Skip to content
AugentaDocsOpen console ↗
Create experiences

Documentation

API reference
View Markdown

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

Send your API key with the AugentaKey authorization scheme. Workspace requests must target a Workspace assigned to the key. See authentication and permissions.

Request

Parameters

waitstringoptional

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

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

workspacestringoptional

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

Min length: 1

experiencesarrayrequired

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

Min items: 1

Show item fields
srcstringrequired

Who composed it. Send service from your own code.

Allowed: "service""claude-code""codex"

sidstringrequired

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

Min length: 1

projstringoptional

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

typestringoptional

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

eventsarrayoptional

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

Show item fields
seqintegerrequired

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

tsstringrequired

When it happened: ISO-8601 with an offset.

kindstringrequired

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

Allowed: "msg""tool""error""outcome""session"

rolestringrequired

Allowed: "user""assistant""tool""system"

textstringrequired

What was said or done. Scrub secrets before sending.

datavalueoptional

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

Responses

Every Experience finished processing within wait.

billingobjectconditional

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

Show nested fields
operationIdstringalways present
priceVersionstringalways present
sourceTokensintegeralways present

Minimum: 0

memoryTokensintegeralways present

Minimum: 0

measuredMemoryTokensintegeralways present

Minimum: 0

replayedbooleanalways present
complimentarybooleanconditional
ratedAmountstringconditional
amountstringalways present
receiptIdsarrayalways present
Show item fields
acceptedintegeralways present

How many experiences were accepted.

connectorIdstringconditional

Present for Connector-backed writes.

sourceobjectconditional

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

Show nested fields
typestringalways present

Allowed: "api-key"

idstringalways present
workspacestringconditional

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

experiencesarrayalways present

One per experience, in request order.

Show item fields
objectstringalways present

Allowed: "experience"

idstringalways present

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

statusstringalways present

Allowed: "accepted""processed""consolidated""failed"

billingOperationIdstringconditional

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

claimIdsarrayconditional

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

Show item fields