Create experiences
/v1/experiencesSubmit 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
waitstringoptionalquery parameter. Seconds (0–30) to wait for processing before answering. 200 when every experience finished in time, else 202.
X-Augenta-Connector-Idstringoptionalheader 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
workspacestringoptionalOne Workspace assigned to the key. Required when the key has multiple assignments; inferred for one.
Min length: 1
experiencesarrayrequiredOne or more experiences, up to 1,000 steps and data items in all.
Min items: 1
Show item fields
srcstringrequiredWho composed it. Send service from your own code.
Allowed: "service""claude-code""codex"
sidstringrequiredThe session id: one conversation, one agent run, or one document. Experiences that share it are one stream.
Min length: 1
projstringoptionalAn optional project name, for your own grouping. Defaults to empty.
typestringoptionaltrajectory (the default) for conversations and agent runs, doc for a document.
eventsarrayoptionalA trajectory's steps. Required for a trajectory; not allowed on other types.
Show item fields
seqintegerrequiredThe step's position in the session. Integer; give each step its own, increasing across calls.
tsstringrequiredWhen it happened: ISO-8601 with an offset.
kindstringrequiredmsg for a message; session for context such as a system prompt; tool for a tool call or result.
Allowed: "msg""tool""error""outcome""session"
rolestringrequiredAllowed: "user""assistant""tool""system"
textstringrequiredWhat was said or done. Scrub secrets before sending.
datavalueoptionalAny 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.
billingobjectconditionalPresent 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 presentpriceVersionstringalways presentsourceTokensintegeralways presentMinimum: 0
memoryTokensintegeralways presentMinimum: 0
measuredMemoryTokensintegeralways presentMinimum: 0
replayedbooleanalways presentcomplimentarybooleanconditionalratedAmountstringconditionalamountstringalways presentreceiptIdsarrayalways presentShow item fields
acceptedintegeralways presentHow many experiences were accepted.
connectorIdstringconditionalPresent for Connector-backed writes.
sourceobjectconditionalPresent for writes made with the API key's Workspace permissions, instead of connectorId.
workspacestringconditionalThe destination Workspace for writes made with the API key's Workspace permissions.
experiencesarrayalways presentOne per experience, in request order.
Show item fields
objectstringalways presentAllowed: "experience"
idstringalways presentPoll GET /v1/experiences/{id} with it. The same experience sent again gets the same id.
statusstringalways presentAllowed: "accepted""processed""consolidated""failed"
billingOperationIdstringconditionalSource receipt reference when billing is enabled. It settles with successful durable processing.
claimIdsarrayconditionalIDs of Claims extracted from this source, when returned. Read extractedClaims.data or an Engram's claims.data for their text.