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:
export AUGENTA_API_KEY="your-api-key"
Send a document
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 --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 --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
- Give an agent memory turn by turn: Add memory to your agent.
- Add data and get its extracted claims back in one call: Consolidate.
- Compare stateless and workspace-backed request sequences: Using the APIs together.
- Documents, conversations, updates, deletion and retries: Experiences.
- Want Augenta's model to write the answer? Use answer mode.
- Handling failures: Errors.