Experiences
Submit source documents and conversations, then follow their processing.
POST /v1/experiences adds source material to a Workspace: conversations, agent runs and
documents. It answers as soon as the input is stored and processes it in the background, so it is
the call to make after every agent turn. An experience is one unit of source data. See
Add memory to your agent for the per-turn pattern, and
Using the APIs together to compare it with Consolidate.
Once an experience is processed, its claims are searchable through Recall, before they are consolidated into an engram. Grouping them into engrams follows in the background.
{
"experiences": [
{
"src": "service",
"sid": "handbook/deploys.md",
"type": "doc",
"data": {
"documentId": "handbook/deploys.md",
"title": "How we deploy",
"text": "Merging to main deploys checkout to dev.",
"capturedAt": "2026-10-14T09:30:00Z"
}
}
]
}
The response is 202, with an id for each experience, in order:
{
"accepted": 1,
"source": {
"type": "api-key",
"id": "sk-aug-example-public-id"
},
"workspace": "ws-product",
"experiences": [
{
"id": "exp_9b2f6c1e4d7a0b3c5e8f1a2d",
"status": "accepted",
"object": "experience"
}
]
}
See the Experience object for its available operations, all attributes and an example object.
Endpoints
| Endpoint | Purpose |
|---|---|
POST /v1/experiences | Add source material to a Workspace. |
GET /v1/experiences/{id} | Retrieve a stored Experience’s processing status. |
The POST response lists one reference per experience (object, id, status); GET adds its type, Workspace and processing times. There is no endpoint to list, edit or delete experiences.
The envelope
| Field | What to send |
|---|---|
src | Who composed it. Send service from your own code. |
sid | The session: one conversation, one agent run, or one document. Keep it stable: everything sent under one sid is one stream. |
proj | Optional. A project name for your own grouping. |
type | doc for a document. Leave it out (or send trajectory) for a conversation or agent run. |
events | A conversation's steps. Required for a trajectory. |
data | A document's content. Any JSON; on a trajectory it's kept as raw telemetry. |
Name the Workspace in the body's workspace field. You can leave it out when the key has exactly one assigned Workspace. A key with no assigned Workspace can't add experiences.
The body is {experiences} with an optional workspace. Any other top-level field is refused with 400 invalid_request rather than ignored, so a misspelt field never stores what you meant to send somewhere else. wait is a query parameter, not a body field.
Documents
A document is type: "doc" with its content in data:
documentIdnames the document. Keep it, andsid, the same for every version. Using thedocumentIdas thesidis simplest.textis the content, Markdown or plain text. One experience can be up to 1 MiB.titlegives an inline document a readable name alongside its text. When a file path or filename is supplied, that name takes precedence. It does not change the document's identity.capturedAtorders versions. Send ISO-8601 with an offset.
Update a document by sending it again with a later capturedAt. What Augenta learned from the old version is replaced. A version with an earlier capturedAt than the one stored changes nothing, so a late retry can't undo an update.
Forget a document by sending "deleted": true with a later capturedAt, and no text:
{
"src": "service",
"sid": "handbook/deploys.md",
"type": "doc",
"data": {
"documentId": "handbook/deploys.md",
"deleted": true,
"capturedAt": "2026-10-20T08:00:00Z"
}
}
A document belongs to whoever first wrote it: the person or API key that wrote it. A write from anyone else is still accepted (202), but it changes nothing: GET /v1/experiences/{id} reports status: "failed" with error.code document_conflict.
Conversations
A conversation is a trajectory: its messages are events, one step each.
{
"src": "service",
"sid": "chat-2026-10-14-ada",
"events": [
{
"seq": 1,
"ts": "2026-10-14T09:29:10Z",
"kind": "msg",
"role": "user",
"text": "Can I deploy checkout on Fridays?"
},
{
"seq": 2,
"ts": "2026-10-14T09:29:12Z",
"kind": "msg",
"role": "assistant",
"text": "Only to dev; production waits until Monday."
}
]
}
seqis yours: an integer, increasing across the whole conversation. Each experience is named by itsseqrange.- Send each turn once. When the conversation continues, send only the new messages, with the next
seqs, under the samesid. Send a question and its answer together, in one experience: messages in one experience are read together. kindismsgfor a message. Usesessionfor context such as a system prompt, andtoolfor a tool call or result. Tool anderrorsteps are stored, but claims are extracted only from the other steps.roleisuser,assistant,systemortool.tsneeds an offset.- Scrub secrets from
textbefore sending.
Follow an experience
GET /v1/experiences/{id} answers where it stands:
| Status | Meaning |
|---|---|
accepted | Received, waiting to be processed. |
processed | Its claims are extracted and stored, and recall can find them. claimCount says how many, processedAt when. |
consolidated | A completed consolidation covers its processed claims. Recall does not wait for this. |
failed | It could not be processed. error.code and error.message say why. |
At processed, Recall searches its claims, including those not yet in an engram.
consolidated follows in the background: every experience that changes the Workspace's claims
starts a consolidation, whatever the Workspace's cadence. An experience with no claims needs no
consolidation and can stay processed. Acceptance is not a guarantee of completion time.
To wait without polling, add ?wait= (up to 30 seconds) to the POST. It answers 200 once every experience is processed, or 202 with their statuses when time runs out.
Retries
Sending the same experience again is safe: it lands in the same place, gets the same id, and isn't processed twice. If a request fails or times out, send it again exactly as it was. Build the body once and reuse it: the same conversation steps (sid and seq range) sent again with different events are refused with 409 conflict, and the steps accepted first stay. Give every new step a new seq: a turn that reuses earlier numbers is refused, not stored.
A conversation's id comes from its sid, its seq range and its first message's ts, so the same body sent again on any day gets the same id. A document's id includes the UTC day it was accepted, so retry a document promptly: a retry on a later day is accepted as a new experience.
Deleting data
- A document is forgotten by sending it again with
"deleted": true(see Documents). - A conversation can't be deleted on its own yet: once sent, its claims stay in the Workspace.
- Everything in a Workspace is removed by deleting the Workspace. An organization owner or admin archives it, then deletes its data; see Workspaces.
Scrub secrets and anything you may need to delete individually before sending.
One-shot processing
To process input without storing it, use Consolidate without workspace.
Experiences always stores what it accepts.