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

# Search

> Full-text and semantic search across your saved content

## Search content

```bash theme={null}
GET /api/v1/search
```

Search across all your saved content with full-text matching, filters, and faceted results.

**Scope:** `search`

### Query parameters

| Parameter    | Type    | Default      | Description                                     |
| ------------ | ------- | ------------ | ----------------------------------------------- |
| `q`          | string  | **required** | Search query                                    |
| `limit`      | integer | `20`         | Results per page (1-50)                         |
| `offset`     | integer | `0`          | Offset for pagination (0-10000)                 |
| `sort_by`    | string  | `relevance`  | Sort order: `relevance`, `saved_at`, or `title` |
| `sort_order` | string  | `desc`       | Sort direction: `asc` or `desc`                 |

### Filters

| Parameter         | Type    | Description                                              |
| ----------------- | ------- | -------------------------------------------------------- |
| `platforms`       | string  | Comma-separated platform filter (e.g. `youtube,twitter`) |
| `tags`            | string  | Comma-separated tag filter                               |
| `creators`        | string  | Comma-separated creator handles                          |
| `collection_ids`  | string  | Comma-separated collection IDs                           |
| `favorites_only`  | boolean | Only return favorites                                    |
| `archived_only`   | boolean | Only return archived items                               |
| `has_ai_analysis` | boolean | Filter by AI analysis status                             |
| `saved_after`     | integer | Unix timestamp — only items saved after this time        |
| `saved_before`    | integer | Unix timestamp — only items saved before this time       |

### Example

```bash theme={null}
curl "https://api.animus.so/api/v1/search?q=machine+learning&platforms=youtube,web&limit=10&sort_by=saved_at" \
  -H "Authorization: Bearer anm_your_key"
```

### Response

```json theme={null}
{
  "hits": [
    {
      "user_content_id": "uuid",
      "title": "Introduction to Transformers",
      "short_summary": "A comprehensive guide to transformer architecture...",
      "thumbnail_url": "https://example.com/thumb.jpg",
      "original_url": "https://example.com/transformers",
      "platform": "web",
      "domain": "example.com",
      "creator_name": "Author Name",
      "creator_handle": "authorhandle",
      "personal_tags": ["ml", "transformers"],
      "is_favorite": false,
      "is_archived": false,
      "saved_at": 1705312200,
      "collection_ids": ["uuid"],
      "text_match_score": 0.95,
      "highlights": [
        {
          "field": "title",
          "snippet": "Introduction to <mark>Transformers</mark>"
        }
      ]
    }
  ],
  "found": 42,
  "out_of": 1250,
  "page": 0,
  "search_time_ms": 12,
  "has_more": true,
  "facets": {
    "platforms": [
      { "value": "web", "count": 28 },
      { "value": "youtube", "count": 14 }
    ],
    "tags": [
      { "value": "ml", "count": 35 },
      { "value": "ai", "count": 22 }
    ]
  }
}
```

### Response fields

| Field            | Type    | Description                                         |
| ---------------- | ------- | --------------------------------------------------- |
| `hits`           | array   | Matching content items                              |
| `found`          | integer | Total matching documents                            |
| `out_of`         | integer | Total documents in your library                     |
| `page`           | integer | Current page number                                 |
| `search_time_ms` | integer | Search execution time in milliseconds               |
| `has_more`       | boolean | Whether more results are available                  |
| `facets`         | object  | Aggregated counts for platforms, tags, and creators |

### Hit fields

| Field              | Type       | Description                                 |
| ------------------ | ---------- | ------------------------------------------- |
| `user_content_id`  | string     | Content item ID                             |
| `title`            | string     | Content title                               |
| `short_summary`    | string     | Brief summary                               |
| `thumbnail_url`    | string?    | Thumbnail image URL                         |
| `original_url`     | string     | Source URL                                  |
| `platform`         | string     | Platform (e.g. `web`, `youtube`, `twitter`) |
| `domain`           | string     | Source domain                               |
| `creator_name`     | string?    | Creator display name                        |
| `creator_handle`   | string?    | Creator handle/username                     |
| `personal_tags`    | string\[]? | User-assigned tags                          |
| `is_favorite`      | boolean    | Whether item is favorited                   |
| `is_archived`      | boolean    | Whether item is archived                    |
| `saved_at`         | integer    | Unix timestamp when saved                   |
| `collection_ids`   | string\[]? | IDs of collections containing this item     |
| `text_match_score` | number     | Relevance score (0-1)                       |
| `highlights`       | array?     | Matched text snippets with `<mark>` tags    |

<Tip>Use facets to build filter UIs — they show what values exist in the result set and how many items match each value.</Tip>