API reference

Memory for agents. Call decorate before every model call and submit what it returns; report the reply after.

Base URL: https://api.threadlessai.com/v1. Version 1.0.0. The raw spec is at /openapi/runtime.yaml.

Authenticate every request with a project key: Authorization: Bearer tl_live_… (or tl_test_…). Errors share one shape, Error, with a hint saying what to do about it.

Operations

Operation	Method and path	Summary
createMemory	`POST /memories`	Create a memory: one per conversation.
getMemory	`GET /memories/{memory_id}`	A memory's size and activity.
deleteMemory	`DELETE /memories/{memory_id}`	Delete a memory and everything it holds. Cannot be undone.
decorate	`POST /memories/{memory_id}/decorate`	Before every model call: hand over what is new, get back the request to submit.
report	`POST /memories/{memory_id}/report`	After the model replies: hand over the reply. Returns at once.
exportMemory	`GET /memories/{memory_id}/export`	Everything a memory holds: messages, episodes and facts.

createMemory

POST https://api.threadlessai.com/v1/memories

Create a memory: one per conversation.

Request body (optional): CreateMemoryRequest

Status	Meaning	Body
201	Created.	Memory
400	The request is malformed.	Error
401	The API key is missing or revoked.	Error
404	No memory with this id in this project.	Error
429	Too many requests, or the plan quota is used up.	Error

getMemory

GET https://api.threadlessai.com/v1/memories/{memory_id}

A memory's size and activity.

Parameter	In	Type	Required
`memory_id`	path	string `^mem_[A-Za-z0-9]{24}$`	yes

Status	Meaning	Body
200	The memory.	Memory
400	The request is malformed.	Error
401	The API key is missing or revoked.	Error
404	No memory with this id in this project.	Error
429	Too many requests, or the plan quota is used up.	Error

deleteMemory

DELETE https://api.threadlessai.com/v1/memories/{memory_id}

Delete a memory and everything it holds. Cannot be undone.

Parameter	In	Type	Required
`memory_id`	path	string `^mem_[A-Za-z0-9]{24}$`	yes

Status	Meaning	Body
204	Deleted and verified gone.	none
400	The request is malformed.	Error
401	The API key is missing or revoked.	Error
404	No memory with this id in this project.	Error
429	Too many requests, or the plan quota is used up.	Error

decorate

POST https://api.threadlessai.com/v1/memories/{memory_id}/decorate

Before every model call: hand over what is new, get back the request to submit.

Returns the full request body for OpenAI: history with forgotten parts already out of view, remembered facts and recall in place, and the note ask when history is leaving. The Server-Timing header carries each step.

Parameter	In	Type	Required
`memory_id`	path	string `^mem_[A-Za-z0-9]{24}$`	yes

Request body: DecorateRequest

Status	Meaning	Body
200	The request to submit.	DecorateResult
400	The request is malformed.	Error
401	The API key is missing or revoked.	Error
404	No memory with this id in this project.	Error
429	Too many requests, or the plan quota is used up.	Error

report

POST https://api.threadlessai.com/v1/memories/{memory_id}/report

After the model replies: hand over the reply. Returns at once.

Parameter	In	Type	Required
`memory_id`	path	string `^mem_[A-Za-z0-9]{24}$`	yes

Request body: ReportRequest

Status	Meaning	Body
202	Accepted; the work runs in the background.	ReportResult
400	The request is malformed.	Error
401	The API key is missing or revoked.	Error
404	No memory with this id in this project.	Error
429	Too many requests, or the plan quota is used up.	Error

exportMemory

GET https://api.threadlessai.com/v1/memories/{memory_id}/export

Everything a memory holds: messages, episodes and facts.

Parameter	In	Type	Required
`memory_id`	path	string `^mem_[A-Za-z0-9]{24}$`	yes

Status	Meaning	Body
200	The export.	MemoryExport
400	The request is malformed.	Error
401	The API key is missing or revoked.	Error
404	No memory with this id in this project.	Error
429	Too many requests, or the plan quota is used up.	Error

Schemas

Error

Field	Type	Required	Description
`error`	object	yes
`error.code`	`"invalid_request"` or `"unauthorized"` or `"forbidden"` or `"not_found"` or `"conflict"` or `"rate_limited"` or `"quota_exceeded"` or `"internal"`	yes
`error.message`	string	yes
`error.hint`	string	no	What to do about it.

CreateMemoryRequest

Field	Type	Required	Description
`metadata`	map of string, at most 512	no	Up to 16 string pairs of your own, such as your conversation id.

DecorateRequest

Field	Type	Required	Description
`format`	`"chat.completions"` or `"responses"`	yes	The OpenAI API the request is for: Chat Completions (`messages`) or Responses (`input` items).
`messages`	array of object or object	yes	Everything new since the last call: the reply plus the user message, or the reply plus tool results. System and developer messages are the instructions: the latest set replaces the stored one and always leads the request.
`messages[]`	object		A Chat Completions message, exactly as it would be sent to OpenAI.
`messages[]`	object		A Responses input item (message, function_call, function_call_output, reasoning, …).
`request`	object	yes	The rest of the request body as it would be sent to OpenAI (model, tools, tool_choice, temperature, instructions, …), without the history. `previous_response_id` and `store` are dropped.
`request.model`	string	yes

DecorateResult

Field	Type	Required	Description
`request`	object	yes	The request body, ready to submit to OpenAI with your own key.
`memory`	object	yes
`memory.id`	string `^mem_[A-Za-z0-9]{24}$`	yes	A memory id, as `POST /v1/memories` returned it.
`memory.revision`	integer	yes	Increases with every change to the memory.
`memory.turn`	integer	yes	The current user turn, counting from 1.
`memory.notes_requested`	boolean	yes	True when this request asks the model for notes on history leaving live context. The model answers with the note tool.
`memory.recalled`	integer	yes	Facts and passages recalled into this request.
`memory.facts_in_view`	integer	yes	Remembered facts shown in this request.
`memory.tokens`	integer	yes	Our estimate of the request size, in tokens.

Memory

Field	Type	Required	Description
`id`	string `^mem_[A-Za-z0-9]{24}$`	yes	A memory id, as `POST /v1/memories` returned it.
`object`	`"memory"`	yes
`created_at`	string (date-time)	yes
`last_activity_at`	string (date-time) or null	yes
`metadata`	map of string	yes
`turns`	integer	yes
`messages`	integer	yes
`episodes`	object	yes
`episodes.live`	integer	yes	In live context, messages and all.
`episodes.sealed`	integer	yes	Messages out of view; their facts still shown.
`episodes.forgotten`	integer	yes	Out of view entirely; held in long-term memory for recall.
`facts`	integer	yes
`bytes`	integer	yes	Stored size, the figure storage is billed on.

MemoryExport

Field	Type	Required
`memory`	Memory	yes
`messages`	array of object	yes
`messages[].seq`	integer	yes
`messages[].turn`	integer	yes
`messages[].at`	string (date-time)	yes
`messages[].item`	object	yes
`episodes`	array of object	yes
`episodes[].id`	integer	yes
`episodes[].state`	`"live"` or `"leaving"` or `"sealed"` or `"forgotten"`	yes
`episodes[].first_turn`	integer	yes
`episodes[].last_turn`	integer	yes
`episodes[].encoded_at`	string (date-time)	yes
`episodes[].message_seqs`	array of integer	yes
`facts`	array of object	yes
`facts[].id`	string	yes
`facts[].text`	string	yes
`facts[].entities`	array of string	yes
`facts[].milestone`	boolean	yes
`facts[].written_by`	`"model"` or `"system"`	yes
`facts[].written_at`	string (date-time)	yes

ReportRequest

Field	Type	Required	Description
`format`	`"chat.completions"` or `"responses"`	yes	The OpenAI API the request is for: Chat Completions (`messages`) or Responses (`input` items).
`reply`	object	yes	The provider response, exactly as OpenAI returned it (usage included).

ReportResult

Field	Type	Required	Description
`accepted`	`true`	yes
`revision`	integer	yes