discovery

Search artifacts

Ranked discovery over artifacts in workspaces the caller can read, across kinds. query matches name, display name, description and the extension's indexed text; filters and the scope fields narrow; fields projects.

The ranking is the order. A sorts body is rejected (400) — use GET /artifacts?sort= for an explicitly ordered browse.

L1 only. This never joins a kind's own storage, so a detail-column filter is rejected and no metadata is returned. GET /artifacts/{artifact_kind}?include_metadata=true is the surface that has both.

strategy selects the ranking: fts (default), vector, hybrid, or group — the graph filter, which returns an anchor plus its typed neighbourhood, anchor first, each item labelled with role/rel_type/direction/weight/confidence.

vector and hybrid take query as text — the registry embeds it with the same model the stored vectors were written with, so a caller needs no embedder of its own and cannot drift out of the index's space. Supply query_vector instead to rank against a probe you embedded yourself; it wins when both are sent. A deployment with no model configured answers 503 not_configured for these strategies rather than silently falling back to a recency browse; a probe the model refuses answers with the reason — 429 budget_exceeded, 422 embedding_input_too_long, 503 embedding_model_unavailable.

Query grammar. Bare words match any; "a phrase" is required; -word excludes; the last word (3+ characters) also matches as a prefix. At most 8000 characters.

project_id includes linked artifacts — those the project owns and those linked into it.

page.total is exact on fts and absent on the distance-ranked strategies: those rank a fixed 1000-deep candidate pool, a pool's size is not a match count, and offset + limit past it is refused.

post/registry/v1/search

Request

  • Base URL: https://api.atlan.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.atlan.com/registry/v1/search
  • Auth: HTTP bearer

Headers

Content-Encoding'base64' | 'gzip, base64'

Codings applied to the request body, outermost last. Send base64, or gzip, base64 to compress first; the body is decoded before it is read and Content-Type still names the inner media type. Omit for an unencoded body.

Request body

countboolean nullable

Return the exact total. Defaults to true, which is the contract (authorization.md D3): a search answers with an exact post-filter count.

false declines it, and what it declines is real work rather than a field. The count is a COUNT(*) OVER () sharing the query's own WHERE, so producing it forces the whole matching set to be materialized — a query matching 2,000 artifacts pays for 2,000 to return 20. A caller paging by "was this page full", which is what a walker actually needs, can decline it.

Opt-out, never opt-in: the default is the promise, and a client that has never heard of this field sees exactly what it saw before.

It does not remove the ranking, only the count. The ORDER BY still sorts the whole matching set, so this is a meaningful p95/p99 improvement on a broad query and not a change of asymptotics — keyset paging is the fix for that (LIMITATIONS L33).

embedding_kindstring nullable

Restrict the vector half to one declared embedding. Omitted ⇒ rank across all of them.

fieldsstring[] nullable

Return only these keys of each result. id and kind are always present, and on group so are the graph labels — projecting away the thing that distinguishes an anchor from a dependent would leave the response unreadable.

includestring[]

Opt-in embeds. permissions attaches the caller's advisory can_* capability matrix per item, resolved from the page's own read receipt; unknown tokens are ignored.

is_all_versions_includedboolean nullable

Include every live version rather than only the heads. Defaults to false.

is_archived_includedboolean nullable

Include archived artifacts. Defaults to false — an archived artifact stays readable by id but is hidden from discovery.

Left false while also filtering artifact_status to archived is a contradiction, and the answer is an empty page: the two are conjoined, not resolved in the caller's favour.

is_system_includedboolean nullable

Include artifacts the deployment wrote. Defaults to false.

kindstring nullable

Narrow to one registered kind.

limitinteger nullable

Max results. Defaults to 50; a larger value than 500 is clamped to 500, and 0 is refused.

offsetinteger nullable

Results to skip. Defaults to 0, rejected above 10000.

On vector, hybrid and group, offset + limit may not exceed 1000 (400 search_window_exceeded): those rank a fixed 1000-deep candidate pool, so a page past it has nothing to serve. A page shorter than limit is the end.

project_idstring nullable

Narrow to one project: the artifacts it owns (project_id) and the ones linked into it. Orthogonal to workspace_id — a project is a grouping inside a workspace, so both may be set and both narrow.

A project linking more than 1000 artifacts is refused (422 project_link_limit_exceeded); narrow by kind or workspace_id instead. A filters clause on project_id still matches the artifact's own column only.

querystring nullable

The free-text query, matched over name, display_name, description and the extension's search_text. Required by fts and hybrid; at most 8000 characters (400 query_too_long).

Bare words match any of them. "a quoted phrase" is required, in order. -word or -"a phrase" excludes. The last bare word, if it has three or more characters, also matches as a prefix, so a partly typed word finds its completions. A query with only exclusions is a 400.

query_vectornumber[] nullable

A probe the caller embedded itself, 1024-dim with finite components.

Optional. vector and hybrid embed query server-side, with the same model the stored vectors were written with — so a caller needs no embedder and cannot drift out of the index's space. This field remains for a caller that runs its own and wants an exact probe; it takes precedence over query when both are sent.

source_typestring nullable

Narrow to one provenance: git | atlan | local | external.

strategystring nullable

fts (the default) | vector | hybrid | group.

group is the graph filter: it resolves the top match into an anchor plus its typed neighbourhood (depends_on / next_step / alternative, both directions) and returns them anchor-first, each item carrying role / rel_type / direction / weight / confidence.

workspace_idstring nullable

Narrow to one workspace. Omitted ⇒ every workspace the caller can read. The account boundary is the verified token and never the body.

Response

A ranked page in the {items, limit, offset} envelope, total present on fts only. Each item is an artifact L1 view; on strategy:group it also carries the graph labels, anchor first.

Changes

No recorded changes to this operation across all 1 revision of this API.