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

# API Introduction

> Base URL, authentication, rate limits, and general API conventions

## Base URL

```
https://api.engram.training/v1
```

## Authentication

All requests require a Bearer token:

```bash theme={null}
curl -H "Authorization: Bearer sk_live_your_key_here" \
  https://api.engram.training/v1/memory
```

API keys start with `sk_live_` and are tied to your account. Each account can create multiple agents, each with their own isolated memory space.

## Rate Limits

| Operation                  | Limit                         |
| -------------------------- | ----------------------------- |
| Global (all requests)      | 300/min per API key           |
| Writes (POST, PUT, DELETE) | 30/min per agent              |
| Reads (GET, search)        | Unlimited (within global cap) |

Exceeding limits returns `429 Too Many Requests`. Rate limits are per agent API key.

<Note>
  Pin/importance updates, TTL alerts, expiring checks, and audit reads are **free** — no credit cost. Credits are automatically **refunded** if an operation fails with a server error (5xx) or an input validation error (400, 413, 422). Legitimate rejections like 404 (not found), 409 (conflict), and 429 (rate limit) are not refunded.
</Note>

## Response Format

All responses are JSON. Successful operations return the appropriate HTTP status:

| Status | Meaning                                                |
| ------ | ------------------------------------------------------ |
| `200`  | Success                                                |
| `201`  | Created                                                |
| `400`  | Bad request (invalid parameters)                       |
| `401`  | Unauthorized (invalid or missing API key)              |
| `402`  | Insufficient credits                                   |
| `404`  | Resource not found                                     |
| `409`  | Conflict (duplicate key)                               |
| `413`  | Payload too large                                      |
| `422`  | Validation error (e.g., credentials in shared content) |
| `429`  | Rate limited                                           |
| `500`  | Server error                                           |

## Pagination

List endpoints support two pagination modes:

### Cursor-based (recommended)

```bash theme={null}
GET /v1/memory?limit=20&cursor=<base64_cursor>
```

Response includes `nextCursor` and `hasMore`:

```json theme={null}
{
  "memories": [...],
  "nextCursor": "base64...",
  "hasMore": true
}
```

<Note>
  `total` is only included in offset-based pagination responses (not cursor-based) to avoid expensive count queries.
</Note>

### Offset-based

```bash theme={null}
GET /v1/memory?limit=20&offset=40
```

## SKILL.md Endpoint

Fetch the latest API documentation programmatically:

```bash theme={null}
# JSON format
GET /v1/skill

# Raw markdown
GET /v1/skill
Accept: text/markdown
```

<Tip>
  Have your agent fetch `/v1/skill` on startup to stay up-to-date with the latest API changes.
</Tip>