Skip to content
AugentaDocsOpen console ↗
Consolidate

Documentation

API reference
View Markdown

Consolidate

Extract claims and engrams from input in one call, or add input to a Workspace and get its claims back.

POST /v1/consolidate extracts claims from your input. It runs in one of two modes:

RequestWhat happensTypical use
Omit workspaceOne-shot. Only this input is processed: its claims are grouped into engrams and returned, and nothing is stored.Trying the API; summarizing a conversation you hold yourself.
Include workspaceWorkspace. The input is stored as experiences, and the call returns once their claims are extracted and searchable by Recall. Engrams form from them in the background.Adding input when you need its extracted claims, or recalled context for a question, in the response.

Send chat messages in the OpenAI or Anthropic format with a session name, or send experience envelopes. Message text is read in full. Tool calls and tool results are accepted and checked, but claims are never extracted from them and they are not billed. Reasoning signatures and encrypted or redacted content are dropped before extraction too. Media (images, audio, files) and a tool result without its matching tool call are refused before processing starts.

One-shot processing

json
{
  "session": "hello-world",
  "messages": [
    {
      "role": "user",
      "content": "Production releases require owner approval. Record a rollback image digest before deployment."
    }
  ]
}

The equivalent experience-envelope form:

json
{
  "experiences": [
    {
      "src": "service",
      "sid": "release-runbook",
      "type": "doc",
      "data": {
        "documentId": "release-runbook",
        "text": "Production releases require owner approval. Record a rollback image digest before deployment.",
        "capturedAt": "2026-10-28T12:00:00Z"
      }
    }
  ]
}

A completed one-shot result:

json
{
  "experiences": [
    {
      "id": "exp_222222222222222222222222",
      "status": "consolidated",
      "claimIds": [
        "clm_111111111111111111111111"
      ],
      "object": "experience"
    }
  ],
  "engrams": {
    "object": "list",
    "data": [
      {
        "object": "engram",
        "id": "eng_333333333333333333333333",
        "summary": "Production releases need owner approval and a recorded rollback image digest.",
        "label": "releases \u00b7 rollback",
        "labelSupport": 1,
        "memoryClass": "semantic",
        "status": "active",
        "strength": 1.5,
        "heatShare": 1,
        "claimCount": 1,
        "claimTokenCount": 15,
        "bornAt": "2026-10-28T12:00:00Z",
        "updatedAt": "2026-10-28T12:00:00Z",
        "claims": {
          "object": "list",
          "data": [
            {
              "id": "clm_111111111111111111111111",
              "text": "Production releases require owner approval and a recorded rollback image digest.",
              "experience": "exp_222222222222222222222222",
              "at": "2026-10-28T12:00:00Z",
              "object": "claim"
            }
          ],
          "nextPageUrl": null,
          "truncated": false
        }
      }
    ],
    "nextPageUrl": null,
    "truncated": false
  },
  "timing": {
    "firstClaimMs": 12,
    "firstEngramMs": 17,
    "totalMs": 21
  },
  "usage": {
    "tokensSent": 13,
    "tokensSentSource": "estimate:utf8-bytes/3.5"
  },
  "extractedClaims": {
    "object": "list",
    "data": [
      {
        "id": "clm_111111111111111111111111",
        "text": "Production releases require owner approval and a recorded rollback image digest.",
        "experience": "exp_222222222222222222222222",
        "at": "2026-10-28T12:00:00Z",
        "object": "claim"
      }
    ],
    "nextPageUrl": null,
    "truncated": false
  },
  "extractedClaimsComplete": true,
  "events": []
}

Nothing is stored. IDs identify objects within this result only: they can't be looked up, and the same input sent again need not produce the same IDs. session names the conversation; in one-shot mode it is not kept.

Workspace processing

Include workspace to add the input to that Workspace's memory. In this mode the messages are stored as an experience under session, so later calls and Recall can use them. Send each message once, with a seq that counts up across the whole conversation: when the conversation continues, send only the new messages under the same session, numbered on from the last seq you sent.

json
{
  "workspace": "ws-research",
  "session": "hello-world",
  "messages": [
    {
      "role": "user",
      "content": "Production releases require owner approval. Record a rollback image digest before deployment.",
      "seq": 0
    }
  ],
  "query": "What is required before production releases?"
}

The next call in this conversation numbers its messages from "seq": 1. Without seq, every call numbers its messages from 0, so a later call reuses numbers an earlier call stored and is refused with 409 conflict; the messages stored first stay. A retry of the same request is accepted.

Experience envelopes use the same request:

json
{
  "workspace": "ws-research",
  "experiences": [
    {
      "src": "service",
      "sid": "release-runbook",
      "type": "doc",
      "data": {
        "documentId": "release-runbook",
        "text": "Production releases require owner approval. Record a rollback image digest before deployment.",
        "capturedAt": "2026-10-28T12:00:00Z"
      }
    }
  ]
}

The call returns once the input's claims are extracted, stored and searchable by Recall. It doesn't wait for them to be grouped into engrams: consolidation runs in the background, and GET /v1/experiences/{id} reports consolidated once it covers the experience. A query runs Recall after the claims are stored, so it already finds them, and returns context:

json
{
  "workspace": "ws-research",
  "operation": "op_5f2c9a7e1b3d4c6a8e0f2b4d",
  "experiences": [
    {
      "id": "exp_222222222222222222222222",
      "status": "processed",
      "object": "experience"
    }
  ],
  "usage": {
    "tokensSent": 27,
    "tokensSentSource": "estimate:source-chars/3.5",
    "modelInputTokens": null,
    "modelOutputTokens": null
  },
  "context": {
    "memory": [
      {
        "type": "claim",
        "text": "Production releases require owner approval and a recorded rollback image digest.",
        "timestamp": "2026-10-28T12:00:00Z",
        "question": false,
        "frame": {},
        "metadata": {
          "src": "service",
          "sid": "hello-world"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Production releases require owner approval. Record a rollback image digest before deployment."
      }
    ],
    "budget_tokens": 6000,
    "tokensEstimated": 48,
    "tokenEstimateSource": "estimate:utf8-bytes/3.5",
    "memoryTruncated": false
  },
  "timing": {
    "firstClaimMs": 2140,
    "firstEngramMs": null,
    "totalMs": 2910
  },
  "extractedClaims": {
    "object": "list",
    "data": [
      {
        "id": "clm_111111111111111111111111",
        "text": "Production releases require owner approval and a recorded rollback image digest.",
        "experience": "exp_222222222222222222222222",
        "at": "2026-10-28T12:00:00Z",
        "object": "claim"
      }
    ],
    "nextPageUrl": null
  },
  "extractedClaimsComplete": true
}
FieldWhat it holds
experiencesOne reference per experience, with status processed, or superseded when a newer revision of the same document was already stored. Poll GET /v1/experiences/{id} to see consolidated.
extractedClaimsThe claims extracted from this call's input. Follow extractedClaims.nextPageUrl unchanged for more; include: [] leaves it out.
extractedClaimsCompletetrue when extraction covered all of the input.
context.memoryThe Recall blocks for query, within budget_tokens (default 6,000). Empty when no query is sent. Add their text to your model's prompt.
context.messagesThe last keep_recent (default 6) of the messages you sent, kept whole with their tool calls. Your own messages, returned for convenience: memory is not inserted into them.
context.memoryTruncatedtrue when blocks were left out to fit budget_tokens.
timing.firstEngramMsAlways null in Workspace mode, which returns before engrams form.

The response has no engrams or events. Once the experiences are consolidated, read the engrams with Engrams and their lifecycle with Events.

query, budget_tokens and keep_recent apply only to Workspace mode. Accepted input keeps processing if your client disconnects.

Parameters

See the endpoint reference for every parameter and attribute.

  • summaries: false (one-shot only) skips writing summaries and omits summary, label and labelSupport. A Workspace's summaries follow its own settings.
  • include: one-shot mode defaults to ["claims", "extractedClaims"]; send a subset, or []. Workspace mode accepts only "extractedClaims", its default; [] leaves it out, and "claims" is refused with 400 invalid_request.
  • claims_limit defaults to 100 and accepts 1–500. engrams_limit (same bounds) is one-shot only; a Workspace call that sends it gets 400 invalid_request.
  • One-shot collections have nextPageUrl: null and a truncated flag that is true when items were left out. Workspace collections carry a nextPageUrl to follow unchanged.

Streaming

Send stream: true or Accept: text/event-stream to receive progress and provisional claims as they are extracted, then one completed result. One-shot streams also send engram previews as they form. Previews carry the available labels and extractive summaries, without extra summarization calls. They have preview_ IDs and may be replaced; only the completed result is final. A Workspace stream sends no engram previews. A stream that ends with an error event has no completed result. Use streaming for long inputs: a JSON request that runs past its deadline (about 90 seconds) fails with operation_timeout.

Common errors

CodeHTTPAction
invalid_request400Correct the input; message names the problem.
at_capacity429Wait Retry-After seconds, then send the same request.
operation_timeout504Send the request again with stream: true.
conflict409This session already stored other messages under these seq numbers. Number new messages on from the last seq you sent.
cursor_stale409The Workspace changed while the result was read; send the same request again.