# 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](https://augenta.pages.dev/docs/agent-memory.md) for the per-turn pattern, and
[Using the APIs together](https://augenta.pages.dev/docs/memory-flows.md) to compare it with Consolidate.

Once an experience is processed, its claims are searchable through [Recall](https://augenta.pages.dev/docs/recall.md), 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](https://augenta.pages.dev/docs/api-reference/experience-object.md) for its available operations, all attributes and an example object.

## Endpoints

| Endpoint                                                                              | Purpose                                           |
| ------------------------------------------------------------------------------------- | ------------------------------------------------- |
| [`POST /v1/experiences`](https://augenta.pages.dev/docs/api-reference/create-experiences.md) | Add source material to a Workspace.               |
| [`GET /v1/experiences/{id}`](https://augenta.pages.dev/docs/api-reference/get-experience.md) | 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`:

* `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 `seq`s, 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:

| 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](https://augenta.pages.dev/docs/experiences.md#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](https://augenta.pages.dev/docs/workspaces.md).

Scrub secrets and anything you may need to delete individually before sending.

## One-shot processing

To process input without storing it, use [Consolidate](https://augenta.pages.dev/docs/consolidate.md) without `workspace`.
Experiences always stores what it accepts.
