API reference

API reference · API

Remember texts, or the facts in a conversation

POST/v1/memoriesAPI key

Embeddings scope; the chat scope too unless infer is false. memories are kept as given; messages are read by a model for at most 20 facts, each with a confidence. A fact like an existing memory of the same user goes to a decision step (ADD, UPDATE, DELETE or NONE against what it was shown); words already kept are NONE with no call. Every model call is a request billed as this key, under strict JSON. async true answers 202 with a memory extraction to follow. A 404 at every path while the operator has not turned memory on.

Request body

application/json, required

Request body fields
FieldTypeWhat it is
space_idstringA space id; the key's default space when absent (made on first use). At most 100 characters.
userstring or nullYour end user these memories are about; the space's own when absent.
memoriesarray of string or object
messagesarray of object
messages[].rolerequiredstringOne of "system", "developer", "user", "assistant", "tool".
messages[].contentrequiredstring or array of any or null
inferbooleanfalse keeps every new text as it is: no model call but the embedding.
metadataobject or null
asyncboolean

Example

{}

Answer 200

Each change the write made.

Headers: x-antimatter-cost-micros

Fields of the 200 answer
FieldTypeWhat it is
object"memory.write"
space_idstring
resultsarray of object
results[].idstring
results[].eventstringOne of "ADD", "UPDATE", "DELETE", "NONE".
results[].memoryobject or null
results[].previous_memorystring or null
factsintegerThe facts read or given, after repeats were dropped.
modelstring or nullThe model that read and decided, if any.
usageobject
usage.cost_microsinteger
usage.requestsarray of string

Answer 202

The conversation, queued.

Fields of the 202 answer
FieldTypeWhat it is
idstringmex_ and 24 hex digits.
object"memory.extraction"
statusstringOne of "pending", "running", "completed", "failed".
space_idstring
resultsarray of any or null
errorstring or null
usageobject
usage.cost_microsinteger

Errors

  • 400OpenAI shaped error.
  • 401OpenAI shaped error.
  • 402OpenAI shaped error.
  • 403OpenAI shaped error.
  • 404OpenAI shaped error.
  • 429Rate limited, or a spent budget or spend cap. The type distinguishes rate_limit_error, policy_exceeded, and spend_cap_exceeded.
  • 502OpenAI shaped error.
  • 503OpenAI shaped error.

Every error answers in one shape, with its type, code and the field it names. The whole list is in the docs' Errors section.

Antimatter