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

# Search

> Search across projects, threads, artifacts, artifact content, and interactions.

Use the Search API to query workspace content with a single text query. Limit search scope with the `types` filter.

Search requests require a token with workspace access and a PrivateGPT gateway linked to your organization collection.

## Basic request and response

Search across resources with `GET /api/v1/app/search`.

<Accordion title="Endpoint parameters">
  | Type  | Name    | Required | Notes                                                                                                                 |
  | ----- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
  | Query | `q`     | Yes      | Search text. Must be between 3 and 80 characters.                                                                     |
  | Query | `types` | No       | Comma-separated list of `Project`, `Artifact`, `ArtifactContent`, `Thread`, and `Interaction`. Defaults to all types. |
  | Query | `limit` | No       | Maximum results. Defaults to `30` and must be greater than `1`.                                                       |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/search?q=support%20summary&types=Artifact,ArtifactContent&limit=5" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  [
    {
      "id": "artifact_2b4d6f8a1c3e5a7b",
      "type": "Artifact",
      "match": "Q1 Support Summary",
      "rank": 0.91,
      "metadata": {
        "name": "Q1 Support Summary",
        "type": "Document",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "project_name": "Customer Insights"
      }
    },
    {
      "id": "content_8f1a3d5c7b9e",
      "type": "ArtifactContent",
      "match": "Billing issues drove 38% of support cases.",
      "rank": 0.84,
      "metadata": {
        "name": "Q1 Support Summary",
        "type": "Document",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "project_name": "Customer Insights"
      }
    }
  ]
  ```
</Accordion>

## Search only threads

<Accordion title="Endpoint parameters">
  | Type  | Name    | Required | Notes                                                           |
  | ----- | ------- | -------- | --------------------------------------------------------------- |
  | Query | `q`     | Yes      | Search text. Must be between 3 and 80 characters.               |
  | Query | `types` | No       | Use `Thread` to limit results to threads.                       |
  | Query | `limit` | No       | Maximum results. Defaults to `30` and must be greater than `1`. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/search?q=weekly%20brief&types=Thread&limit=5" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  [
    {
      "id": "thread_3f2a1c4d5b6e7f8a",
      "type": "Thread",
      "match": "Weekly Support Brief",
      "rank": 0.86,
      "metadata": {
        "name": "Weekly Support Brief",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "project_name": "Customer Insights"
      }
    }
  ]
  ```
</Accordion>

## Metadata by result type

| Result type       | Metadata shape                                                       |
| ----------------- | -------------------------------------------------------------------- |
| `Project`         | `entity`, containing the project object.                             |
| `Artifact`        | `name`, `type`, `project_id`, `project_name`.                        |
| `ArtifactContent` | `name`, `type`, `project_id`, `project_name`.                        |
| `Thread`          | `name`, `project_id`, `project_name`.                                |
| `Interaction`     | `content`, `thread_id`, `project_id`, `project_name`, `thread_name`. |

## Errors and edge cases

* **400**: missing `q`, blank query, query outside the 3-80 character range, invalid `types`, or `limit <= 1`.
* **403**: insufficient permissions.