Examples API

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

Approve a submitted example (prompt owner or admin)

POST/api/v1/examples/{id}/approveToken required · scope write

approveExample parameters
Name	Type	Description
`id` pathrequired	`string`	Example id

Request body (optional)

approveExample body fields
Name	Type	Description
`notes`	`string \| null`

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

Response fields

approveExample response fields
Name	Type	Description
`id`required	`string`
`versionNumber`required	`integer (-9007199254740991–9007199254740991)`
`model`required	`object \| null`
`variables`required	`object`
`outputText`required	`string`
`mediaIds`required	`string[]`
`author`required	`object`
`approval`required	`"pending" \| "approved" \| "rejected"`
`notes`required	`string \| null`
`position`required	`integer (-9007199254740991–9007199254740991)`
`contentRating`required	`"general" \| "mature" \| "explicit"`
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`updatedAt`required	`string`	ISO 8601 timestamp (UTC)
`viewer`required	`object`

Example

curl -X POST 'https://incantory.ai/api/v1/examples/{id}/approve' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

Reject a submitted example (prompt owner or admin)

POST/api/v1/examples/{id}/rejectToken required · scope write

rejectExample parameters
Name	Type	Description
`id` pathrequired	`string`	Example id

Request body (optional)

rejectExample body fields
Name	Type	Description
`notes`	`string \| null`

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

Response fields

rejectExample response fields
Name	Type	Description
`id`required	`string`
`versionNumber`required	`integer (-9007199254740991–9007199254740991)`
`model`required	`object \| null`
`variables`required	`object`
`outputText`required	`string`
`mediaIds`required	`string[]`
`author`required	`object`
`approval`required	`"pending" \| "approved" \| "rejected"`
`notes`required	`string \| null`
`position`required	`integer (-9007199254740991–9007199254740991)`
`contentRating`required	`"general" \| "mature" \| "explicit"`
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`updatedAt`required	`string`	ISO 8601 timestamp (UTC)
`viewer`required	`object`

Example

curl -X POST 'https://incantory.ai/api/v1/examples/{id}/reject' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

List approved examples (plus your queue)

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

Approved examples in the author's order, keyset-paginated (cursor). model filters by model slug, version by version number. Signed-in callers also get queue: every pending example for the prompt owner/admins, otherwise their own pending and rejected submissions.

listExamples parameters
Name	Type	Description
`owner` pathrequired	`string`	Owner handle
`slug` pathrequired	`string`	Prompt slug
`version` query	`integer (…–9007199254740991)`
`model` query	`string`
`cursor` query	`string`
`limit` query	`integer (1–100)`

Responses: 200 OK304, 400, 404, 429

Response fields

listExamples response fields
Name	Type	Description
`items`required	`object[]`
`nextCursor`required	`string \| null`
`queue`required	`object[]`	Pending examples you may see
`pendingCount`required	`integer (-9007199254740991–9007199254740991) \| null`
`canModerate`required	`boolean`
`signedIn`required	`boolean`

Example

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

Submit an example output

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

Pending until the prompt owner approves it (the owner is notified); the owner's own examples are approved immediately. mediaIds must be media you uploaded.

createExample parameters
Name	Type	Description
`owner` pathrequired	`string`	Owner handle
`slug` pathrequired	`string`	Prompt slug

Request body

createExample body fields
Name	Type	Description
`version`	`integer (…–9007199254740991)`
`model`	`string \| null`
`variables`	`object`
`outputText`	`string`
`mediaIds`	`string[]`
`notes`	`string \| null`
`contentRating`	`"general" \| "mature"`

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

Response fields

createExample response fields
Name	Type	Description
`id`required	`string`
`versionNumber`required	`integer (-9007199254740991–9007199254740991)`
`model`required	`object \| null`
`variables`required	`object`
`outputText`required	`string`
`mediaIds`required	`string[]`
`author`required	`object`
`approval`required	`"pending" \| "approved" \| "rejected"`
`notes`required	`string \| null`
`position`required	`integer (-9007199254740991–9007199254740991)`
`contentRating`required	`"general" \| "mature" \| "explicit"`
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`updatedAt`required	`string`	ISO 8601 timestamp (UTC)
`viewer`required	`object`

Example

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

Get one example

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

getExample parameters
Name	Type	Description
`owner` pathrequired	`string`	Owner handle
`slug` pathrequired	`string`	Prompt slug
`id` pathrequired	`string`	Example id

Responses: 200 OK400, 404, 429

Response fields

getExample response fields
Name	Type	Description
`id`required	`string`
`versionNumber`required	`integer (-9007199254740991–9007199254740991)`
`model`required	`object \| null`
`variables`required	`object`
`outputText`required	`string`
`mediaIds`required	`string[]`
`author`required	`object`
`approval`required	`"pending" \| "approved" \| "rejected"`
`notes`required	`string \| null`
`position`required	`integer (-9007199254740991–9007199254740991)`
`contentRating`required	`"general" \| "mature" \| "explicit"`
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`updatedAt`required	`string`	ISO 8601 timestamp (UTC)
`viewer`required	`object`

Example

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

Edit your example

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

Editing an approved example on someone else's prompt sends it back for approval.

updateExample parameters
Name	Type	Description
`owner` pathrequired	`string`	Owner handle
`slug` pathrequired	`string`	Prompt slug
`id` pathrequired	`string`	Example id

Request body

updateExample body fields
Name	Type	Description
`model`	`string \| null`
`variables`	`object`
`outputText`	`string`
`mediaIds`	`string[]`
`notes`	`string \| null`
`contentRating`	`"general" \| "mature"`

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

Response fields

updateExample response fields
Name	Type	Description
`id`required	`string`
`versionNumber`required	`integer (-9007199254740991–9007199254740991)`
`model`required	`object \| null`
`variables`required	`object`
`outputText`required	`string`
`mediaIds`required	`string[]`
`author`required	`object`
`approval`required	`"pending" \| "approved" \| "rejected"`
`notes`required	`string \| null`
`position`required	`integer (-9007199254740991–9007199254740991)`
`contentRating`required	`"general" \| "mature" \| "explicit"`
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`updatedAt`required	`string`	ISO 8601 timestamp (UTC)
`viewer`required	`object`

Example

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

Delete an example (author, prompt owner or admin)

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

deleteExample parameters
Name	Type	Description
`owner` pathrequired	`string`	Owner handle
`slug` pathrequired	`string`	Prompt slug
`id` pathrequired	`string`	Example id

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

Example

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

Set the order of approved examples (prompt owner or admin)

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

reorderExamples parameters
Name	Type	Description
`owner` pathrequired	`string`	Owner handle
`slug` pathrequired	`string`	Prompt slug

Request body

reorderExamples body fields
Name	Type	Description
`ids`required	`string[]`

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

Response fields

reorderExamples response fields
Name	Type	Description
`updated`required	`integer (-9007199254740991–9007199254740991)`

Example

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