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

# Search Documents

> Search documents by title prefix and/or tag

# Search Documents

```
GET /v1/documents/search
```

Search documents by title prefix and/or tag. At least one of `q` or `tag` is required. Results are scoped to the authenticated user.

## Query Parameters

| Parameter   | Type      | Required | Description                                   |
| ----------- | --------- | -------- | --------------------------------------------- |
| `q`         | `string`  | No\*     | Title prefix to search for (case-insensitive) |
| `tag`       | `string`  | No\*     | Exact tag to match from `metadata.tags`       |
| `folder_id` | `string`  | No       | Scope results to a specific folder            |
| `limit`     | `integer` | No       | Max results (default: 20, max: 50)            |
| `offset`    | `integer` | No       | Number of results to skip                     |

<Note>At least one of `q` or `tag` is required.</Note>

**Required role:** `documents:read`

## Example Request

```bash theme={null}
curl "https://api.surfacedocs.dev/v1/documents/search?q=API&tag=guide&limit=10" \
  -H "X-API-Key: sd_live_..."
```

## Response

```json theme={null}
{
  "results": [
    {
      "id": "doc_abc123",
      "url": "https://app.surfacedocs.dev/d/doc_abc123",
      "folder_id": "fld_xyz",
      "title": "API Documentation",
      "content_type": "markdown",
      "block_count": 15,
      "metadata": {
        "tags": ["api", "guide"],
        "source": "claude-3"
      },
      "visibility": "private",
      "current_version": 3,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-02T00:00:00Z"
    }
  ],
  "count": 1,
  "query": "API",
  "tag": "guide",
  "folder_id": null
}
```

## Response Fields

| Field       | Type             | Description                |
| ----------- | ---------------- | -------------------------- |
| `results`   | `array`          | List of matching documents |
| `count`     | `integer`        | Number of results returned |
| `query`     | `string \| null` | The title query used       |
| `tag`       | `string \| null` | The tag filter used        |
| `folder_id` | `string \| null` | The folder scope used      |

Each result in `results` contains:

| Field             | Type              | Description                               |
| ----------------- | ----------------- | ----------------------------------------- |
| `id`              | `string`          | Document ID                               |
| `url`             | `string`          | URL to view the document                  |
| `folder_id`       | `string`          | Parent folder ID                          |
| `title`           | `string`          | Document title                            |
| `content_type`    | `string`          | Content type (`markdown`, `html`, `text`) |
| `block_count`     | `integer`         | Number of content blocks                  |
| `metadata`        | `object \| null`  | Document metadata including tags          |
| `visibility`      | `string`          | Document visibility                       |
| `current_version` | `integer \| null` | Current version number                    |
| `created_at`      | `string`          | ISO 8601 creation timestamp               |
| `updated_at`      | `string`          | ISO 8601 last update timestamp            |

## Search Behavior

* **Title search (`q`):** Case-insensitive prefix match. Searching `q=api` matches "API Documentation", "api-guide", etc.
* **Tag search (`tag`):** Exact match against the `metadata.tags` array.
* **Combined:** When both `q` and `tag` are provided, results must match both (AND logic).
* **Folder scope:** When `folder_id` is provided, only documents in that folder are searched.

## Errors

| Code | Description                         |
| ---- | ----------------------------------- |
| 422  | Neither `q` nor `tag` provided      |
| 401  | Invalid or missing API key          |
| 403  | API key lacks `documents:read` role |
| 404  | Specified `folder_id` not found     |