Contests API

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

List contests

GET/api/v1/contestsPublic

status=open (closing soonest first, the default), upcoming (opening soonest first) or past (judging and closed, most recent first). Keyset cursor. Drafts are never listed.

listContests parameters
Name	Type	Description
`status` query	`"open" \| "upcoming" \| "past"`
`cursor` query	`string`
`limit` query	`integer (1–100)`

Responses: 200 OK304, 400, 404, 429

Response fields

listContests 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/contests'

Get a contest

GET/api/v1/contests/{slug}Token optional

Brief, rules and prizes (markdown), dates, required tags and prompts, judges, the winners once announced, and what the caller may do (enter, vote, judge).

getContest parameters
Name	Type	Description
`slug` pathrequired	`string`	Contest slug

Responses: 200 OK400, 404, 429

Response fields

getContest response fields
Name	Type	Description
`contest`required	`object`
`requiredPrompts`required	`object[]`
`judges`required	`object[]`
`entryCount`required	`integer (-9007199254740991–9007199254740991)`
`winners`required	`object[]`
`viewer`required	`object`

Example

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

Your work that could be entered

GET/api/v1/contests/{slug}/eligibleToken required

Your recent published makes and prompts, each with the requirements it does not meet (empty = eligible) and whether it is already entered.

contestEligible parameters
Name	Type	Description
`slug` pathrequired	`string`	Contest slug

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

Response fields

contestEligible response fields
Name	Type	Description
`open`required	`boolean`
`items`required	`object[]`

Example

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

List entries

GET/api/v1/contests/{slug}/entriesToken optional

Accepted entries, newest first (keyset cursor). mine=1 lists your own entries in every state.

listContestEntries parameters
Name	Type	Description
`slug` pathrequired	`string`	Contest slug
`cursor` query	`string`
`limit` query	`integer (1–100)`
`mine` query	`"1" \| "true"`

Responses: 200 OK304, 400, 404, 429

Response fields

listContestEntries 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/contests/{slug}/entries' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Enter a make or prompt

POST/api/v1/contests/{slug}/entriesToken required

Only while the contest is open, only your own public, published work, and only work that carries every required tag and (if the contest names prompts) links or is/forks one of them. 422 requirements_not_met lists what is missing.

enterContest parameters
Name	Type	Description
`slug` pathrequired	`string`	Contest slug

Request body

Type: object

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

Response fields

enterContest response fields
Name	Type	Description
`id`required	`string`
`status`required	`"accepted"`

Example

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

Withdraw your entry

DELETE/api/v1/contests/{slug}/entries/{id}Token required

Before entries close.

withdrawContestEntry parameters
Name	Type	Description
`slug` pathrequired	`string`	Contest slug
`id` pathrequired	`string`	Entry id

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

Example

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

Score an entry (judges)

PUT/api/v1/contests/{slug}/entries/{id}/scoreToken required

A judge of this contest (or an admin) while it is being judged. 0–10 in steps of 0.5, with optional private notes.

scoreContestEntry parameters
Name	Type	Description
`slug` pathrequired	`string`	Contest slug
`id` pathrequired	`string`	Entry id

Request body

scoreContestEntry body fields
Name	Type	Description
`score`required	`number (0–10)`
`notes`	`string \| null`

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

Response fields

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

Example

curl -X PUT 'https://incantory.ai/api/v1/contests/{slug}/entries/{id}/score' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"score":0}'

Vote for an entry

POST/api/v1/contests/{slug}/entries/{id}/voteToken required

Community voting runs while the contest is judged. Not for your own entry; accounts must be 7 days old. Votes are weighted by the voter's reputation tier when winners are ranked.

voteContestEntry parameters
Name	Type	Description
`slug` pathrequired	`string`	Contest slug
`id` pathrequired	`string`	Entry id

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

Response fields

voteContestEntry response fields
Name	Type	Description
`voted`required	`boolean`
`votes`required	`integer (-9007199254740991–9007199254740991)`

Example

curl -X POST 'https://incantory.ai/api/v1/contests/{slug}/entries/{id}/vote' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Remove your vote

DELETE/api/v1/contests/{slug}/entries/{id}/voteToken required

unvoteContestEntry parameters
Name	Type	Description
`slug` pathrequired	`string`	Contest slug
`id` pathrequired	`string`	Entry id

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

Response fields

unvoteContestEntry response fields
Name	Type	Description
`voted`required	`boolean`
`votes`required	`integer (-9007199254740991–9007199254740991)`

Example

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