Skip to content
AugentaDocsOpen console ↗
Experiences

Documentation

API reference
View Markdown

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.

json
{
  "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:

json
{
  "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

EndpointPurpose
POST /v1/experiencesAdd 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

FieldWhat to send
srcWho composed it. Send service from your own code.
sidThe session: one conversation, one agent run, or one document. Keep it stable: everything sent under one sid is one stream.
projOptional. A project name for your own grouping.
typedoc for a document. Leave it out (or send trajectory) for a conversation or agent run.
eventsA conversation's steps. Required for a trajectory.
dataA 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:

  • documentId names the document. Keep it, and sid, the same for every version. Using the documentId as the sid is simplest.
  • text is the content, Markdown or plain text. One experience can be up to 1 MiB.
  • title gives 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.
  • capturedAt orders 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:

json
{
  "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.

json
{
  "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."
    }
  ]
}
  • seq is yours: an integer, increasing across the whole conversation. Each experience is named by its seq range.
  • Send each turn once. When the conversation continues, send only the new messages, with the next seqs, under the same sid. Send a question and its answer together, in one experience: messages in one experience are read together.
  • kind is msg for a message. Use session for context such as a system prompt, and tool for a tool call or result. Tool and error steps are stored, but claims are extracted only from the other steps.
  • role is user, assistant, system or tool. ts needs an offset.
  • Scrub secrets from text before sending.

Follow an experience

GET /v1/experiences/{id} answers where it stands:

StatusMeaning
acceptedReceived, waiting to be processed.
processedIts claims are extracted and stored, and recall can find them. claimCount says how many, processedAt when.
consolidatedA completed consolidation covers its processed claims. Recall does not wait for this.
failedIt 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.