Search API

3 operations. Authentication, errors and pagination work as described in the REST API overview.

Related prompts

GET/api/v1/prompts/{owner}/{slug}/relatedToken optional

Precomputed by the worker from embedding similarity, shared tags and co-stars (a shared-tags fallback before it has run), filtered to what the caller may see.

getRelatedPrompts parameters
Name	Type	Description
`owner` pathrequired	`string`	Owner handle
`slug` pathrequired	`string`	Prompt slug
`limit` query	`integer (1–50)`	Default 10, max 50

Responses: 200 OK304, 400, 404, 429

Response fields

getRelatedPrompts response fields
Name	Type	Description
`items`required	`object[]`

Example

curl 'https://incantory.ai/api/v1/prompts/{owner}/{slug}/related' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Hybrid prompt search

GET/api/v1/searchToken optional

Full-text (weighted title/handle > summary/tags > body) + title trigram + semantic (pgvector) retrieval, fused with reciprocal-rank fusion (k=60) plus a small popularity boost. Keyset-paginated with an opaque cursor tied to the query. When the embedding gateway is unavailable the response is keyword-only with usedFallback: true. Filters narrow every branch; model means "works on". Drafts, private and unlisted prompts are only ever returned to their owner. Branch timings are in the Server-Timing header.

search parameters
Name	Type	Description
`q` query	`string`	Search text. Inline filters such as `kind:skill tag:coding by:@alice` are lifted out of it.
`kind` query	`"text" \| "chat" \| "image" \| "video" \| "skill" \| "rules" \| "agent"`	Prompt kind
`tag` query	`string`	Tag slug
`model` query	`string`	Model slug: prompts that work on it (targets it, verified on it, or crowd-voted as working)
`source` query	`string`	Ingest source slug, e.g. fabric
`license` query	`string`	SPDX id, e.g. CC-BY-4.0
`owner` query	`string`	Owner handle (with or without @)
`rating` query	`"general" \| "mature"`	Content rating; mature only narrows for viewers who may see it
`mode` query	`"hybrid" \| "keyword"`	hybrid (default): keyword + semantic, fused with RRF; keyword: full-text and trigram only
`cursor` query	`string`
`limit` query	`integer (1–50)`	Page size (default 20, max 50)

Responses: 200 OK304, 400, 404, 429

Response fields

search response fields
Name	Type	Description
`items`required	`object[]`
`nextCursor`required	`string \| null`
`mode`required	`"hybrid" \| "keyword"`
`usedFallback`required	`boolean`	True when hybrid was expected but the semantic side was unavailable; results are keyword-only
`fallbackReason`	`"gateway_down" \| "circuit_open" \| "timeout" \| "bad_response" \| "no_embeddings" \| "vector_error"`
`query`required	`object`
`candidates`required	`number`

Example

curl 'https://incantory.ai/api/v1/search' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Typeahead suggestions: prompt titles, tags, users (and collections, makes, posts via types)

GET/api/v1/search/typeaheadToken optional

searchTypeahead parameters
Name	Type	Description
`q` queryrequired	`string`	At least 2 characters
`limit` query	`integer (1–10)`
`types` query	`string`	Comma-separated entity types to return: prompts, tags, users, collections, makes, posts, (default prompts,tags,users). Types not asked for come back as empty arrays.

Responses: 200 OK400, 404, 429

Response fields

searchTypeahead response fields
Name	Type	Description
`prompts`required	`object[]`
`tags`required	`object[]`
`users`required	`object[]`
`collections`required	`object[]`	Public collections (only when types includes collections)
`makes`required	`object[]`	Published makes (only when types includes makes)
`posts`required	`object[]`	Published blog posts (only when types includes posts)

Example

curl 'https://incantory.ai/api/v1/search/typeahead' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"