Create a chat completion

Drop-in replacement for OpenAI's /v1/chat/completions, with Truememory's persona and memory layers applied to every turn. Supports tools, streaming and all standard parameters.

The response comes in one of two shapes, depending on stream:

stream: false (default) — a single JSON ChatCompletionResponse.
stream: true — text/event-stream of data: lines, each an OpenAI-style chunk, terminated by data: [DONE].

POST

https://truememory-api.mvstg.com/v1/chat/completions

View as Markdown

Authorization

HTTPBearerHTTPrequired

Header parameters

x-agent-idoptional
TIE agent to use
One of the following:
string
null
}
x-app-idoptional
Application ID for scoping threads
One of the following:
string
null
}
X-On-Behalf-Ofoptional
One of the following:
string
null
}
X-External-User-Idoptional
One of the following:
string
null
}
X-App-Idoptional
One of the following:
string
null
}

Request bodyJSONrequired

modelstringrequired
Model to use, e.g. 'anthropic/claude-sonnet-4-6'
messagesarray ofobjectrequired
- rolesystemordeveloperoruserorassistantortoolrequired
- contentoptional
  One of the following:
  string
  array<one of>
  null
- tool_callsoptional
  One of the following:
  array<object>
  null
- tool_call_idoptional
  One of the following:
  string
  null
- nameoptional
  One of the following:
  string
  null
- cache_controloptional
  Anthropic prompt-caching marker applied to the whole message. Example: {"type": "ephemeral"}. Per Anthropic semantics, the marker attaches to the last content block, caching everything up to and including that block. Use this for the simple case (string-content messages); for fine-grained control, set cache_control on individual content parts. Forwarded to the underlying provider via the LangChain message's additional_kwargs.
  
  One of the following:
  object
  null
}
toolsoptional
One of the following:
array<unknown>
null
}
streamoptionalboolean
default: false
stream_optionsoptional
One of the following:
StreamOptions
include_usageoptionalboolean
default: false
null
}
temperatureoptional
One of the following:
number
null
}
max_tokensoptional
One of the following:
integer
null
}
top_poptional
One of the following:
number
null
}
seedoptional
One of the following:
integer
null
}
stopoptional
One of the following:
array<string>
string
null
}
max_history_tokensoptional
Cap the replayed thread history to roughly this many tokens, keeping the most recent turns (the window starts on a human turn). Older turns are dropped from the replay — callers that set this should supply their own running summary so older context is preserved. Omit (default) to replay the full history unchanged.
One of the following:
integer
null
}
system_prompt_cache_contractoptionallegacyorexplicit
How to read multi-block system content. "legacy" (default, unchanged behaviour): a block list with no cache_control marker anywhere is treated as entirely STABLE — the historical reading, so existing callers that use block lists for structure are unaffected. "explicit": markers are the caller's cacheability declaration — blocks through the last marked one are stable, later blocks are dynamic, and a list with NO marker means nothing is cacheable. Opt in only if you place markers deliberately: under "explicit" an unmarked system prompt is delivered as per-request context inside the user turn, not as a system message.

default: "legacy"
prompt_cache_keyoptional
OpenAI cache-routing key (GPT-5.6+), forwarded verbatim to the provider so same-conversation requests land on the same cache shard. Ignored for non-OpenAI models. Send an opaque, privacy-safe value (a hash, never raw user/thread identifiers).
One of the following:
string
null
}
context_managementoptional
Context-management strategies for this request. At most one entry is supported. Include a {"type": "compaction", ...} entry to enable thread compaction: when the upcoming request is over budget (compact_threshold when set, else the model's context window minus a buffer), older turns fold into a rolling summary checkpoint before the model call runs; subsequent turns replay the checkpoint plus newer messages instead of the full transcript. The thread's stored history is never modified. Omit to disable.
One of the following:
array<unknown>
null
}
thread_idoptional
TIE thread ID for state persistence
One of the following:
string
null
}
parent_message_idoptional
ID of the last stored message the client received. When set, anything already stored after it is not appended again, so a request that failed mid-run can be re-sent unchanged. messages holds the messages after it, optionally preceded by replayed history that ends at it; that history is dropped exactly as it is without this field. Use the message_id from the previous response. Ignored without thread_id: a turn with no thread has no stored state.
One of the following:
string
null
}
storeoptionalboolean
Whether to persist this turn to the user's chat history. Default: true. Set to false for system-internal or ephemeral calls. Memory injection (pre-LLM) and usage tracking are unaffected.

default: true
persona_idoptional
Persona to use. Falls back to the user's active persona if omitted.
One of the following:
string
null
}
metadataoptional
Up to 16 key-value pairs attached to this request. Persisted with the thread and returned in history.
One of the following:
map<string>
null
}
skill_instructionsoptional
Caller-composed skill prompt. Injected after persona, before memory context. Never replaces persona or base instructions — purely additive.
One of the following:
string
null
}
skill_selectionoptionalofforauto
auto lets Truememory pick skills for this turn by matching the user's message against each visible skill's use_case and detection_patterns. Only skills the caller could already list are considered, and only ones carrying trigger data. Combines with skills: explicit keys always apply, matches are added after them. Defaults to off — no existing caller changes behaviour.

default: "off"
skillsoptionalarray ofstring
Skill keys to resolve from the registry and inject, in the order given. Truememory reads each skill's stored prompt, so the registry stays authoritative instead of each caller pasting a copy. A key you cannot see is a 404, never a silent drop. Resolved prompts are injected before skill_instructions, which still works and can be used alongside them for per-request text.
skill_filesoptionalboolean
Let the model read the files of this turn's skills (from skills and skill_selection): each such skill's file list follows its prompt, and the model gets a read_skill_file tool. Off by default, so a skill injects only its prompt, as before. Ignored on a deployment without skill file storage.

default: false
memoryoptional
Per-request memory controls. Defaults to read/write enabled for user-scoped requests.
One of the following:
MemoryOptions
readoptionalboolean
default: true
writeoptionalboolean
default: true
null
}
tool_callbackoptional
Callback configuration for tool execution. When set, TIE runs the tool loop and executes caller-defined tools via HTTPS POST to {base_url}/{tool_name}. tools must also be provided.
One of the following:
ToolCallback
base_urlstringrequired
Base URL for tool execution. Must be HTTPS and on the allowlist.

format: uri · maxLength: 2083 · minLength: 1
auth_tokenstringrequired
Short-lived bearer token TIE forwards on every tool call.

maxLength: 8192 · minLength: 1
timeout_msoptionalinteger
Per-call timeout in milliseconds (default 8000).

maximum: 60000 · minimum: 100 · default: 8000
null
}
extra_contextoptional
Free-form caller-provided context injected into the system prompt before tool definitions. TIE does not interpret it.
One of the following:
object
null
}
skill_idoptional
Skill ID whose associated knowledge packs are searched and injected into the system prompt. Works alongside skill_instructions — neither requires the other.
One of the following:
string
null
}
knowledge_pack_idsoptional
Explicit knowledge pack IDs to search. Combined with skill_id when both are provided. No document context is injected when both are absent.
One of the following:
array<string>
null
}
brain_idoptional
Brain ID whose knowledge packs are searched and injected into the system prompt. Resolved to knowledge_pack_ids before context injection. Ignored when knowledge_pack_ids is also provided. Singular alias for brain_ids — when both are set, their union is resolved.
One of the following:
string
null
}
brain_idsoptional
Brain IDs whose knowledge packs are searched and injected into the system prompt. All named brains are resolved to one deduplicated set of knowledge_pack_ids before context injection. Every ID must be readable by the caller — an unknown or unreachable one is a 404, not a silent drop. Ignored when knowledge_pack_ids is also provided.
One of the following:
array<string>
null
}
mind_idsoptional
Minds whose memory namespaces are blended into per-message retrieval alongside the user's own memory. Each is resolved through the mind read gate, so only minds the caller can actually read take effect; an unknown or unreachable id is a 404, not a silent drop. Namespace facts appear in the injected memory context — conversation ingestion still writes only to the user's own graph.
One of the following:
array<string>
null
}
graph_idsoptional
Raw shared knowledge-graph namespaces, by slug. Service principals only — a namespace slug carries no ownership, so honouring one from a user token would let any caller read any namespace they can guess. First-party callers name minds instead, via mind_ids.
One of the following:
array<string>
null
}

Returns

200

A chat completion. JSON when stream is false; an SSE stream of chunks when it is true.

JSON

idstringrequired
createdintegerrequired
modelstringrequired
choicesarray ofobjectrequired
- messageobjectrequired
  roleoptionalstring
  default: "assistant"
  contentoptional
  One of the following:
  string
  null
  tool_callsoptional
  One of the following:
  array<object>
  null
- indexoptionalinteger
  default: 0
- finish_reasonoptional
  default: "stop"
  One of the following:
  string
  null
}
objectoptionalstring
default: "chat.completion"
usageoptionalobject
metadataoptional
One of the following:
map<string>
null
}
context_managementoptional
One of the following:
array<unknown>
null
}
message_idoptional
ID of the last message stored on the thread by this turn. Send it as parent_message_id on the next request. Streaming responses carry it as a top-level message_id on the chunk with a non-error finish_reason. Only set for requests with a thread_id.
One of the following:
string
null
}

422

Validation Error

JSON

detailoptionalarray ofobject
- locarray ofrequired
  One of the following:
  string
  integer
- msgstringrequired
- typestringrequired
- inputoptionalunknown
- ctxoptionalobject
}