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

# REST API

> Access AMFS over HTTP — entries, search, outcomes, traces, and real-time streaming.

The AMFS REST API gives you full access to agent memory from any language or service.

**Base URL:** `https://amfs-login.sense-lab.ai` (or your custom domain from Dashboard → Settings)

**Authentication:** Include your API key in every request:

```
X-AMFS-API-Key: <your-api-key>
```

***

## Entries

| Method | Path                                          | Description         |
| :----- | :-------------------------------------------- | :------------------ |
| `POST` | `/api/v1/entries`                             | Write a new entry   |
| `GET`  | `/api/v1/entries/{entity_path}/{key}`         | Read an entry       |
| `GET`  | `/api/v1/entries`                             | List entries        |
| `GET`  | `/api/v1/entries/{entity_path}/{key}/history` | Version history     |
| `POST` | `/api/v1/search`                              | Search with filters |

All entry endpoints accept a `branch` parameter (defaults to `main`).

### Write

```bash theme={null}
curl -X POST https://amfs-login.sense-lab.ai/api/v1/entries \
  -H "Content-Type: application/json" \
  -H "X-AMFS-API-Key: <your-api-key>" \
  -d '{
    "entity_path": "checkout-service",
    "key": "retry-pattern",
    "value": {"max_retries": 3, "backoff": "exponential"},
    "confidence": 0.85
  }'
```

### Read

```bash theme={null}
curl https://amfs-login.sense-lab.ai/api/v1/entries/checkout-service/retry-pattern \
  -H "X-AMFS-API-Key: <your-api-key>"
```

### Search

```bash theme={null}
curl -X POST https://amfs-login.sense-lab.ai/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-AMFS-API-Key: <your-api-key>" \
  -d '{"entity_path": "checkout-service", "min_confidence": 0.5, "limit": 10}'
```

***

## Outcomes

| Method | Path               | Description                                    |
| :----- | :----------------- | :--------------------------------------------- |
| `POST` | `/api/v1/outcomes` | Commit an outcome (back-propagates confidence) |
| `GET`  | `/api/v1/outcomes` | List all outcomes                              |

```bash theme={null}
curl -X POST https://amfs-login.sense-lab.ai/api/v1/outcomes \
  -H "Content-Type: application/json" \
  -H "X-AMFS-API-Key: <your-api-key>" \
  -d '{"outcome_ref": "DEP-287", "outcome_type": "success"}'
```

***

## Decision Traces

| Method | Path                        | Description                    |
| :----- | :-------------------------- | :----------------------------- |
| `GET`  | `/api/v1/traces`            | List traces with enriched data |
| `GET`  | `/api/v1/traces/{trace_id}` | Full trace detail              |

***

## Agents & Timeline

| Method | Path                                     | Description                                     |
| :----- | :--------------------------------------- | :---------------------------------------------- |
| `GET`  | `/api/v1/agents`                         | List agents with entry counts and last activity |
| `GET`  | `/api/v1/agents/{agent_id}/memory-graph` | Entity relationship graph                       |
| `GET`  | `/api/v1/agents/{agent_id}/activity`     | Activity timeline                               |
| `GET`  | `/api/v1/agents/{agent_id}/timeline`     | Git-like event log                              |

***

## Memory Cortex

| Method | Path                     | Description                                     |
| :----- | :----------------------- | :---------------------------------------------- |
| `GET`  | `/api/v1/briefing`       | Ranked knowledge digests for an entity or agent |
| `GET`  | `/api/v1/cortex/status`  | Cortex status and digest counts                 |
| `GET`  | `/api/v1/cortex/digests` | All compiled digests                            |
| `POST` | `/api/v1/events`         | Ingest an external event                        |

### Get a briefing

```bash theme={null}
curl "https://amfs-login.sense-lab.ai/api/v1/briefing?entity_path=checkout-service" \
  -H "X-AMFS-API-Key: <your-api-key>"
```

***

## Branching (Pro)

| Method | Path                            | Description                 |
| :----- | :------------------------------ | :-------------------------- |
| `POST` | `/api/v1/branches`              | Create a branch             |
| `GET`  | `/api/v1/branches`              | List branches               |
| `GET`  | `/api/v1/branches/{name}/diff`  | Diff branch vs. main        |
| `POST` | `/api/v1/branches/{name}/merge` | Merge into main             |
| `POST` | `/api/v1/pull-requests`         | Create a pull request       |
| `GET`  | `/api/v1/pull-requests`         | List pull requests          |
| `POST` | `/api/v1/tags`                  | Create a snapshot tag       |
| `POST` | `/api/v1/rollback`              | Rollback to a point in time |
| `POST` | `/api/v1/fork`                  | Fork memory to a new agent  |

***

## Real-time Streaming

Subscribe to memory events via Server-Sent Events:

```bash theme={null}
curl -N "https://amfs-login.sense-lab.ai/api/v1/stream" \
  -H "X-AMFS-API-Key: <your-api-key>"
```

```
event: memory_write
data: {"entity_path": "checkout-service", "key": "retry-pattern", "version": 2, ...}

event: outcome
data: {"outcome_ref": "DEP-287", "outcome_type": "success", ...}
```

***

## Admin

| Method   | Path                              | Description            |
| :------- | :-------------------------------- | :--------------------- |
| `GET`    | `/api/v1/admin/api-keys`          | List API keys          |
| `POST`   | `/api/v1/admin/api-keys`          | Create an API key      |
| `DELETE` | `/api/v1/admin/api-keys/{key_id}` | Revoke a key           |
| `GET`    | `/api/v1/admin/audit`             | Audit log              |
| `GET`    | `/api/v1/admin/teams`             | List teams             |
| `POST`   | `/api/v1/admin/teams`             | Create a team          |
| `GET`    | `/api/v1/admin/patterns`          | List detected patterns |
| `POST`   | `/api/v1/admin/patterns/scan`     | Run pattern detection  |

***

## Python Client

```python theme={null}
import httpx

client = httpx.Client(
    base_url="https://amfs-login.sense-lab.ai",
    headers={"X-AMFS-API-Key": "<your-api-key>"},
)

client.post("/api/v1/entries", json={
    "entity_path": "myapp/auth",
    "key": "session-timeout",
    "value": "30m",
    "confidence": 0.9,
})

entry = client.get("/api/v1/entries/myapp/auth/session-timeout").json()
```

<Tip>
  For Python, the SDK with `AMFS_HTTP_URL` set is simpler than raw HTTP calls. See the [Python guide](/amfs/guides/python).
</Tip>