Project memory

Durable per-task turn history (meta, summary, artifacts) and a project digest, scoped to tenant/project. Retained 30 days by default.

Every request needs a credential — see Authentication.

Method	Path	Summary
`GET`	`/sandbox/memory/v1/project.md`	Project digest: one section per task with its latest summary
`GET`	`/sandbox/memory/v1/tasks`	List tasks in project memory (most recently updated first)
`DELETE`	`/sandbox/memory/v1/tasks/{task_id}`	Delete a task's memory (owner, or project_admin and above)
`GET`	`/sandbox/memory/v1/tasks/{task_id}`	Task index: turns, meta, artifact names
`GET`	`/sandbox/memory/v1/tasks/{task_id}/turns/{turn}`	One turn: meta, summary, artifact list
`PUT`	`/sandbox/memory/v1/tasks/{task_id}/turns/{turn}`	Upsert one turn's meta + summary; refreshes the task index and project.md
`GET`	`/sandbox/memory/v1/tasks/{task_id}/turns/{turn}/artifacts/{name}`	Download a turn artifact (stored Content-Type)
`PUT`	`/sandbox/memory/v1/tasks/{task_id}/turns/{turn}/artifacts/{name}`	Store a turn artifact (raw body, Content-Type kept, max 50 MiB)

Common headers

Accepted on every endpoint on this page.

Name	In	Type	Required	Description
`x-correlation-id`	header	string	no	End-to-end correlation id for this eval run. When set, the gateway and downstream services honor it verbatim in logs, Cloud Trace span attributes, async job payloads, and Langfuse trace.id. When omitted, the gateway generates a ULID and echoes it on the response.
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Endpoints

Project digest: one section per task with its latest summary

GET /sandbox/memory/v1/project.md

Responses

Status	Description	Body
`200`	Successful Response	string
`422`	Validation Error	HTTPValidationError

List tasks in project memory (most recently updated first)

GET /sandbox/memory/v1/tasks

Parameters

Name	In	Type	Required	Description
`limit`	query	integer	no
`cursor`	query	string \| null	no

Responses

Status	Description	Body
`200`	Successful Response	TaskList
`422`	Validation Error	HTTPValidationError

Delete a task's memory (owner, or project_admin and above)

DELETE /sandbox/memory/v1/tasks/{task_id}

Parameters

Name	In	Type	Required	Description
`task_id`	path	string	yes	Task id: [A-Za-z0-9][A-Za-z0-9._-]{0,127}

Responses

Status	Description	Body
`204`	Successful Response	—
`422`	Validation Error	HTTPValidationError

Task index: turns, meta, artifact names

GET /sandbox/memory/v1/tasks/{task_id}

Parameters

Name	In	Type	Required	Description
`task_id`	path	string	yes	Task id: [A-Za-z0-9][A-Za-z0-9._-]{0,127}

Responses

Status	Description	Body
`200`	Successful Response	object
`422`	Validation Error	HTTPValidationError

One turn: meta, summary, artifact list

GET /sandbox/memory/v1/tasks/{task_id}/turns/{turn}

Parameters

Name	In	Type	Required	Description
`task_id`	path	string	yes	Task id: [A-Za-z0-9][A-Za-z0-9._-]{0,127}
`turn`	path	integer	yes	Turn number (stored zero-padded, 0000-9999)

Responses

Status	Description	Body
`200`	Successful Response	TurnRecord
`422`	Validation Error	HTTPValidationError

Upsert one turn's meta + summary; refreshes the task index and project.md

PUT /sandbox/memory/v1/tasks/{task_id}/turns/{turn}

Parameters

Name	In	Type	Required	Description
`task_id`	path	string	yes	Task id: [A-Za-z0-9][A-Za-z0-9._-]{0,127}
`turn`	path	integer	yes	Turn number (stored zero-padded, 0000-9999)

Request body

application/json, required — PutTurnRequest

Field	Type	Required	Description
`meta`	TurnMeta	no	Run metadata for one turn. Every field is optional; unknown keys are kept.
`summary_md`	string	no	Markdown summary of the turn (max 1 MiB). Default: "".

Responses

Status	Description	Body
`200`	Successful Response	TurnRecord
`422`	Validation Error	HTTPValidationError

Download a turn artifact (stored Content-Type)

GET /sandbox/memory/v1/tasks/{task_id}/turns/{turn}/artifacts/{name}

Parameters

Name	In	Type	Required	Description
`task_id`	path	string	yes	Task id: [A-Za-z0-9][A-Za-z0-9._-]{0,127}
`turn`	path	integer	yes	Turn number (stored zero-padded, 0000-9999)
`name`	path	string	yes	Artifact name: [A-Za-z0-9._-]{1,128}

Responses

Status	Description	Body
`200`	Successful Response	—
`422`	Validation Error	HTTPValidationError

Store a turn artifact (raw body, Content-Type kept, max 50 MiB)

PUT /sandbox/memory/v1/tasks/{task_id}/turns/{turn}/artifacts/{name}

Parameters

Name	In	Type	Required	Description
`task_id`	path	string	yes	Task id: [A-Za-z0-9][A-Za-z0-9._-]{0,127}
`turn`	path	integer	yes	Turn number (stored zero-padded, 0000-9999)
`name`	path	string	yes	Artifact name: [A-Za-z0-9._-]{1,128}

Request body

application/octet-stream, required

Responses

Status	Description	Body
`200`	Successful Response	ArtifactRecord
`422`	Validation Error	HTTPValidationError

Schemas

The object shapes referenced above.

ArtifactRecord

Field	Type	Required
`name`	string	yes
`content_type`	string	yes
`size`	integer	yes
`updated_at`	string \| null	no
`task_id`	string	yes
`turn`	integer	yes

HTTPValidationError

Field	Type	Required	Description
`detail`	ValidationError[]	no

MemoryArtifact

Field	Type	Required
`name`	string	yes
`content_type`	string	yes
`size`	integer	yes
`updated_at`	string \| null	no

PutTurnRequest

Field	Type	Required	Description
`meta`	TurnMeta	no	Run metadata for one turn. Every field is optional; unknown keys are kept.
`summary_md`	string	no	Markdown summary of the turn (max 1 MiB). Default: "".

TaskList

Field	Type	Required	Description
`tasks`	TaskSummary[]	yes
`total`	integer	yes
`next_cursor`	string \| null	no	Pass back as ?cursor= for the next page; null at the end.

TaskSummary

Field	Type	Required
`task_id`	string	yes
`latest_turn`	integer \| null	no
`turn_count`	integer \| null	no
`updated_at`	string \| null	no
`retain_until`	string \| null	no

TurnMeta

Run metadata for one turn. Every field is optional; unknown keys are kept.

Field	Type	Required	Description
`agent_id`	string \| null	no
`model`	string \| null	no
`job_id`	string \| null	no
`sandbox_id`	string \| null	no
`commit`	string \| null	no
`exit_code`	integer \| null	no
`started_at`	string \| number \| null	no	ISO 8601 or epoch
`ended_at`	string \| number \| null	no	ISO 8601 or epoch
`tokens`	integer \| object \| null	no
`cost`	number \| object \| null	no
`claude_session_id`	string \| null	no

TurnRecord

Field	Type	Required
`task_id`	string	yes
`turn`	integer	yes
`meta`	object	yes
`summary_md`	string	yes
`artifacts`	MemoryArtifact[]	yes
`created_at`	string \| null	no
`updated_at`	string \| null	no
`retain_until`	string \| null	no

ValidationError

Field	Type	Required
`loc`	string \| integer[]	yes
`msg`	string	yes
`type`	string	yes
`input`	any	no
`ctx`	object	no

Machine-readable spec: OpenAPI YAML.

Project memory

On this page