# Create experiences

## POST `/v1/experiences`

Submit source Experiences for durable Workspace processing. Processing extracts Claims; scheduled consolidation groups them into Engrams. Poll GET /v1/experiences/{id}, or use wait for a bounded processing wait, which does not promise immediate consolidation. For one-shot processing without persistence, use POST /v1/consolidate without workspace.

## Authentication

Use an API key with the AugentaKey authorization scheme. See [Authentication](https://augenta.pages.dev/docs/authentication.md).

## Request example

```bash
curl --fail-with-body -X POST "https://api.augenta.ai/v1/experiences" \
  -H "Authorization: AugentaKey $AUGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "experiences": [
    {
      "src": "service",
      "sid": "handbook-deploys",
      "type": "doc",
      "data": {
        "documentId": "handbook/deploys.md",
        "title": "How we deploy",
        "text": "Merging to main deploys to dev.",
        "capturedAt": "2026-10-14T09:30:00Z"
      }
    }
  ]
}'
```

## Parameters

<a id="request-parameters-wait"></a>

### `request.parameters.wait`

`string` · optional

query parameter. Seconds (0–30) to wait for processing before answering. 200 when every experience finished in time, else 202.

<a id="request-parameters-x-augenta-connector-id"></a>

### `request.parameters.X-Augenta-Connector-Id`

`string` · optional

header parameter. With a person's sign-in, the Connector to write through. Existing Connector keys infer it. Direct keys select an assigned Workspace with the body workspace field (inferred for one assignment) and refuse this header. Keys need an assigned Workspace for this route.

## Body fields

<a id="request-body-workspace"></a>

### `request.body.workspace`

`string` · optional

One Workspace assigned to the key. Required when the key has multiple assignments; inferred for one.

Min length: `1`.

<a id="request-body-experiences"></a>

### `request.body.experiences`

`array<value>` · required

One or more experiences, up to 1,000 steps and data items in all.

Min items: `1`.

<a id="request-body-experiences-src"></a>

### `request.body.experiences.src`

`string` · required

Who composed it. Send `service` from your own code.

Allowed values: `"service"`, `"claude-code"`, `"codex"`.

<a id="request-body-experiences-sid"></a>

### `request.body.experiences.sid`

`string` · required

The session id: one conversation, one agent run, or one document. Experiences that share it are one stream.

Min length: `1`.

<a id="request-body-experiences-proj"></a>

### `request.body.experiences.proj`

`string` · optional

An optional project name, for your own grouping. Defaults to empty.

<a id="request-body-experiences-type"></a>

### `request.body.experiences.type`

`string` · optional

`trajectory` (the default) for conversations and agent runs, `doc` for a document.

<a id="request-body-experiences-events"></a>

### `request.body.experiences.events`

`array<value>` · optional

A trajectory's steps. Required for a trajectory; not allowed on other types.

<a id="request-body-experiences-events-seq"></a>

### `request.body.experiences.events.seq`

`integer` · required

The step's position in the session. Integer; give each step its own, increasing across calls.

<a id="request-body-experiences-events-ts"></a>

### `request.body.experiences.events.ts`

`string` · required

When it happened: ISO-8601 with an offset.

<a id="request-body-experiences-events-kind"></a>

### `request.body.experiences.events.kind`

`string` · required

`msg` for a message; `session` for context such as a system prompt; `tool` for a tool call or result.

Allowed values: `"msg"`, `"tool"`, `"error"`, `"outcome"`, `"session"`.

<a id="request-body-experiences-events-role"></a>

### `request.body.experiences.events.role`

`string` · required

Allowed values: `"user"`, `"assistant"`, `"tool"`, `"system"`.

<a id="request-body-experiences-events-text"></a>

### `request.body.experiences.events.text`

`string` · required

What was said or done. Scrub secrets before sending.

<a id="request-body-experiences-data"></a>

### `request.body.experiences.data`

`value` · optional

Any JSON. A document's content: `{documentId, title?, text, capturedAt?, deleted?}`. Optional on a trajectory, where it is kept as raw telemetry.

## Response 200

Every Experience finished processing within wait.

Content-Type: `application/json`

<a id="response-200-billing"></a>

### `response.200.billing`

`object` · conditional

Present when billing is enabled. USD amount is exact. Receipt references settle only on successful server delivery; retries reuse the original debit.

<a id="response-200-billing-operationid"></a>

### `response.200.billing.operationId`

`string` · always present

<a id="response-200-billing-priceversion"></a>

### `response.200.billing.priceVersion`

`string` · always present

<a id="response-200-billing-sourcetokens"></a>

### `response.200.billing.sourceTokens`

`integer` · always present

Minimum: `0`.

<a id="response-200-billing-memorytokens"></a>

### `response.200.billing.memoryTokens`

`integer` · always present

Minimum: `0`.

<a id="response-200-billing-measuredmemorytokens"></a>

### `response.200.billing.measuredMemoryTokens`

`integer` · always present

Minimum: `0`.

<a id="response-200-billing-replayed"></a>

### `response.200.billing.replayed`

`boolean` · always present

<a id="response-200-billing-complimentary"></a>

### `response.200.billing.complimentary`

`boolean` · conditional

<a id="response-200-billing-ratedamount"></a>

### `response.200.billing.ratedAmount`

`string` · conditional

<a id="response-200-billing-amount"></a>

### `response.200.billing.amount`

`string` · always present

<a id="response-200-billing-receiptids"></a>

### `response.200.billing.receiptIds`

`array<string>` · always present

<a id="response-200-accepted"></a>

### `response.200.accepted`

`integer` · always present

How many experiences were accepted.

<a id="response-200-connectorid"></a>

### `response.200.connectorId`

`string` · conditional

Present for Connector-backed writes.

<a id="response-200-source"></a>

### `response.200.source`

`object` · conditional

Present for writes made with the API key's Workspace permissions, instead of connectorId.

<a id="response-200-source-type"></a>

### `response.200.source.type`

`string` · always present

Allowed values: `"api-key"`.

<a id="response-200-source-id"></a>

### `response.200.source.id`

`string` · always present

<a id="response-200-workspace"></a>

### `response.200.workspace`

`string` · conditional

The destination Workspace for writes made with the API key's Workspace permissions.

<a id="response-200-experiences"></a>

### `response.200.experiences`

`array<value>` · always present

One per experience, in request order.

<a id="response-200-experiences-object"></a>

### `response.200.experiences.object`

`string` · always present

Allowed values: `"experience"`.

<a id="response-200-experiences-id"></a>

### `response.200.experiences.id`

`string` · always present

Poll `GET /v1/experiences/{id}` with it. The same experience sent again gets the same id.

<a id="response-200-experiences-status"></a>

### `response.200.experiences.status`

`string` · always present

Allowed values: `"accepted"`, `"processed"`, `"consolidated"`, `"failed"`.

<a id="response-200-experiences-billingoperationid"></a>

### `response.200.experiences.billingOperationId`

`string` · conditional

Source receipt reference when billing is enabled. It settles with successful durable processing.

<a id="response-200-experiences-claimids"></a>

### `response.200.experiences.claimIds`

`array<string>` · conditional

IDs of Claims extracted from this source, when returned. Read extractedClaims.data or an Engram's claims.data for their text.

## Response 202

Accepted; processing continues.

Content-Type: `application/json`

```json
{
  "accepted": 1,
  "connectorId": "3f6c2b1e-6d0a-4b7e-9a51-2f0c8e7d4a10",
  "experiences": [
    {
      "id": "exp_9b2f6c1e4d7a0b3c5e8f1a2d",
      "status": "accepted"
    }
  ]
}
```

Response fields use the same schema as Response 200.

## Response 400

`invalid_request`: invalid experience envelopes or unsupported fields. Send `{experiences, workspace?}` for durable ingestion; use POST /v1/consolidate for one-shot processing. Unsupported state/snapshot fields are rejected; `wait` must be 0–30; a person's durable call needs `X-Augenta-Connector-Id`.

Content-Type: `application/json`

```json
{
  "error": {
    "code": "invalid_request",
    "message": "experiences[0]: a trajectory needs a non-empty events array",
    "retryable": false
  },
  "requestId": "req_7f9c2b1e-6d0a-4b7e-9a51-2f0c8e7d4a10"
}
```

<a id="response-400-error"></a>

### `response.400.error`

`object` · always present

<a id="response-400-error-code"></a>

### `response.400.error.code`

`string` · always present

Stable. The Errors page lists every code.

<a id="response-400-error-message"></a>

### `response.400.error.message`

`string` · always present

Human-readable. May change; don't parse it.

<a id="response-400-error-retryable"></a>

### `response.400.error.retryable`

`boolean` · always present

<a id="response-400-error-retryafterseconds"></a>

### `response.400.error.retryAfterSeconds`

`integer` · conditional

Capacity retry interval, also present as Retry-After before stream headers commit. SSE error events retain this field after HTTP 200 is committed.

Minimum: `1`.

<a id="response-400-error-billingurl"></a>

### `response.400.error.billingUrl`

`string` · conditional

Top-up action when error.code is insufficient_balance (HTTP 402).

<a id="response-400-requestid"></a>

### `response.400.requestId`

`string` · always present

The request's id, as in the `X-Request-Id` response header.

## Response 401

`unauthenticated`: missing, invalid or revoked credential.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 402

insufficient_balance: add credits before retrying the same source revision.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 403

`forbidden`: the Connector does not accept experiences from this credential. `connector_inactive`: the Connector is disabled.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 413

`payload_too_large`: an experience is over the 1 MiB limit, or the body is too large.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 429

`rate_limited` (retryable): wait the number of seconds in `Retry-After`. `at_capacity` (retryable): the service is temporarily full; wait the same way.

Content-Type: `application/json`

```json
{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded",
    "retryable": true
  },
  "requestId": "req_7f9c2b1e-6d0a-4b7e-9a51-2f0c8e7d4a10"
}
```

Response fields use the same schema as Response 400.

## Response 500

`internal_error`: an unexpected failure; quote the `requestId`.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 501

`stateless_not_available`: Consolidate is not configured in this environment.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 503

`service_unavailable` (retryable): retry the same request; it is safe. `workos_unavailable` (retryable).

Content-Type: `application/json`

Response fields use the same schema as Response 400.
