---
title: "Search Artifacts"
method: POST
path: "/artifacts/search"
tags: ["Artifacts"]
---

# Search Artifacts

`POST /artifacts/search`

Search across accessible artifacts.

Supports the same query syntax as the legacy ``POST /search`` endpoint:
+term (AND), !term (exclude), ~term (semantic), ="phrase" (exact),
field:value filters, and @hybrid:on/off control.

Scope can be narrowed with ``scope`` (list of container IDs).

## Request body

- ArtifactSearchRequest — Search across accessible artifacts. Provide exactly one of ``query_text`` (text → embedded + hybrid BM25/kNN) or ``embedding`` (a raw query vector → kNN directly, skipping the text-embed step — "embedding activation" for callers that already hold a vector).
  - `query_text` string, nullable
  - `embedding` number[], nullable
  - `scope` string[], nullable
  - `content_types` string[], nullable
  - `use_hybrid` boolean, nullable
  - `aperture` number, nullable
  - `from_` integer
  - `size` integer
  - `sort` 'relevance' | 'recency', nullable
  - `highlight` boolean

## Response `200`

Successful Response

- ArtifactSearchResponse
  - `hits` SearchHitResponse[], required
    - `id` string, required
    - `score` number, required
    - `root_id` string, required
    - `version_id` string, required
    - `collection_id` string, nullable
    - `title` string, nullable
    - `description` string, nullable
    - `content` string, nullable
    - `tags` string[], nullable
    - `highlights` object, nullable
  - `total` integer, required
  - `query_text` string, required
  - `parsed_query` string, nullable
  - `corrections` string[]
  - `used_hybrid` boolean, required
  - `from_` integer
  - `size` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agience/apis/agience-platform-api.md) · [All operations](https://skmtc.net/agience/apis/agience-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agience/agience-platform-api/versions/187bad270c94/schema)