# 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](https://augenta.pages.dev/docs/memory-flows.md#workspace-memory).

In the [console](https://augenta.pages.dev/dashboard/getting-started), 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.

### 1. Get an API key

In the [console](https://augenta.pages.dev/dashboard), open **API Keys** →
**New API Key**, give it a label and select the Workspace. You must administer the
Workspace to assign it. See [Authentication](https://augenta.pages.dev/docs/authentication.md)
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:

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

### 2. Send a document

```bash 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.

### 3. Follow processing

```bash 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](https://augenta.pages.dev/docs/experiences.md#follow-an-experience) 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](https://augenta.pages.dev/docs/consolidate.md) with the key's authorized `workspace`
selector.

### 4. 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.

```bash 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?"}'
```

```python Python
import os, uuid, requests

response = requests.post(
    "https://api.augenta.ai/v1/recall?mode=context",
    headers={
        "Authorization": f"AugentaKey {os.environ['AUGENTA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
        "X-Augenta-Content": "content-v3",
    },
    json={"query": "How do we deploy checkout?"},
    timeout=60,
)
response.raise_for_status()
recall = response.json()
for block in recall["content"]:
    if block["type"] in ("engram", "claim"):
        print(block["text"])
```

```javascript JavaScript
const response = await fetch("https://api.augenta.ai/v1/recall?mode=context", {
  method: "POST",
  headers: {
    Authorization: `AugentaKey ${process.env.AUGENTA_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "X-Augenta-Content": "content-v3",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "How do we deploy checkout?" }),
});
if (!response.ok) throw new Error(`recall failed: ${response.status}`);
const recall = await response.json();
for (const block of recall.content) {
  if (["engram", "claim"].includes(block.type)) console.log(block.text);
}
```

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](https://augenta.pages.dev/docs/errors.md).

> Note:
>
> Recorded recall adds an **activation** when returned claims belong to a real
> engram. Claims without an engram can be recalled without inventing one.
> Use `record: false` for a read without activation lookup or writes; it needs
> no idempotency header. See [Activations](https://augenta.pages.dev/docs/recall.md#activations).

## Next

* Give an agent memory turn by turn: [Add memory to your agent](https://augenta.pages.dev/docs/agent-memory.md).
* Add data and get its extracted claims back in one call: [Consolidate](https://augenta.pages.dev/docs/consolidate.md).
* Compare stateless and workspace-backed request sequences: [Using the APIs together](https://augenta.pages.dev/docs/memory-flows.md).
* Documents, conversations, updates, deletion and retries: [Experiences](https://augenta.pages.dev/docs/experiences.md).
* Want Augenta's model to write the answer? Use [answer mode](https://augenta.pages.dev/docs/recall.md#modes).
* Handling failures: [Errors](https://augenta.pages.dev/docs/errors.md).
