Neutrally API

Read and write memory items programmatically. Use this API to integrate Neutrally with any tool, agent, or workflow.

Authentication

All requests require a Bearer token in the Authorization header. Use your CLI token (from npx neutrally setup) or a Supabase JWT.

Authorization: Bearer ntrl_your_token_here

Memory Types

project

decision

preference

fact

note

Each memory item has a type, title, content, optional metadata (JSON), and can be pinned.

Endpoints

GET

/api/v1/memory

List all memory items. Filter by type with ?type=project

Query params

?type=project|decision|preference|fact|note

Response

{ items: [...], count: 5 }

POST

/api/v1/memory

Create a new memory item.

Request body

{ "type": "decision", "title": "Use Supabase", "content": "Chose Supabase for fast iteration" }

Response

{ id, type, title, content, ... }

PATCH

/api/v1/memory

Update an existing memory item.

Request body

{ "id": "uuid", "title": "Updated title", "content": "New content" }

Response

{ id, type, title, content, ... }

DELETE

/api/v1/memory?id=uuid

Delete a memory item by ID.

Response

{ deleted: true }

Example: Save a decision from your agent

curl -X POST https://neutrally.app/api/v1/memory \
  -H "Authorization: Bearer ntrl_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "decision",
    "title": "Database: Supabase",
    "content": "Chose Supabase over Firebase for RLS and Postgres support"
  }'

Base URL: https://neutrally.app