Search

Upcoming release — Zylon 1.58These 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.

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.

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

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

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.

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}"

Example response

[
  {
    "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"
    }
  }
]

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.

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.

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 [].

First Steps

Build with Zylon

Coding Agents

Prerequisites

Search workspace content

Filter behavior

Response fields

Understanding search scores

Metadata by result type

Errors and edge cases

​Prerequisites

​Search workspace content

​Filter behavior

​Response fields

​Understanding search scores

​Metadata by result type

​Errors and edge cases

Prerequisites

Search workspace content

Filter behavior

Response fields

Understanding search scores

Metadata by result type

Errors and edge cases