Imports API

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

Your recent imports

GET/api/v1/importsToken required

Newest first, keyset-paginated (cursor).

listImports parameters
Name	Type	Description
`cursor` query	`string`
`limit` query	`integer (1–50)`

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

Response fields

listImports 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/imports' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Start an import (paste, URL, GitHub repo/folder, folder files)

POST/api/v1/importsToken required · scope write

Paste and Incantory URLs answer 201, finished. URL (raw file, GitHub file/folder, gist, Hugging Face, prompts.chat), GitHub and folder imports answer 202 and are processed by the worker: poll GET /api/v1/imports/{id}. Foreign placeholders ([VAR], ${var}, {var}) are converted to {{var}}.

Request body

Type: object

Responses: 202 Queued (201 when already finished: paste and Incantory URLs)400, 401, 403, 404, 413, 429

Response fields

createImport response fields
Name	Type	Description
`id`required	`string`
`kind`required	`string`
`status`required	`string`	pending, running, awaiting_selection, done, failed, cancelled
`stage`required	`string`
`error`required	`string \| null`
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`finishedAt`required	`string \| null`
`source`required	`object \| null`
`license`required	`object \| null`
`warnings`required	`string[]`
`items`required	`object[]`
`conversations`required	`object[] \| null`	Chat-export conversations to pick messages from
`existing`required	`object \| null`	An existing prompt with the same content
`upload`required	`object \| null`
`created`required	`object[]`
`failed`required	`object[]`

Example

curl -X POST 'https://incantory.ai/api/v1/imports' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"kind":"paste","text":"text"}'

Import status, detected items, dedup hints and results

GET/api/v1/imports/{id}Token required

getImport parameters
Name	Type	Description
`id` pathrequired	`string`

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

Response fields

getImport response fields
Name	Type	Description
`id`required	`string`
`kind`required	`string`
`status`required	`string`	pending, running, awaiting_selection, done, failed, cancelled
`stage`required	`string`
`error`required	`string \| null`
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`finishedAt`required	`string \| null`
`source`required	`object \| null`
`license`required	`object \| null`
`warnings`required	`string[]`
`items`required	`object[]`
`conversations`required	`object[] \| null`	Chat-export conversations to pick messages from
`existing`required	`object \| null`	An existing prompt with the same content
`upload`required	`object \| null`
`created`required	`object[]`
`failed`required	`object[]`

Example

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

Cancel an import

POST/api/v1/imports/{id}/cancelToken required · scope write

cancelImport parameters
Name	Type	Description
`id` pathrequired	`string`

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

Response fields

cancelImport response fields
Name	Type	Description
`id`required	`string`
`kind`required	`string`
`status`required	`string`	pending, running, awaiting_selection, done, failed, cancelled
`stage`required	`string`
`error`required	`string \| null`
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`finishedAt`required	`string \| null`
`source`required	`object \| null`
`license`required	`object \| null`
`warnings`required	`string[]`
`items`required	`object[]`
`conversations`required	`object[] \| null`	Chat-export conversations to pick messages from
`existing`required	`object \| null`	An existing prompt with the same content
`upload`required	`object \| null`
`created`required	`object[]`
`failed`required	`object[]`

Example

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

Import the selected items as draft prompts

POST/api/v1/imports/{id}/commitToken required · scope write

Each selected package or chat message becomes a draft prompt. URL/GitHub imports record a SourceAttribution; the detected license must be confirmed, or ownWork asserted when it is unknown.

commitImport parameters
Name	Type	Description
`id` pathrequired	`string`

Request body

commitImport body fields
Name	Type	Description
`items`	`object[]`
`messages`	`object[]`
`license`required	`object`
`visibility`	`"public" \| "unlisted"`

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

Response fields

commitImport response fields
Name	Type	Description
`id`required	`string`
`kind`required	`string`
`status`required	`string`	pending, running, awaiting_selection, done, failed, cancelled
`stage`required	`string`
`error`required	`string \| null`
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`finishedAt`required	`string \| null`
`source`required	`object \| null`
`license`required	`object \| null`
`warnings`required	`string[]`
`items`required	`object[]`
`conversations`required	`object[] \| null`	Chat-export conversations to pick messages from
`existing`required	`object \| null`	An existing prompt with the same content
`upload`required	`object \| null`
`created`required	`object[]`
`failed`required	`object[]`

Example

curl -X POST 'https://incantory.ai/api/v1/imports/{id}/commit' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"license":{"spdx":"CC0-1.0","confirmed":true}}'

Upload the next chunk

POST/api/v1/imports/{id}/uploadToken required · scope write

appendImportUpload parameters
Name	Type	Description
`id` pathrequired	`string`
`offset` queryrequired	`integer (0–20971520)`	Byte offset of this chunk

Request body

Type: string

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

Response fields

appendImportUpload response fields
Name	Type	Description
`id`required	`string`
`kind`required	`string`
`status`required	`string`	pending, running, awaiting_selection, done, failed, cancelled
`stage`required	`string`
`error`required	`string \| null`
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`finishedAt`required	`string \| null`
`source`required	`object \| null`
`license`required	`object \| null`
`warnings`required	`string[]`
`items`required	`object[]`
`conversations`required	`object[] \| null`	Chat-export conversations to pick messages from
`existing`required	`object \| null`	An existing prompt with the same content
`upload`required	`object \| null`
`created`required	`object[]`
`failed`required	`object[]`

Example

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

Upload a zip or chat export (first chunk)

POST/api/v1/imports/uploadToken required · scope write

A prompt-pack zip, or a ChatGPT (conversations.json / export zip) or Claude export, up to 20 MB, in 6 MB chunks. Send the first chunk here; the rest to /api/v1/imports/{id}/upload. Nothing from a chat export is kept except the messages you import.

startImportUpload parameters
Name	Type	Description
`kind` queryrequired	`"zip" \| "chat_export"`
`size` queryrequired	`integer (1–20971520)`	Total size of the file in bytes
`filename` query	`string`

Request body

Type: string

Responses: 202 OK400, 401, 403, 404, 413, 429

Response fields

startImportUpload response fields
Name	Type	Description
`id`required	`string`
`kind`required	`string`
`status`required	`string`	pending, running, awaiting_selection, done, failed, cancelled
`stage`required	`string`
`error`required	`string \| null`
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`finishedAt`required	`string \| null`
`source`required	`object \| null`
`license`required	`object \| null`
`warnings`required	`string[]`
`items`required	`object[]`
`conversations`required	`object[] \| null`	Chat-export conversations to pick messages from
`existing`required	`object \| null`	An existing prompt with the same content
`upload`required	`object \| null`
`created`required	`object[]`
`failed`required	`object[]`

Example

curl -X POST 'https://incantory.ai/api/v1/imports/upload' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '"string"'