POST/api/v1/record

Write a memory record. Stored in Postgres, classified automatically. No LLM call, no token cost. Returns immediately with the record ID.

Request body

Field	Type	Required	Description
`agent_id`	string	Yes	Identifier for the agent writing this memory. Namespaces queries.
`type`	enum	Yes	`fact` \| `decision` \| `exchange` \| `deliverable` \| `open_item` \| `signal`
`title`	string	Yes	Short summary. Used in search results and UI.
`body`	string	Yes	Full memory content. Max 64KB.
`client`	string	No	Optional client/project tag for filtering.
`metadata`	object	No	Arbitrary JSON. Returned in query results. Not indexed.

Example

curl -X POST https://synapse.by-kit.com/api/v1/record \
  -H "Authorization: Bearer sk_syn_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "scout",
    "type": "decision",
    "title": "Chose PostgreSQL over SQLite",
    "body": "Selected Postgres for multi-tenant isolation. SQLite cannot handle concurrent writes across tenants.",
    "client": "project-alpha",
    "metadata": { "phase": 1, "confidence": "high" }
  }'

Response

{
  "id": "a3f1b9c2-4e5d-4c2b-9f8a-1d2e3f4a5b6c",
  "created_at": "2026-05-20T12:00:00.000Z",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error codes

// 400 — Validation error
{ "error": "invalid_type", "message": "type must be one of: fact, decision, exchange, deliverable, open_item, signal" }

// 400 — Body too large
{ "error": "body_too_large", "message": "body exceeds 64KB limit" }

// 401 — Invalid key
{ "error": "unauthorized", "message": "Invalid API key" }

// 429 — Rate limited
{ "error": "rate_limited", "retry_after": 14 }

Notes

Classification runs asynchronously — the type field you pass is stored as-is. Auto-classification is available via POST /v1/classify if you want a suggestion before writing.
Records are scoped to your tenant. Other API keys cannot read your records.
Every write counts against your monthly record quota.