Skip to content
AugentaDocsOpen console ↗
Import documents into a Workspace

Documentation

Guides
View Markdown

Import documents into a Workspace

Use the Experiences API for background ingestion, then retrieve the stored memory.

Use a Workspace when you want Augenta to keep memory between requests and update it with new data. It can belong to your personal account or an organization you have joined.

This guide uses Experiences for asynchronous ingestion. To add input and get its extracted claims back in one call, follow the workspace-backed Consolidate flow.

In the console, choose the account from the user menu, then use Create Workspace in the optional saved-memory section of Getting started. You can also use an existing Workspace. This walkthrough sends a document, follows processing and retrieves the memory it forms. If the Workspace already contains memory, skip to Recall the memory.

A Workspace holds memory. Create an API key with the Workspace assigned. The requests below infer the destination when the key has exactly one assignment. For multiple assignments, add workspace to ingestion and Recall request bodies.

Get an API key

In the console, open API Keys → New API Key, give it a label and select the Workspace. You must administer the Workspace to assign it. See Authentication for permissions.

Save the one-time secret before leaving its reveal screen. Load AUGENTA_API_KEY from your secret store; keep the value out of source control and agent conversations. For the curl examples, set it once in your terminal:

API key
export AUGENTA_API_KEY="your-api-key"

Send a document

cURL
curl --fail-with-body -sS "https://api.augenta.ai/v1/experiences" \
  -H "Authorization: AugentaKey $AUGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "experiences": [{
    "src": "service",
    "sid": "onboarding/deploys.md",
    "type": "doc",
    "data": {
      "documentId": "onboarding/deploys.md",
      "title": "Checkout deployment",
      "text": "Merging to main deploys checkout to dev. Production releases need an owner approval."
    }
  }]
}
JSON

Expect 202, accepted: 1, and an id in experiences[0].id. Set AUGENTA_EXPERIENCE_ID to that id (it is not a secret). Acceptance means durable ingest; it does not mean memory is ready.

Follow processing

cURL
curl --fail-with-body -sS "https://api.augenta.ai/v1/experiences/$AUGENTA_EXPERIENCE_ID" \
  -H "Authorization: AugentaKey $AUGENTA_API_KEY"

Repeat until the status is processed or consolidated, for about five minutes at most. If it is failed, read error.code and error.message before retrying.

If it remains accepted after five minutes, stop polling and check the Workspace's Experiences list in the console for processing progress. Keep the accepted id when reporting a stalled request; do not repeatedly upload the same document.

At processed, the retained claims are already searchable: continue to Recall the memory. A claim can be recalled before it belongs to an engram. At consolidated, a completed consolidation also covers the experience. See Experiences for all statuses.

Consolidation starts in the background once the experience is processed; an admin can also open Overview in the console and click Synthesize now. Recall doesn't need it. To add input and wait for its claims in one call, use Consolidate with the key's authorized workspace selector.

Recall the memory

Context mode returns matched memory for your own code or model to read, without an Augenta answer-model call. With exactly one assignment, the key infers its Workspace automatically.

The Python example uses requests; install it with python -m pip install requests in your application's virtual environment.

cURL
curl --fail-with-body -sS "https://api.augenta.ai/v1/recall?mode=context" \
  -H "Authorization: AugentaKey $AUGENTA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-Augenta-Content: content-v3" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do we deploy checkout?"}'

A successful response is 200, with mode: "context" and a content list containing matched claims and, when available, their engram. Look for the deployment statement you sent; ranked retrieval need not echo every sentence.

A valid empty search returns 200 with noMatch: true and content: []. It makes no answer-model call and records no activation. Check the accepted experience's processing status and whether your query matches its retained claims rather than repeatedly uploading. Consolidation is not required to retrieve an individual claim. 401 means the credential was not accepted; an inactive Connector or Workspace can also refuse access. See Errors.

Next