Collections API

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

List collections

GET/api/v1/collectionsToken optional

Public collections, one owner's (owner=handle) or yours (mine=1), newest first.

listCollections parameters
Name	Type	Description
`owner` query	`string`
`mine` query	`"1" \| "true"`
`cursor` query	`string`

Responses: 200 OK304, 400, 404, 429

Response fields

listCollections response fields
Name	Type	Description
`items`required	`object[]`
`nextCursor`required	`string \| null`	Opaque cursor for the next page; null at the end

Example

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

Create a collection

POST/api/v1/collectionsToken required

Request body

createCollection body fields
Name	Type	Description
`title`required	`string`
`description`	`string`
`visibility`	`"public" \| "unlisted" \| "private"`

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

Response fields

createCollection response fields
Name	Type	Description
`id`required	`string`
`slug`required	`string`
`title`required	`string`
`description`required	`string`
`visibility`required	`"public" \| "unlisted" \| "private"`
`itemCount`required	`integer (-9007199254740991–9007199254740991)`
`starCount`required	`integer (-9007199254740991–9007199254740991)`
`owner`required	`object`
`url`required	`string`
`updatedAt`required	`string`	ISO 8601 timestamp (UTC)
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`viewer`required	`object`

Example

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

A collection and the items you may see

GET/api/v1/collections/{id}Token optional

getCollection parameters
Name	Type	Description
`id` pathrequired	`string`	Id

Responses: 200 OK400, 404, 429

Response fields

getCollection response fields
Name	Type	Description
`id`required	`string`
`slug`required	`string`
`title`required	`string`
`description`required	`string`
`visibility`required	`"public" \| "unlisted" \| "private"`
`itemCount`required	`integer (-9007199254740991–9007199254740991)`
`starCount`required	`integer (-9007199254740991–9007199254740991)`
`owner`required	`object`
`url`required	`string`
`updatedAt`required	`string`	ISO 8601 timestamp (UTC)
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`viewer`required	`object`
`items`required	`object[]`

Example

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

Edit a collection (owner or admin)

PATCH/api/v1/collections/{id}Token required

A slug change redirects the old URL.

updateCollection parameters
Name	Type	Description
`id` pathrequired	`string`	Id

Request body

updateCollection body fields
Name	Type	Description
`title`	`string`
`description`	`string`
`visibility`	`"public" \| "unlisted" \| "private"`
`slug`	`string`

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

Response fields

updateCollection response fields
Name	Type	Description
`id`required	`string`
`slug`required	`string`
`title`required	`string`
`description`required	`string`
`visibility`required	`"public" \| "unlisted" \| "private"`
`itemCount`required	`integer (-9007199254740991–9007199254740991)`
`starCount`required	`integer (-9007199254740991–9007199254740991)`
`owner`required	`object`
`url`required	`string`
`updatedAt`required	`string`	ISO 8601 timestamp (UTC)
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`viewer`required	`object`

Example

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

Delete a collection (owner or admin)

DELETE/api/v1/collections/{id}Token required

deleteCollection parameters
Name	Type	Description
`id` pathrequired	`string`	Id

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

Example

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

Add a prompt, make or post (idempotent)

POST/api/v1/collections/{id}/itemsToken required

addCollectionItem parameters
Name	Type	Description
`id` pathrequired	`string`	Id

Request body

addCollectionItem body fields
Name	Type	Description
`itemType`required	`"prompt" \| "make" \| "post"`
`itemId`required	`string`
`note`	`string \| null`

Responses: 201 Added (200 when it was already there, `added: false`)400, 401, 403, 404, 409, 429

Response fields

addCollectionItem response fields
Name	Type	Description
`added`required	`boolean`
`itemCount`required	`integer (-9007199254740991–9007199254740991)`

Example

curl -X POST 'https://incantory.ai/api/v1/collections/{id}/items' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"itemType":"prompt","itemId":"itemId"}'

Reorder items

PUT/api/v1/collections/{id}/itemsToken required

reorderCollection parameters
Name	Type	Description
`id` pathrequired	`string`	Id

Request body

reorderCollection body fields
Name	Type	Description
`order`required	`string[]`

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

Response fields

reorderCollection response fields
Name	Type	Description
`ok`required	`true`

Example

curl -X PUT 'https://incantory.ai/api/v1/collections/{id}/items' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"order":["order"]}'

Remove an item by its target

DELETE/api/v1/collections/{id}/itemsToken required

removeCollectionItemByTarget parameters
Name	Type	Description
`id` pathrequired	`string`	Id
`itemType` query	`"prompt" \| "make" \| "post"`
`itemId` query	`string`

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

Response fields

removeCollectionItemByTarget response fields
Name	Type	Description
`removed`required	`boolean`
`itemCount`required	`integer (-9007199254740991–9007199254740991)`

Example

curl -X DELETE 'https://incantory.ai/api/v1/collections/{id}/items' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Set the note on an item

PATCH/api/v1/collections/{id}/items/{itemId}Token required

setCollectionItemNote parameters
Name	Type	Description
`id` pathrequired	`string`	Collection id
`itemId` pathrequired	`string`	Collection item row id

Request body

setCollectionItemNote body fields
Name	Type	Description
`note`required	`string \| null`

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

Response fields

setCollectionItemNote response fields
Name	Type	Description
`ok`required	`true`

Example

curl -X PATCH 'https://incantory.ai/api/v1/collections/{id}/items/{itemId}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"note":"note"}'

Remove one item

DELETE/api/v1/collections/{id}/items/{itemId}Token required

removeCollectionItem parameters
Name	Type	Description
`id` pathrequired	`string`	Collection id
`itemId` pathrequired	`string`	Collection item row id

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

Response fields

removeCollectionItem response fields
Name	Type	Description
`removed`required	`boolean`
`itemCount`required	`integer (-9007199254740991–9007199254740991)`

Example

curl -X DELETE 'https://incantory.ai/api/v1/collections/{id}/items/{itemId}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Your collections, flagged if they contain a target

GET/api/v1/collections/membershipToken required

collectionMembership parameters
Name	Type	Description
`targetType` queryrequired	`"prompt" \| "make" \| "post"`
`targetId` queryrequired	`string`

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

Response fields

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

Example

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