> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withfoundry.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory API reference

> REST API reference for the Memory Engine.

# Memory API reference

Base URL: `https://api.withfoundry.ai`\
Auth: `Authorization: Bearer key_...`

All responses use this envelope:

```json theme={null}
{
  "success": true,
  "data": { ... },
  "meta": { "requestId": "req_..." }
}
```

Errors return `success: false`, `data` with error details, and appropriate HTTP status (4xx/5xx).

***

## Write entries

`POST /v1/memory/entries`

Write one or more entries into a namespace. Each entry is embedded and indexed for semantic search.

**Request body**

| Field                | Type   | Required | Description                           |
| -------------------- | ------ | -------- | ------------------------------------- |
| `namespace`          | string | Yes      | Namespace id (e.g. app or tenant).    |
| `entries`            | array  | Yes      | Array of `{ content, metadata? }`.    |
| `entries[].content`  | string | Yes      | Text to store and embed.              |
| `entries[].metadata` | object | No       | Arbitrary JSON for filtering/display. |

**Response** `data`

| Field | Type      | Description                              |
| ----- | --------- | ---------------------------------------- |
| `ids` | string\[] | IDs of created entries (e.g. `mem_...`). |

**Example**

```bash theme={null}
curl -X POST https://api.withfoundry.ai/v1/memory/entries \
  -H "Authorization: Bearer key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"my-app","entries":[{"content":"Auth uses Bearer key_...","metadata":{"source":"docs"}}]}'
```

***

## Search

`POST /v1/memory/search`

Semantic search over a namespace. Returns entries ranked by similarity to the query.

**Request body**

| Field            | Type   | Required | Description                      |
| ---------------- | ------ | -------- | -------------------------------- |
| `namespace`      | string | Yes      | Namespace to search.             |
| `query`          | string | Yes      | Natural-language query.          |
| `limit`          | number | No       | Max results (default from plan). |
| `metadataFilter` | object | No       | Key-value filters on metadata.   |

**Response** `data`

Array of objects:

| Field      | Type   | Description                  |
| ---------- | ------ | ---------------------------- |
| `id`       | string | Entry id.                    |
| `content`  | string | Stored text.                 |
| `metadata` | object | Stored metadata.             |
| `score`    | number | Similarity score (e.g. 0–1). |

**Example**

```bash theme={null}
curl -X POST https://api.withfoundry.ai/v1/memory/search \
  -H "Authorization: Bearer key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"my-app","query":"How do we authenticate?","limit":5}'
```

***

## Get context

`POST /v1/memory/context`

Run semantic search and return a single formatted context string for use in LLM prompts.

**Request body**

| Field       | Type   | Required | Description                           |
| ----------- | ------ | -------- | ------------------------------------- |
| `namespace` | string | Yes      | Namespace to search.                  |
| `query`     | string | Yes      | Query for ranking entries.            |
| `limit`     | number | No       | Max entries to include in the string. |

**Response** `data`

| Field      | Type      | Description                          |
| ---------- | --------- | ------------------------------------ |
| `text`     | string    | Concatenated content of top entries. |
| `entryIds` | string\[] | IDs of entries included.             |

**Example**

```bash theme={null}
curl -X POST https://api.withfoundry.ai/v1/memory/context \
  -H "Authorization: Bearer key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"my-app","query":"user preferences and auth","limit":3}'
```