Prompts API

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

List and search prompts

GET/api/v1/promptsToken optional

Keyset-paginated. q runs full-text + trigram search ordered by relevance unless sort is given. Drafts, private and unlisted prompts are listed only to their owner.

listPrompts parameters
Name	Type	Description
`q` query	`string`
`owner` query	`string`
`tag` query	`string`
`kind` query	`"text" \| "chat" \| "image" \| "video" \| "skill" \| "rules" \| "agent"`
`model` query	`string`
`source` query	`string`
`sort` query	`"new" \| "top" \| "updated"`
`cursor` query	`string`
`limit` query	`integer (1–100)`

Responses: 200 OK304, 400, 404, 429

Response fields

listPrompts response fields
Name	Type	Description
`items`required	`object[]`
`nextCursor`required	`string \| null`

Example

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

Create a prompt (published v1, or a draft with publish=false)

POST/api/v1/promptsToken required · scope write

Request body

createPrompt body fields
Name	Type	Description
`slug`required	`string`
`title`required	`string`
`summary`	`string`
`kind`	`"text" \| "chat" \| "image" \| "video" \| "skill" \| "rules" \| "agent"`
`licenseSpdx`	`"CC0-1.0" \| "CC-BY-4.0" \| "CC-BY-SA-4.0" \| "MIT" \| "Apache-2.0"`	Defaults to CC-BY-4.0
`tags`	`string[]`
`contentRating`	`"general" \| "mature"`
`visibility`	`"public" \| "unlisted"`
`publish`	`boolean`	false keeps the prompt as a draft (PLAN §14c.3). Default true.
`message`	`string`
`files`required	`object[]`
`frontmatter`	`object`

Responses: 201 OK400, 401, 403, 404, 409, 413, 422, 429

Response fields

createPrompt response fields
Name	Type	Description
`id`required	`string`
`ref`required	`string`
`owner`required	`object`
`slug`required	`string`
`title`required	`string`
`summary`required	`string`
`kind`required	`"text" \| "chat" \| "image" \| "video" \| "skill" \| "rules" \| "agent"`
`licenseSpdx`required	`string`
`contentRating`required	`"general" \| "mature" \| "explicit"`
`visibility`required	`"public" \| "unlisted" \| "private"`
`publishState`required	`"draft" \| "published"`
`tags`required	`string[]`
`starCount`required	`integer (-9007199254740991–9007199254740991)`
`forkCount`required	`integer (-9007199254740991–9007199254740991)`
`makeCount`required	`integer (-9007199254740991–9007199254740991)`
`latestVersion`required	`integer (-9007199254740991–9007199254740991) \| null`
`riskLevel`required	`"unscanned" \| "low" \| "med" \| "high"`
`updatedAt`required	`string`
`publishedAt`required	`string \| null`
`version`required	`object`
`labels`required	`object[]`
`forkedFrom`required	`object \| null`
`attribution`required	`object \| null`
`attributionChain`required	`object[]`
`unmodifiedFork`required	`boolean`
`canonicalPath`required	`string`
`viewer`required	`object`
`hasDraft`required	`boolean`

Example

curl -X POST 'https://incantory.ai/api/v1/prompts' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"slug":"slug","title":"title","files":[{"path":"path","content":"content"}]}'

Get a prompt at its latest version, a pinned version or a label

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

Pinned versions are served with Cache-Control: immutable; yanked versions carry a Deprecation header. With format= the response is a download instead of JSON. A renamed slug answers 301.

getPrompt parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`
`version` query	`integer (…–999999999)`
`label` query	`string`
`format` query	`"zip" \| "tar" \| "skill" \| "cursor-mdc" \| "copilot-instructions" \| "copilot-agent" \| "claude-agent" \| "agents-md" \| "claude-md" \| "gemini-md" \| "plain"`	Return a download in this format instead of JSON (PLAN §14c.12)

Responses: 200 OK301, 304, 400, 404, 410, 429

Response fields

getPrompt response fields
Name	Type	Description
`id`required	`string`
`ref`required	`string`
`owner`required	`object`
`slug`required	`string`
`title`required	`string`
`summary`required	`string`
`kind`required	`"text" \| "chat" \| "image" \| "video" \| "skill" \| "rules" \| "agent"`
`licenseSpdx`required	`string`
`contentRating`required	`"general" \| "mature" \| "explicit"`
`visibility`required	`"public" \| "unlisted" \| "private"`
`publishState`required	`"draft" \| "published"`
`tags`required	`string[]`
`starCount`required	`integer (-9007199254740991–9007199254740991)`
`forkCount`required	`integer (-9007199254740991–9007199254740991)`
`makeCount`required	`integer (-9007199254740991–9007199254740991)`
`latestVersion`required	`integer (-9007199254740991–9007199254740991) \| null`
`riskLevel`required	`"unscanned" \| "low" \| "med" \| "high"`
`updatedAt`required	`string`
`publishedAt`required	`string \| null`
`version`required	`object`
`labels`required	`object[]`
`forkedFrom`required	`object \| null`
`attribution`required	`object \| null`
`attributionChain`required	`object[]`
`unmodifiedFork`required	`boolean`
`canonicalPath`required	`string`
`viewer`required	`object`
`hasDraft`required	`boolean`

Example

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

Edit metadata (title, summary, tags, license, visibility, rating, slug)

PATCH/api/v1/prompts/{owner}/{slug}Token required · scope write

Renaming the slug writes a 301 redirect from the old path (and every sub-path). Forks may only relicense within their parent's fork policy.

updatePrompt parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`

Request body

updatePrompt body fields
Name	Type	Description
`slug`	`string`
`title`	`string`
`summary`	`string`
`licenseSpdx`	`string`
`tags`	`string[]`
`contentRating`	`"general" \| "mature"`
`visibility`	`"public" \| "unlisted"`

Responses: 200 OK400, 401, 403, 404, 409, 410, 422, 429

Response fields

updatePrompt response fields
Name	Type	Description
`id`required	`string`
`ref`required	`string`
`owner`required	`object`
`slug`required	`string`
`title`required	`string`
`summary`required	`string`
`kind`required	`"text" \| "chat" \| "image" \| "video" \| "skill" \| "rules" \| "agent"`
`licenseSpdx`required	`string`
`contentRating`required	`"general" \| "mature" \| "explicit"`
`visibility`required	`"public" \| "unlisted" \| "private"`
`publishState`required	`"draft" \| "published"`
`tags`required	`string[]`
`starCount`required	`integer (-9007199254740991–9007199254740991)`
`forkCount`required	`integer (-9007199254740991–9007199254740991)`
`makeCount`required	`integer (-9007199254740991–9007199254740991)`
`latestVersion`required	`integer (-9007199254740991–9007199254740991) \| null`
`riskLevel`required	`"unscanned" \| "low" \| "med" \| "high"`
`updatedAt`required	`string`
`publishedAt`required	`string \| null`
`version`required	`object`
`labels`required	`object[]`
`forkedFrom`required	`object \| null`
`attribution`required	`object \| null`
`attributionChain`required	`object[]`
`unmodifiedFork`required	`boolean`
`canonicalPath`required	`string`
`viewer`required	`object`
`hasDraft`required	`boolean`

Example

curl -X PATCH 'https://incantory.ai/api/v1/prompts/{owner}/{slug}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

Soft-delete a prompt (it answers 410 afterwards)

DELETE/api/v1/prompts/{owner}/{slug}Token required · scope write

deletePrompt parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`

Responses: 204 OK400, 401, 403, 404, 429

Example

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

Diff two versions (`{range}` is `a..b`)

GET/api/v1/prompts/{owner}/{slug}/diff/{range}Token optional

File-level status with both texts, plus frontmatter and variables before/after. Unchanged files omit their content.

diffVersions parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`
`range` pathrequired	`string`

Responses: 200 OK304, 400, 404, 429

Response fields

diffVersions response fields
Name	Type	Description
`from`required	`integer (-9007199254740991–9007199254740991)`
`to`required	`integer (-9007199254740991–9007199254740991)`
`files`required	`object[]`
`frontmatter`required	`object`
`variables`required	`object`

Example

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

Download as zip / tar.gz or converted to a tool format

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

Lossy conversions list what was dropped in the X-Incantory-Warnings header.

downloadPrompt parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`
`version` query	`integer (…–999999999)`
`label` query	`string`
`format` query	`"zip" \| "tar" \| "skill" \| "cursor-mdc" \| "copilot-instructions" \| "copilot-agent" \| "claude-agent" \| "agents-md" \| "claude-md" \| "gemini-md" \| "plain"`

Responses: 200 The file or archive304, 400, 404, 429

Example

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

Get the working draft (owner only; null when none)

GET/api/v1/prompts/{owner}/{slug}/draftToken required

getDraft parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`

Responses: 200 OK400, 401, 403, 404, 429

Example

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

Save the working draft

PUT/api/v1/prompts/{owner}/{slug}/draftToken required · scope write

saveDraft parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`

Request body

saveDraft body fields
Name	Type	Description
`files`required	`object[]`
`frontmatter`	`object`
`message`	`string`

Responses: 204 OK400, 401, 403, 404, 410, 413, 422, 429

Example

curl -X PUT 'https://incantory.ai/api/v1/prompts/{owner}/{slug}/draft' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"files":[{"path":"path","content":"content"}]}'

Discard the working draft

DELETE/api/v1/prompts/{owner}/{slug}/draftToken required · scope write

discardDraft parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`

Responses: 204 OK400, 401, 403, 404, 409, 429

Example

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

Fork into your namespace

POST/api/v1/prompts/{owner}/{slug}/forksToken required · scope write

Copies a version (default: latest) into a new prompt. The license follows the parent's fork policy; a taken slug gets a numeric suffix.

forkPrompt parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`

Request body (optional)

forkPrompt body fields
Name	Type	Description
`version`	`integer (…–9007199254740991)`
`slug`	`string`
`licenseSpdx`	`string`

Responses: 201 OK400, 401, 403, 404, 409, 422, 429

Response fields

forkPrompt response fields
Name	Type	Description
`id`required	`string`
`ref`required	`string`
`owner`required	`object`
`slug`required	`string`
`title`required	`string`
`summary`required	`string`
`kind`required	`"text" \| "chat" \| "image" \| "video" \| "skill" \| "rules" \| "agent"`
`licenseSpdx`required	`string`
`contentRating`required	`"general" \| "mature" \| "explicit"`
`visibility`required	`"public" \| "unlisted" \| "private"`
`publishState`required	`"draft" \| "published"`
`tags`required	`string[]`
`starCount`required	`integer (-9007199254740991–9007199254740991)`
`forkCount`required	`integer (-9007199254740991–9007199254740991)`
`makeCount`required	`integer (-9007199254740991–9007199254740991)`
`latestVersion`required	`integer (-9007199254740991–9007199254740991) \| null`
`riskLevel`required	`"unscanned" \| "low" \| "med" \| "high"`
`updatedAt`required	`string`
`publishedAt`required	`string \| null`
`version`required	`object`
`labels`required	`object[]`
`forkedFrom`required	`object \| null`
`attribution`required	`object \| null`
`attributionChain`required	`object[]`
`unmodifiedFork`required	`boolean`
`canonicalPath`required	`string`
`viewer`required	`object`
`hasDraft`required	`boolean`

Example

curl -X POST 'https://incantory.ai/api/v1/prompts/{owner}/{slug}/forks' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

List labels

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

listLabels parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`

Responses: 200 OK304, 400, 404, 429

Example

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

Create or move a label

PUT/api/v1/prompts/{owner}/{slug}/labels/{name}Token required · scope write

A label cannot point at a yanked version (403 version_yanked). With requirePassingEval the target version needs a passing EvalRun: the latest finished run decides (403 eval_required). evalDatasetId narrows that to the latest run over one dataset of this prompt (404 dataset_not_found if it is not one). Every move is recorded in the label history.

setLabel parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`
`name` pathrequired	`string`

Request body

setLabel body fields
Name	Type	Description
`version`required	`integer (…–9007199254740991)`
`protected`	`boolean`
`requirePassingEval`	`boolean`
`evalDatasetId`	`string`
`reason`	`string`

Responses: 200 OK400, 401, 403, 404, 410, 422, 429

Response fields

setLabel response fields
Name	Type	Description
`name`required	`string`
`versionNumber`required	`integer (-9007199254740991–9007199254740991)`
`protected`required	`boolean`
`requirePassingEval`required	`boolean`
`updatedAt`required	`string`

Example

curl -X PUT 'https://incantory.ai/api/v1/prompts/{owner}/{slug}/labels/{name}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"version":1}'

Delete a label

DELETE/api/v1/prompts/{owner}/{slug}/labels/{name}Token required · scope write

deleteLabel parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`
`name` pathrequired	`string`

Responses: 204 OK400, 401, 403, 404, 410, 429

Example

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

Label move history, newest first

GET/api/v1/prompts/{owner}/{slug}/labels/{name}/historyToken optional

labelHistory parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`
`name` pathrequired	`string`

Responses: 200 OK304, 400, 404, 429

Example

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

The entry file as text (or `?path=`)

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

rawEntry parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`
`version` query	`integer (…–999999999)`
`label` query	`string`
`path` query	`string`

Responses: 200 The file304, 400, 404, 429

Example

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

One file of a version as text

GET/api/v1/prompts/{owner}/{slug}/raw/{path}Token optional

rawFile parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`
`path` pathrequired	`string`	File path within the package (may contain "/")
`version` query	`integer (…–999999999)`
`label` query	`string`

Responses: 200 The file304, 400, 404, 429

Example

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

List versions, newest first (yanked versions only for the owner)

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

listVersions parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`
`cursor` query	`string`
`limit` query	`integer (1–100)`

Responses: 200 OK304, 400, 404, 429

Response fields

listVersions response fields
Name	Type	Description
`items`required	`object[]`
`nextCursor`required	`string \| null`

Example

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

Commit a new immutable version (from the body, or the saved draft when files are omitted)

POST/api/v1/prompts/{owner}/{slug}/versionsToken required · scope write

commitVersion parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`

Request body (optional)

commitVersion body fields
Name	Type	Description
`files`	`object[]`	Omit to commit the saved draft
`frontmatter`	`object`
`message`	`string`
`baseVersion`	`integer (…–9007199254740991)`	Optimistic concurrency: the version you edited from; 409 stale_base if it is not the latest

Responses: 201 OK400, 401, 403, 404, 409, 410, 413, 422, 429

Response fields

commitVersion response fields
Name	Type	Description
`number`required	`integer (-9007199254740991–9007199254740991)`
`message`required	`string`
`author`required	`object \| null`
`contentHash`required	`string`
`createdAt`required	`string`
`yanked`required	`boolean`
`labels`required	`string[]`

Example

curl -X POST 'https://incantory.ai/api/v1/prompts/{owner}/{slug}/versions' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

Get one version with its files (immutable)

GET/api/v1/prompts/{owner}/{slug}/versions/{n}Token optional

getVersion parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`
`n` pathrequired	`integer (…–999999999)`

Responses: 200 OK304, 400, 404, 429

Response fields

getVersion response fields
Name	Type	Description
`number`required	`integer (-9007199254740991–9007199254740991)`
`message`required	`string`
`author`required	`object \| null`
`contentHash`required	`string`
`createdAt`required	`string`
`yanked`required	`boolean`
`labels`required	`string[]`
`files`required	`object[]`
`frontmatter`required	`object`
`variables`required	`object[]`
`targetModels`required	`string[]`

Example

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

Restore an old version as a new version

POST/api/v1/prompts/{owner}/{slug}/versions/{n}/restoreToken required · scope write

restoreVersion parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`
`n` pathrequired	`integer (…–999999999)`

Request body (optional)

restoreVersion body fields
Name	Type	Description
`message`	`string`

Responses: 201 OK400, 401, 403, 404, 409, 410, 429

Response fields

restoreVersion response fields
Name	Type	Description
`number`required	`integer (-9007199254740991–9007199254740991)`
`message`required	`string`
`author`required	`object \| null`
`contentHash`required	`string`
`createdAt`required	`string`
`yanked`required	`boolean`
`labels`required	`string[]`

Example

curl -X POST 'https://incantory.ai/api/v1/prompts/{owner}/{slug}/versions/{n}/restore' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

Yank a version (hidden from lists, cannot be labelled; still served when pinned)

POST/api/v1/prompts/{owner}/{slug}/versions/{n}/yankToken required · scope write

yankVersion parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`
`n` pathrequired	`integer (…–999999999)`

Request body

yankVersion body fields
Name	Type	Description
`reason`required	`string`

Responses: 204 OK400, 401, 403, 404, 409, 410, 429

Example

curl -X POST 'https://incantory.ai/api/v1/prompts/{owner}/{slug}/versions/{n}/yank' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"reason":"reason"}'

Unyank a version

DELETE/api/v1/prompts/{owner}/{slug}/versions/{n}/yankToken required · scope write

unyankVersion parameters
Name	Type	Description
`owner` pathrequired	`string`
`slug` pathrequired	`string`
`n` pathrequired	`integer (…–999999999)`

Responses: 204 OK400, 401, 403, 404, 410, 429

Example

curl -X DELETE 'https://incantory.ai/api/v1/prompts/{owner}/{slug}/versions/{n}/yank' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"