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

<Warning>
  **Upcoming release — Zylon 1.58**

  These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the [1.57 documentation](/en/v1.57/overview).
</Warning>

Use the Search API to query content visible to the authenticated workspace member. You can combine text, resource, project, artifact-type, and creation-date filters in one request.

## Prerequisites

* Send an API token whose effective permissions include Workspace search.
* Send the organization slug in the `x-org` header.
* Semantic `ArtifactContent` search requires a PrivateGPT gateway linked to the organization collection. Keyword-only searches do not use the semantic search engine.

## Search workspace content

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

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Query | `q` | Yes | Search text. Leading and trailing whitespace is removed before validating the configured length range: 3 to 80 characters by default. |
  | Query | `types` | No | Search result types. Accepts comma-separated or repeated values: `Project`, `Artifact`, `Thread`, `Interaction`, and `ArtifactContent`. Defaults to all types. |
  | Query | `type` | No | Alternative to `types`. Used only when `types` is absent. |
  | Query | `project_ids` | No | Project UUID allow-list. Accepts comma-separated or repeated values and searches only projects also visible to the caller. |
  | Query | `exclude_project_ids` | No | Project UUID deny-list. Accepts comma-separated or repeated values. Exclusion wins when an ID appears in both project filters. |
  | Query | `artifact_types` | No | Artifact types for `Artifact` and `ArtifactContent` results. Accepts comma-separated or repeated values. |
  | Query | `start_date` | No | Inclusive creation-time lower bound as Unix epoch milliseconds. |
  | Query | `end_date` | No | Inclusive creation-time upper bound as Unix epoch milliseconds. Must not be earlier than `start_date`. |
  | Query | `limit` | No | Positive result limit applied separately to each result type. Defaults to `30`. |
</Accordion>

List parameters are case-sensitive, trim whitespace, remove duplicates, and support both formats below:

```text theme={null}
types=Artifact,ArtifactContent
types=Artifact&types=ArtifactContent
```

`artifact_types` accepts `InlineText`, `Document`, `Folder`, `Summary`, `Composition`, `SmartDoc`, `Link`, `BulkQA`, `ReadAndExtract`, `SqlDatabase`, `McpServer`, `Integration`, `Analysis`, and `Skill`. Searchable content currently covers document-family artifacts, visible links to them, and agent flows. Other valid artifact types can produce no artifact or content results.

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

<Accordion title="Example response">
  ```json theme={null}
  [
    {
      "id": "0198cc5a-4411-7000-8000-000000000001",
      "type": "Artifact",
      "match": "Q1 Support Summary",
      "rank": 0.0241,
      "keyword_score": 0.76,
      "metadata": {
        "name": "Q1 Support Summary",
        "type": "Document",
        "project_id": "0198cc5a-4411-7000-8000-000000000010",
        "project_name": "Customer Insights"
      }
    },
    {
      "id": "0198cc5a-4411-7000-8000-000000000002",
      "type": "ArtifactContent",
      "match": "Billing issues drove a significant share of support cases.",
      "rank": 0.0014,
      "semantic_score": 0.84,
      "metadata": {
        "name": "Support Analysis",
        "type": "Document",
        "project_id": "0198cc5a-4411-7000-8000-000000000010",
        "project_name": "Customer Insights"
      }
    }
  ]
  ```
</Accordion>

## Filter behavior

* If `types` and `type` are both present, `types` takes precedence and `type` is ignored.
* Omitting `project_ids` searches every project visible to the caller. Valid but inaccessible project IDs are silently excluded.
* `exclude_project_ids` is applied after `project_ids`. If no projects remain, the response is `[]`.
* Date bounds use each entity's creation time. For semantic content results, they use the artifact creation time.
* Artifact-type filtering affects only `Artifact` and `ArtifactContent` results.
* Search returns only visible projects, active visible threads and interactions, and available artifacts ready for use.

## Response fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Result identifier. A result created from a link uses the link ID. |
| `type` | string | `Project`, `Artifact`, `Thread`, `Interaction`, or `ArtifactContent`. |
| `match` | string | Matching name or content excerpt. Semantic excerpts have Markdown formatting removed. |
| `rank` | number | Combined weighted score used to order the response. Always present. |
| `keyword_score` | number, optional | Raw keyword-search score. Omitted for semantic-only results. |
| `semantic_score` | number, optional | Raw semantic-search score. Omitted for keyword-only results. |
| `metadata` | object | Type-specific result details. |

### Understanding search scores

* **`rank`** combines the source score, its position in the keyword or semantic result list, and dynamic source weighting. It is not a probability or confidence percentage and has no fixed range. Use the returned order instead of applying a fixed threshold.
* **`keyword_score`** is the original PostgreSQL full-text relevance score. Higher values are treated as stronger keyword matches. A name matched outside full-text ranking can have a score of `0`.
* **`semantic_score`** is the raw semantic retrieval score for the selected content chunk. It is not normalized confidence.
* Compare raw scores only between results produced by the same engine for the same query. Do not compare `keyword_score` with `semantic_score`, or scores from different requests.
* Optional raw score fields are omitted from JSON rather than returned as `null`.

<Note>
  Results are grouped in this order: `Project`, `Artifact`, `Thread`, `Interaction`, and `ArtifactContent`. Within each group, higher `rank` values appear first. Because `limit` is applied per result type, a mixed-type response can contain more than `limit` total items. Entries returned by both search engines are not deduplicated.
</Note>

## Metadata by result type

| Result type | Metadata shape |
| - | - |
| `Project` | `entity`, containing `id`, `name`, `goal`, `default_member_role`, `default_role_enabled`, `visibility`, `member_count`, `members`, `project_context`, `use_citations`, `use_system_prompt`, and `is_pinned`. Each member contains `id`, `role`, `account`, and `is_project_member`. |
| `Artifact` | `name`, `type`, `project_id`, and `project_name`. Project fields can be `null`. |
| `ArtifactContent` | `name`, `type`, `project_id`, and `project_name`. A link result keeps the link identity and target-project metadata while `type` identifies the original artifact type. |
| `Thread` | `name`, `project_id`, and `project_name`. |
| `Interaction` | `content`, `thread_id`, `project_id`, `project_name`, and `thread_name`. |

## Errors and edge cases

* **400**: missing or blank `q`; query outside the configured length range; empty or invalid list values; invalid project UUID; invalid date or limit; `start_date` after `end_date`; `limit` below `1`; or missing organization context.
* **401**: missing or invalid authentication.
* **403**: the token or account lacks Workspace search permission.
* **500**: the deployment has no search languages configured.
* A valid search with no visible matches returns `[]`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.