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

# Overview

> Build custom integrations with the Animus REST API

The Animus REST API lets you programmatically manage your content library. Save content, search across everything you've collected, and organize items into collections — all with simple HTTP requests.

## Base URL

```
https://api.animus.so/api/v1
```

## Authentication

All API requests require an API key sent as a Bearer token:

```bash theme={null}
curl https://api.animus.so/api/v1/content/stats \
  -H "Authorization: Bearer anm_your_api_key_here"
```

API keys are created in the [Animus app](https://app.animus.so/integrations) under **Integrations > API Keys**. See the [authentication guide](/api/authentication) for details.

## Available endpoints

<CardGroup cols={2}>
  <Card title="Content" icon="file-lines" href="/api/content">
    Save, retrieve, and manage content items in your library.
  </Card>

  <Card title="Collections" icon="folder" href="/api/collections">
    Create and manage collections to organize your content.
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/api/search">
    Full-text and semantic search across your saved content.
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    Create and manage API keys, scopes, and permissions.
  </Card>
</CardGroup>

## Quick start

Save a URL to your library:

```bash theme={null}
curl -X POST https://api.animus.so/api/v1/content \
  -H "Authorization: Bearer anm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'
```

Search your library:

```bash theme={null}
curl "https://api.animus.so/api/v1/search?q=pricing+strategies" \
  -H "Authorization: Bearer anm_your_api_key_here"
```

Get library statistics:

```bash theme={null}
curl https://api.animus.so/api/v1/content/stats \
  -H "Authorization: Bearer anm_your_api_key_here"
```

```json theme={null}
{
  "data": {
    "totalItems": 142,
    "collectionsCount": 8,
    "uncategorizedCount": 23,
    "archivedCount": 5,
    "deletedCount": 2,
    "bookmarkCount": 31
  },
  "statusCode": 200,
  "timestamp": "2025-01-15T10:30:00.000Z"
}
```

## Response format

All API responses are wrapped in a standard envelope:

```json theme={null}
{
  "data": { ... },
  "statusCode": 200,
  "timestamp": "2025-01-15T10:30:00.000Z"
}
```

| Field        | Type    | Description                            |
| ------------ | ------- | -------------------------------------- |
| `data`       | any     | The endpoint-specific response payload |
| `statusCode` | integer | HTTP status code                       |
| `timestamp`  | string  | ISO 8601 timestamp of the response     |

All response examples in this documentation show the contents of the `data` field.

## Rate limits

API key requests are rate-limited per endpoint. If you exceed the limit, you'll receive a `429 Too Many Requests` response. Wait and retry after the period resets.

| Endpoint             | Limit              |
| -------------------- | ------------------ |
| Search               | 60 requests/minute |
| Content ingestion    | 10 requests/minute |
| Other read endpoints | 60 requests/minute |

## Errors

The API uses standard HTTP status codes:

| Code  | Description                                                      |
| ----- | ---------------------------------------------------------------- |
| `200` | Success                                                          |
| `201` | Created                                                          |
| `204` | No content (successful delete)                                   |
| `400` | Bad request — check your parameters                              |
| `401` | Unauthorized — invalid or missing API key                        |
| `403` | Forbidden — endpoint not available via API key, or missing scope |
| `404` | Not found                                                        |
| `429` | Rate limit exceeded                                              |
| `500` | Server error                                                     |