REST API

List decks#

Returns every deck in the collection, including the built-in Default deck and nested decks, or only the decks whose name q accepts. A nested deck's name is its full path, such as Languages::German.

Parameters

Example request

# List decks (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/decks" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

{
  "decks": [
    {
      "id": 1,
      "name": "Default"
    },
    {
      "id": 1736899200123,
      "name": "Languages::German"
    }
  ]
}

• 401The Authorization header is missing, or the key is invalid, disabled or expired.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Create a deck#

Creates a deck and returns it. Use :: in the name to nest it under a parent, for example Languages::German.

Parameters

Request body

{
  "name": "Languages::German"
}

Example request

# Create a deck (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X POST "https://ankinize.com/api/v1/decks" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Languages::German"
  }'

Response

{
  "id": 1736899200123,
  "name": "Languages::German"
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 401The Authorization header is missing, or the key is invalid, disabled or expired.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 422The body does not match the earlier request that used this Idempotency-Key (idempotency_conflict), or the body failed validation (validation_error).
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Get a deck by ID#

Returns one deck by its numeric id.

Parameters

Example request

# Get a deck by ID (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/decks/1736899200123" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

{
  "id": 1736899200123,
  "name": "Languages::German"
}

• 404No deck, note, note type or card has that id.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Rename a deck#

Changes a deck's name. The deck keeps its id and its cards, and its subdecks are renamed with it.

Parameters

Request body

{
  "name": "Languages::Deutsch"
}

Example request

# Rename a deck (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X PATCH "https://ankinize.com/api/v1/decks/1736899200123" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Languages::Deutsch"
  }'

Response

{
  "id": 1736899200123,
  "name": "Languages::Deutsch"
}

• 404No deck, note, note type or card has that id.
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Delete a deck and its subdecks#

Deletes the deck, all of its subdecks and every card in them. Notes left with no cards are removed too.

This cannot be undone. The response lists exactly which decks and cards were removed. Deleting is still allowed while the account is over its storage quota.

Parameters

Example request

# Delete a deck and its subdecks (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X DELETE "https://ankinize.com/api/v1/decks/1736899200123" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41"

Response

{
  "ok": true,
  "deletedDeckIds": [
    1736899200123
  ],
  "defaultDeckReset": false,
  "deletedCardIds": [
    1736899300457,
    1736899300458
  ],
  "deletedNoteIds": [
    1736899300456
  ],
  "returnedCardIds": []
}

• 404No deck, note, note type or card has that id.
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Search notes#

Returns the notes that match a search (q; every note when it is empty), in ascending id order, one page at a time. q is the search of Searching, including fz: for typos: the Anki browser's notes mode. A note is found when one of its cards satisfies the whole search, so deck:Languages is:due needs a card that is in the deck and due. A search that asks nothing of the cards (tag:, a field, plain text) looks at the notes alone, so it also finds a note that has no cards.

To read the next page, send the previous response's nextCursor as cursor. nextCursor is null on the last page. As for cards, a search that has to look at every note, such as a regular expression or a fuzzy search, stops after about 10,000 notes and returns what it found so far with a nextCursor, so keep following it until it is null.

Parameters

Example request

# Search notes (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/notes?q=tag%3Avocab%20front%3Adog*&limit=50" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

{
  "notes": [
    {
      "id": 1736899300456,
      "guid": "k3Jx9!aQ2c",
      "notetypeId": 1736899100001,
      "mtime": 1736899300,
      "usn": -1,
      "tags": [
        "vocab",
        "a1"
      ],
      "fields": {
        "front": "der Hund",
        "back": "the dog"
      }
    }
  ],
  "nextCursor": "1736899300456"
}

• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Create a note and generate its cards#

Creates a note and generates its cards from the note type's templates.

Name the note type with notetypeName and the deck with deckName (compared ignoring case; a nested deck is Languages::German), or send notetypeId and deckId instead. Exactly one of notetypeName and notetypeId is needed; without a deck the note goes to the Default deck. A name that matches nothing is 404.

fields is an object with one entry per field of the note type, keyed by the field's name in camelCase: Back Extra is backExtra. Each field of a note type shows its key in Get a note type. The field's exact name works as a key too. A field you leave out is empty; a key that names no field is 400 invalid_input and lists the valid keys.

Send a guid only when you import notes from somewhere else and need to keep a stable identity; otherwise one is generated. All fields together may not exceed 5 MiB.

Parameters

Request body

{
  "notetypeName": "Basic (and reversed card)",
  "deckName": "Languages::German",
  "fields": {
    "front": "der Hund",
    "back": "the dog"
  },
  "tags": [
    "vocab",
    "a1"
  ]
}

Example request

# Create a note and generate its cards (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X POST "https://ankinize.com/api/v1/notes" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "notetypeName": "Basic (and reversed card)",
    "deckName": "Languages::German",
    "fields": {
      "front": "der Hund",
      "back": "the dog"
    },
    "tags": [
      "vocab",
      "a1"
    ]
  }'

Response

{
  "id": 1736899300456,
  "guid": "k3Jx9!aQ2c",
  "cards": [
    {
      "id": 1736899300457,
      "ord": 0,
      "deckId": 1736899200123,
      "due": 1
    },
    {
      "id": 1736899300458,
      "ord": 1,
      "deckId": 1736899200123,
      "due": 2
    }
  ]
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 422The body does not match the earlier request that used this Idempotency-Key (idempotency_conflict), or the body failed validation (validation_error).
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Create many notes in one call#

Creates up to 200 notes in one call. It does what Create a note does for each entry (also naming note types and decks by name), but in one transaction and with the note types, decks and tags looked up once, so importing is far faster than one request per note.

The answer is 200 with one entry in results per note you sent, in the same order (index). An entry the collection refuses, such as an unknown deck or a key that names no field, is reported as ok: false with an error, and the others are still written. Send atomic: true to write all or nothing: if any entry is refused, nothing is written and the answer is 422 with the same body.

A batch counts as one request per 10 notes (at least one) against your plan's rate limit. At most 2 batches run at once on the server; when it is busy the answer is 503 with Retry-After, and nothing was changed.

Parameters

Request body

{
  "notes": [
    {
      "notetypeName": "Basic (and reversed card)",
      "deckName": "Languages::German",
      "fields": {
        "front": "der Hund",
        "back": "the dog"
      },
      "tags": [
        "vocab",
        "a1"
      ]
    },
    {
      "notetypeName": "Basic (and reversed card)",
      "deckName": "Languages::German",
      "fields": {
        "front": "die Katze",
        "back": "the cat"
      }
    }
  ]
}

Example request

# Create many notes in one call (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X POST "https://ankinize.com/api/v1/notes/batch-create" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": [
      {
        "notetypeName": "Basic (and reversed card)",
        "deckName": "Languages::German",
        "fields": {
          "front": "der Hund",
          "back": "the dog"
        },
        "tags": [
          "vocab",
          "a1"
        ]
      },
      {
        "notetypeName": "Basic (and reversed card)",
        "deckName": "Languages::German",
        "fields": {
          "front": "die Katze",
          "back": "the cat"
        }
      }
    ]
  }'

Response

{
  "atomic": false,
  "committed": true,
  "created": 2,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "ok": true,
      "id": 1736899300001,
      "guid": "k3f9&aZ1xq",
      "cards": [
        {
          "id": 1736899300002,
          "ord": 0,
          "deckId": 1736899200123,
          "due": 1
        }
      ],
      "newTags": [
        "vocab",
        "a1"
      ]
    },
    {
      "index": 1,
      "ok": true,
      "id": 1736899300003,
      "guid": "p0L!m4Qe2c",
      "cards": [
        {
          "id": 1736899300004,
          "ord": 0,
          "deckId": 1736899200123,
          "due": 2
        }
      ],
      "newTags": []
    }
  ]
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 422The body failed validation (validation_error), or the call was atomic and an entry was refused: then the body is the usual batch answer with every entry's error, and nothing was written.
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.
• 503Other batch operations are using the server. Wait the number of seconds in Retry-After and retry; nothing was changed.

Edit many notes in one call#

Edits up to 200 notes in one call. It does what Edit a note does for each entry, but in one transaction with note types, decks and tags looked up once. Each entry names a note by id and may send fields, tags, or the tag edits addTags and removeTags; what it leaves out stays as it was. tags replaces all tags and can not be sent with addTags or removeTags. removeTags works as in Anki: a tag is matched ignoring case, and removing lang also removes lang::de and the other tags below it (* is not a wildcard). A note may appear once per call.

The answer is 200 with one entry in results per entry you sent, in the same order (index). An entry the collection refuses, such as an unknown note or the wrong number of fields, is reported as ok: false with an error, and the others are still written. Send atomic: true to write all or nothing: if any entry is refused, nothing is written and the answer is 422 with the same body. changed counts notes that differed from what was stored.

A batch counts as one request per 10 entries (at least one) against your plan's rate limit.

Parameters

Request body

{
  "updates": [
    {
      "id": 1736899300001,
      "fields": {
        "back": "the hound"
      }
    },
    {
      "id": 1736899300003,
      "addTags": [
        "animals"
      ],
      "removeTags": [
        "a1"
      ]
    }
  ]
}

Example request

# Edit many notes in one call (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X POST "https://ankinize.com/api/v1/notes/batch-update" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "id": 1736899300001,
        "fields": {
          "back": "the hound"
        }
      },
      {
        "id": 1736899300003,
        "addTags": [
          "animals"
        ],
        "removeTags": [
          "a1"
        ]
      }
    ]
  }'

Response

{
  "atomic": false,
  "committed": true,
  "changed": 2,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "ok": true,
      "id": 1736899300001,
      "changed": true,
      "newCards": [],
      "newTags": []
    },
    {
      "index": 1,
      "ok": true,
      "id": 1736899300003,
      "changed": true,
      "newCards": [],
      "newTags": [
        "animals"
      ]
    }
  ]
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 422The body failed validation (validation_error), or the call was atomic and an entry was refused: then the body is the usual batch answer with every entry's error, and nothing was written.
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.
• 503Other batch operations are using the server. Wait the number of seconds in Retry-After and retry; nothing was changed.

Delete many notes in one call#

Deletes up to 1000 notes and every card made from them, in one transaction. Ids that do not exist are not an error; they are listed in missingNoteIds. This cannot be undone. Deleting is still allowed while the account is over its storage quota.

A batch counts as one request per 10 ids (at least one) against your plan's rate limit.

Parameters

Request body

{
  "ids": [
    1736899300001,
    1736899300003
  ]
}

Example request

# Delete many notes in one call (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X POST "https://ankinize.com/api/v1/notes/batch-delete" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      1736899300001,
      1736899300003
    ]
  }'

Response

{
  "deleted": 2,
  "deletedNoteIds": [
    1736899300001,
    1736899300003
  ],
  "deletedCardIds": [
    1736899300002,
    1736899300004
  ],
  "missingNoteIds": []
}

• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 422The body does not match the earlier request that used this Idempotency-Key (idempotency_conflict), or the body failed validation (validation_error).
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.
• 503Other batch operations are using the server. Wait the number of seconds in Retry-After and retry; nothing was changed.

Get note by ID with cards#

Returns one note, including the cards it produced.

Parameters

Example request

# Get note by ID with cards (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/notes/1736899300456" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

{
  "id": 1736899300456,
  "guid": "k3Jx9!aQ2c",
  "notetypeId": 1736899100001,
  "mtime": 1736899300,
  "usn": -1,
  "tags": [
    "vocab",
    "a1"
  ],
  "fields": {
    "front": "der Hund",
    "back": "the dog"
  },
  "cards": [
    {
      "id": 1736899300457,
      "ord": 0,
      "deckId": 1736899200123,
      "due": 1
    }
  ]
}

• 404No deck, note, note type or card has that id.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Update note fields or tags#

Changes a note's fields, its tags, or both. Anything you leave out stays as it was, including each field missing from fields: send only the fields that change. If the new field content makes a template produce a card it did not before, the new cards are returned in newCards.

changed is false when the request matched what was already stored, and nothing is written.

Parameters

Request body

{
  "fields": {
    "back": "the dog (animal)"
  },
  "tags": [
    "vocab",
    "a1",
    "animals"
  ]
}

Example request

# Update note fields or tags (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X PATCH "https://ankinize.com/api/v1/notes/1736899300456" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "back": "the dog (animal)"
    },
    "tags": [
      "vocab",
      "a1",
      "animals"
    ]
  }'

Response

{
  "id": 1736899300456,
  "changed": true,
  "newCards": [],
  "newTags": [
    "animals"
  ]
}

• 404No deck, note, note type or card has that id.
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Delete a note and its cards#

Deletes a note and every card made from it. This cannot be undone. Deleting is still allowed while the account is over its storage quota.

Parameters

Example request

# Delete a note and its cards (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X DELETE "https://ankinize.com/api/v1/notes/1736899300456" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41"

Response

{
  "ok": true,
  "deletedNoteIds": [
    1736899300456
  ],
  "deletedCardIds": [
    1736899300457,
    1736899300458
  ]
}

• 404No deck, note, note type or card has that id.
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

List note types#

Returns the id and name of every note type, or only the ones whose name q accepts. Use Get a note type for its fields and templates.

Parameters

Example request

# List note types (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/note-types" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

{
  "noteTypes": [
    {
      "id": 1736899100001,
      "name": "Basic"
    },
    {
      "id": 1736899100002,
      "name": "Cloze"
    }
  ]
}

• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Create note type (stock or custom)#

Creates a note type, either from one of Anki's stock designs or from your own fields and templates.

Send stock (basic, basic-and-reversed, basic-optional-reversed, basic-type-in-answer, cloze or image-occlusion) to start from a stock design, and optionally name to rename it. Or send fields and templates to define it yourself.

Parameters

Request body

{
  "stock": "basic-and-reversed",
  "name": "Vocabulary"
}

Example request

# Create note type (stock or custom) (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X POST "https://ankinize.com/api/v1/note-types" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "stock": "basic-and-reversed",
    "name": "Vocabulary"
  }'

Response

{
  "id": 1736899400001,
  "name": "Vocabulary"
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Get note type details with fields and templates#

Returns a note type with its fields and card templates, its CSS and its sort field.

Parameters

Example request

# Get note type details with fields and templates (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/note-types/1736899100001" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

{
  "id": 1736899100001,
  "name": "Basic",
  "kind": "normal",
  "css": ".card { font-family: arial; font-size: 20px; text-align: center; }",
  "sortFieldIdx": 0,
  "fields": [
    {
      "ord": 0,
      "name": "Front",
      "key": "front"
    },
    {
      "ord": 1,
      "name": "Back",
      "key": "back"
    }
  ],
  "templates": [
    {
      "ord": 0,
      "name": "Card 1",
      "qFormat": "{{Front}}",
      "aFormat": "{{FrontSide}}<hr id=answer>{{Back}}"
    }
  ]
}

• 404No deck, note, note type or card has that id.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Update note type fields, templates, or styling#

Changes a note type's name, CSS, sort field, fields or templates.

Adding, reordering or renaming fields and templates is safe. Removing a field or template, or changing which fields a template needs, changes the collection's schema, so every device has to download the whole collection again on its next sync (a full sync). The request is refused with 409 full_sync_required until you add ?acceptFullSync=true.

Removing a field or template also needs Allow destructive schema changes via API turned on under Settings → Developer, or the answer is 403 destructive_change_disabled.

Parameters

Request body

{
  "css": ".card { font-size: 24px; }"
}

Example request

# Update note type fields, templates, or styling (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X PATCH "https://ankinize.com/api/v1/note-types/1736899100001?acceptFullSync=true" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "css": ".card { font-size: 24px; }"
  }'

Response

{
  "id": 1736899100001,
  "name": "Basic",
  "schemaChanged": false,
  "change": {
    "fieldsAdded": 0,
    "fieldsRemoved": 0,
    "fieldsMoved": 0,
    "sortFieldChanged": false,
    "templatesAdded": 0,
    "templatesRemoved": 0,
    "templatesMoved": 0,
    "destructive": false
  },
  "updatedNotes": 0,
  "deletedCards": 0,
  "movedCards": 0,
  "newCards": 0
}

• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 404No deck, note, note type or card has that id.
• 409The change alters the collection's schema and needs ?acceptFullSync=true (full_sync_required), or the card is in a state that does not allow this (card_state_error: suspended, buried, in a filtered deck, or an unsupported scheduler).
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Delete a note type#

Deletes a note type and every note that uses it.

This changes the collection's schema, so it needs ?acceptFullSync=true (otherwise 409 full_sync_required) and Allow destructive schema changes via API turned on under Settings → Developer (otherwise 403 destructive_change_disabled).

Parameters

Example request

# Delete a note type (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X DELETE "https://ankinize.com/api/v1/note-types/1736899100001?acceptFullSync=true" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41"

Response

{
  "ok": true,
  "deletedNotes": 42,
  "deletedCards": 42,
  "currentNotetypeId": 1736899100002,
  "addedBasic": false
}

• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 404No deck, note, note type or card has that id.
• 409The change alters the collection's schema and needs ?acceptFullSync=true (full_sync_required), or the card is in a state that does not allow this (card_state_error: suspended, buried, in a filtered deck, or an unsupported scheduler).
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

List tags#

Returns every tag in the collection, sorted by name, or only the tags q accepts. A nested tag keeps Anki's :: separator, such as Languages::German; searching tag:Languages also finds the notes tagged with the nested ones.

Parameters

Example request

# List tags (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/tags" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

{
  "tags": [
    "german",
    "Languages::German",
    "vocab"
  ]
}

• 401The Authorization header is missing, or the key is invalid, disabled or expired.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Create a tag#

Creates a tag without putting it on a note, as Anki registers a tag when a note brings it. A name that is already used (ignoring case) answers 200 with created: false and the spelling that is stored, so sending it twice is safe. A nested name keeps the spelling of a parent that exists, as in Anki.

A tag no note carries is removed by Anki's Check Database and Clear Unused Tags.

Parameters

Request body

{
  "name": "Languages::German"
}

Example request

# Create a tag (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X POST "https://ankinize.com/api/v1/tags" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Languages::German"
  }'

Response

{
  "name": "Languages::German",
  "created": true
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 422The body does not match the earlier request that used this Idempotency-Key (idempotency_conflict), or the body failed validation (validation_error).
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Get a tag by name#

Returns a tag and noteCount, the notes that carry it or one of its nested tags (the notes tag:name finds). A tag exists when it is in the list, when a nested tag is, or when a note carries it. The name in the path is the tag, percent-encoded, and is compared ignoring case.

Parameters

Example request

# Get a tag by name (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/tags/german" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

{
  "name": "Languages::German",
  "noteCount": 42
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 404No deck, note, note type or card has that id.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Rename a tag#

Renames a tag and every tag nested under it on all notes: renaming Languages to Lang makes Languages::German into Lang::German. The notes that change get a new modification time, so they sync. If the new name is already a tag, the two are merged, and a note that ends up with the tag twice keeps it once. Renaming a tag that no note carries renames it in the list.

notes is how many notes were looked at and changed.

Parameters

Request body

{
  "newName": "Lang::German"
}

Example request

# Rename a tag (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X PATCH "https://ankinize.com/api/v1/tags/german" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "newName": "Lang::German"
  }'

Response

{
  "name": "Lang::German",
  "notes": 42
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 404No deck, note, note type or card has that id.
• 422The body does not match the earlier request that used this Idempotency-Key (idempotency_conflict), or the body failed validation (validation_error).
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Delete a tag#

Removes a tag and the tags nested under it from every note and from the list. The notes keep everything else. This cannot be undone. Deleting is still allowed while the account is over its storage quota.

Parameters

Example request

# Delete a tag (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X DELETE "https://ankinize.com/api/v1/tags/german" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41"

Response

{
  "ok": true,
  "deletedTags": [
    "Lang::German",
    "Lang::German::Verbs"
  ],
  "notes": 57
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 404No deck, note, note type or card has that id.
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Create many tags in one call#

Creates up to 200 tags in one call, in one transaction. It does what Create a tag does for each name. The answer is 200 with one entry in results per name, in order; a name that is refused (such as one with a space) is ok: false with an error and the others are still created. Send atomic: true to write all or nothing: then the answer is 422 with the same body.

A batch counts as one request per 10 names against your plan's rate limit.

Parameters

Request body

{
  "names": [
    "vocab",
    "grammar",
    "two words"
  ]
}

Example request

# Create many tags in one call (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X POST "https://ankinize.com/api/v1/tags/batch-create" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "names": [
      "vocab",
      "grammar",
      "two words"
    ]
  }'

Response

{
  "atomic": false,
  "committed": true,
  "created": 2,
  "failed": 1,
  "results": [
    {
      "index": 0,
      "ok": true,
      "name": "vocab",
      "created": true
    },
    {
      "index": 1,
      "ok": true,
      "name": "grammar",
      "created": true
    },
    {
      "index": 2,
      "name": "two words",
      "ok": false,
      "error": {
        "code": "invalid_input",
        "message": "a tag name can not contain a space"
      }
    }
  ]
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 422The body failed validation (validation_error), or the call was atomic and an entry was refused: then the body is the usual batch answer with every entry's error, and nothing was written.
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.
• 503Other batch operations are using the server. Wait the number of seconds in Retry-After and retry; nothing was changed.

Rename many tags in one call#

Renames up to 200 tags in one call, in one pass over the notes. Each entry names a tag by name and gives its newName, as Rename a tag does. Two entries may use the same newName (that merges the tags), but an entry that touches another one (a name that is, contains or lies inside another entry's name or newName) is refused with invalid_input, because the result would depend on the order. Entries are reported in results as in Create many notes; atomic: true writes all or nothing.

Parameters

Request body

{
  "updates": [
    {
      "name": "vocab",
      "newName": "vocabulary"
    },
    {
      "name": "grammar",
      "newName": "Grammar"
    }
  ]
}

Example request

# Rename many tags in one call (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X POST "https://ankinize.com/api/v1/tags/batch-update" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "name": "vocab",
        "newName": "vocabulary"
      },
      {
        "name": "grammar",
        "newName": "Grammar"
      }
    ]
  }'

Response

{
  "atomic": false,
  "committed": true,
  "renamed": 2,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "ok": true,
      "name": "vocab",
      "newName": "vocabulary",
      "notes": 12
    },
    {
      "index": 1,
      "ok": true,
      "name": "grammar",
      "newName": "Grammar",
      "notes": 4
    }
  ]
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 422The body failed validation (validation_error), or the call was atomic and an entry was refused: then the body is the usual batch answer with every entry's error, and nothing was written.
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.
• 503Other batch operations are using the server. Wait the number of seconds in Retry-After and retry; nothing was changed.

Delete many tags in one call#

Deletes up to 1000 tags, with the tags nested under them, from every note and from the list, in one transaction. Names that do not exist are not an error; they are listed in missingNames. This cannot be undone. Deleting is still allowed while the account is over its storage quota.

Parameters

Request body

{
  "names": [
    "vocabulary",
    "unused"
  ]
}

Example request

# Delete many tags in one call (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X POST "https://ankinize.com/api/v1/tags/batch-delete" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "names": [
      "vocabulary",
      "unused"
    ]
  }'

Response

{
  "deleted": 1,
  "deletedTags": [
    "vocabulary"
  ],
  "notes": 12,
  "missingNames": [
    "unused"
  ]
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.
• 503Other batch operations are using the server. Wait the number of seconds in Retry-After and retry; nothing was changed.

Search cards#

Returns the cards that match a search (q; every card when it is empty), in ascending id order, one page at a time. Narrow it by deck or note with deck:, did: and nid: in the search. Paginate with nextCursor as for notes, with one difference: a search that has to look at every card, such as a regular expression or prop:s, stops after about 10,000 cards and returns what it found so far together with a nextCursor. A page can therefore hold fewer than limit cards, or none, while nextCursor is not null; keep following it until it is.

Parameters

Example request

# Search cards (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/cards?q=deck%3ALanguages%3A%3AGerman%20is%3Adue&limit=50" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

{
  "cards": [
    {
      "id": 1736899300457,
      "noteId": 1736899300456,
      "deckId": 1736899200123,
      "ord": 0,
      "mtime": 1736899300,
      "usn": -1,
      "type": 0,
      "queue": 0,
      "due": 1,
      "interval": 0,
      "factor": 0,
      "reps": 0,
      "lapses": 0,
      "left": 0,
      "originalDue": 0,
      "originalDeckId": 0,
      "flags": 0
    }
  ],
  "nextCursor": null
}

• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Edit many cards in one call#

Applies one change to up to 1000 cards, in one transaction: set a flag, move them to a deck, suspend or bury them. It does what Edit a card does for each id, with the same rules for patch.

The answer is 200 with one entry in results per distinct id. A card that does not exist, or that sits in a filtered deck and so can not be moved, is reported as ok: false, and the others are still changed. Send atomic: true to write all or nothing: if any card is refused, nothing is written and the answer is 422 with the same body. changed counts the cards that differed from what was stored.

A batch counts as one request per 10 ids (at least one) against your plan's rate limit.

Parameters

Request body

{
  "ids": [
    1736899300002,
    1736899300004
  ],
  "patch": {
    "flag": 2
  }
}

Example request

# Edit many cards in one call (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X POST "https://ankinize.com/api/v1/cards/batch-update" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      1736899300002,
      1736899300004
    ],
    "patch": {
      "flag": 2
    }
  }'

Response

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 422The body failed validation (validation_error), or the call was atomic and an entry was refused: then the body is the usual batch answer with every entry's error, and nothing was written.
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.
• 503Other batch operations are using the server. Wait the number of seconds in Retry-After and retry; nothing was changed.

Delete many cards in one call#

Deletes up to 1000 cards in one transaction. A note whose last card is deleted is deleted with it. Ids that do not exist are not an error; they are listed in missingCardIds. This cannot be undone. Deleting is still allowed while the account is over its storage quota.

A batch counts as one request per 10 ids (at least one) against your plan's rate limit.

Parameters

Request body

{
  "ids": [
    1736899300002,
    1736899300004
  ]
}

Example request

# Delete many cards in one call (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X POST "https://ankinize.com/api/v1/cards/batch-delete" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      1736899300002,
      1736899300004
    ]
  }'

Response

{
  "deleted": 2,
  "deletedCardIds": [
    1736899300002,
    1736899300004
  ],
  "deletedNoteIds": [
    1736899300001,
    1736899300003
  ],
  "missingCardIds": []
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 403The key lacks the scope, the account is suspended or its email unverified, the account is over its storage quota (over_quota; deleting is still allowed), or a destructive schema change is switched off (destructive_change_disabled).
• 422The body does not match the earlier request that used this Idempotency-Key (idempotency_conflict), or the body failed validation (validation_error).
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.
• 503Other batch operations are using the server. Wait the number of seconds in Retry-After and retry; nothing was changed.

Get card details by ID#

Returns one card with its scheduling state: queue, due, interval, ease factor, repetitions and lapses.

Parameters

Example request

# Get card details by ID (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/cards/1736899300457" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

• 404No deck, note, note type or card has that id.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Edit a card#

Changes a card's flag, moves it to another deck, or suspends or buries it. Anything you leave out stays as it was.

flag is 0 (none) to 7. suspended and buried cannot both be sent. Suspending keeps a card out of review until you send suspended: false; burying hides it only until the next day or until you unbury it. A suspended card is never buried. Moving a card clears its FSRS memory state; it is replayed from the review history with the new deck's parameters the next time the card is shown or answered. Cards in a filtered deck can neither be moved nor moved into one (409 card_state_error).

changed is false when the request matched what was already stored.

Parameters

Request body

{
  "flag": 2,
  "suspended": false
}

Example request

# Edit a card (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X PATCH "https://ankinize.com/api/v1/cards/1736899300457" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "flag": 2,
    "suspended": false
  }'

Response

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 404No deck, note, note type or card has that id.
• 422The body does not match the earlier request that used this Idempotency-Key (idempotency_conflict), or the body failed validation (validation_error).
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Delete a card#

Deletes one card. If it was the last card of its note, the note is removed too. This cannot be undone. Deleting is still allowed while the account is over its storage quota.

Parameters

Example request

# Delete a card (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X DELETE "https://ankinize.com/api/v1/cards/1736899300457" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41"

Response

• 404No deck, note, note type or card has that id.
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Render a card's front and back#

Renders the card as Anki shows it: the note's fields are put into the card template, so the question and the answer are ready to display. The answer includes the question above a divider, as in Anki.

Everything is sanitized on the server before it is returned: scripts, event handlers, iframes, forms, javascript: links and remote styles are removed, and CSS is limited to a safe subset. The result is still content from your collection, so display it in a sandboxed <iframe sandbox> or srcdoc and not straight into your page.

With format=json (the default) you get question, answer and css. With format=html you get one complete HTML document, with a Content-Security-Policy that allows no script and the sandbox directive, which is meant for <iframe sandbox srcdoc>: fetch it with your key and put the text in srcdoc (an iframe's src cannot send the key, and this server refuses to be framed). Media in a card is referred to by file name and listed in media. The file names in the question and answer are turned into signed links to GET /api/v1/media/{name} that last an hour, so the card shows its pictures and plays its audio from a sandboxed frame; or pass mediaBaseUrl (an http(s) URL ending in /) to have them point at files you host instead.

Typing the answer. For {{type:Field}}, {{type:nc:Field}} (accents ignored) and {{type:cloze:Field}} the question holds <div class="typeans" data-field="Field"></div>, where your own input goes. Pass what the learner typed as typedAnswer (up to 1000 characters) and the answer shows the comparison Anki shows, computed the same way: a <code id="typeans"> with the typed text and the expected text as typeGood, typeBad and typeMissed spans around an arrow, in the font and size of the field. The classes carry no colors, so style them in your page. Without typedAnswer the answer shows the expected text. A text too long to compare is shown as one change.

Formulas. \(...\) and \[...\] are returned as written. Anki's [$]...[/$] and [$$]...[/$$] tags are rewritten to them, and [latex]...[/latex] becomes display math; images are not generated, because that needs a TeX installation. math is true when the question or the answer holds a formula. Typeset it in your page with MathJax 3 after inserting the HTML (format=html allows no script, so a formula stays as text there). TeX that is not math, such as packages or TikZ, is not supported.

A template that cannot be rendered is 422 render_error.

Parameters

Example request

# Render a card's front and back (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/cards/1736899300457/render" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

• 404No deck, note, note type or card has that id.
• 422The card's template has a syntax error or refers to a field that does not exist (render_error).
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Preview the four answer buttons#

Shows what each answer button would do, without answering: the time until the card would next be due after Again, Hard, Good and Easy. This is the preview Anki shows above its buttons.

Only the v3 scheduler is supported. The card must be answerable: not suspended or buried (409 card_state_error). A card in a filtered deck is previewed as Anki does: in a deck that reschedules, the buttons are the home deck preset's, and a review that comes before it was due is scheduled from the days it was early; in a deck that does not reschedule, the buttons are the preview delays (Again, Hard and Good come back after the deck's delays, a delay of 0 ends the preview, and Easy always ends it) and show 0 seconds when they end it.

Review intervals are fuzzed and load balanced like Anki's: the day is drawn within the fuzz range, weighted towards days with fewer cards of the same preset due, the preset's Easy Days and (if it buries siblings) days away from the card's siblings. The draw is fixed by the card and its review count, so the preview, the answer and a repeat of either agree.

Parameters

Example request

# Preview the four answer buttons (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/cards/1736899300457/scheduling" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

• 404No deck, note, note type or card has that id.
• 409The change alters the collection's schema and needs ?acceptFullSync=true (full_sync_required), or the card is in a state that does not allow this (card_state_error: suspended, buried, in a filtered deck, or an unsupported scheduler).
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Answer (review) a card#

Answers a card, the same as pressing a button in Anki's reviewer. The card is rescheduled with the deck preset's v3 scheduler (or FSRS when the preset turns it on), a review-log entry is written, the deck's daily counts go up, and siblings are buried if the preset says so. A card that reaches the leech threshold gets the leech tag and, if the preset says so, is suspended.

rating is again, hard, good or easy (or 1 to 4). timeTakenMs is how long the learner looked at the card, capped by the preset. Send an Idempotency-Key so a retry does not answer twice.

The card must not be suspended or buried, and the collection must use the v3 scheduler; otherwise the answer is 409 card_state_error. A card in a filtered deck is answered as Anki does. The preset, the answer-time cap and burying come from the card's home deck, the daily counts go to the filtered deck and its parents, and the review log records an answer given before the card was due (or in a deck that does not reschedule) with type 3 (filtered). In a deck that reschedules, a review card that is passed returns to its home deck, and a learning card stays in the filtered deck until it graduates; in a deck that does not reschedule, nothing is rescheduled: Again, Hard and Good bring the card back after the deck's preview delay, and the card returns to its home deck in its old state when the preview ends. The legacy schedulers are not supported. A card that has no FSRS memory state yet (for example one that was just moved into an FSRS deck) gets one replayed from its review history, as Anki does, and from its SM-2 ease and interval when the history is too short.

The load balancer is applied to review intervals as in Anki (see GET /api/v1/cards/{id}/scheduling). It reads the cards due in the next 99 days when the card is answered (Anki reads them once when it builds a queue), and the weekday used for Easy Days is taken in the collection's localOffset (UTC when unset).

Parameters

Request body

{
  "rating": "good",
  "timeTakenMs": 4200
}

Example request

# Answer (review) a card (needs a key with the "write" scope)
# Idempotency-Key makes a retry safe: the first answer is replayed.
# A 423 means Anki is syncing: wait Retry-After seconds, then retry.
curl -X POST "https://ankinize.com/api/v1/cards/1736899300457/answer" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY" \
  -H "Idempotency-Key: 9b2f6c1e-7f3a-4a53-9f55-0d3c1c2a8e41" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": "good",
    "timeTakenMs": 4200
  }'

Response

• 404No deck, note, note type or card has that id.
• 409The change alters the collection's schema and needs ?acceptFullSync=true (full_sync_required), or the card is in a state that does not allow this (card_state_error: suspended, buried, in a filtered deck, or an unsupported scheduler).
• 422The body does not match the earlier request that used this Idempotency-Key (idempotency_conflict), or the body failed validation (validation_error).
• 423Another write or an Anki sync is using the collection. Wait the number of seconds in Retry-After and retry; nothing was changed.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Get the study queue of a deck#

Returns the cards Anki would show next in a deck, in the order it would show them: the deck (and its subdecks) is searched for learning cards due now, then reviews and day-learning cards, then new cards, under the daily limits of every deck preset and deck (including New cards ignore review limit and Apply all parent limits), with new-card gather and sort order, review order, FSRS orders, burying of siblings and the mixes of new cards and day-learning cards with reviews. The result matches the desktop client's queue for the same collection and moment.

counts is what Anki shows above the buttons (new, learning, review). cards holds the first limit cards, each with a kind of new, learning or review; total is the length of the whole queue. Learning cards that are due within the preset's learn-ahead limit are listed at the end. Nothing is written, so asking again before you answer gives the same queue; after POST /api/v1/cards/{id}/answer ask again.

Without deckId the collection's current deck is used. Only the v3 scheduler is supported (409 card_state_error otherwise). A filtered deck is queued with unlimited counts, in the order it was built in Anki (its cards keep that position).

Parameters

Example request

# Get the study queue of a deck (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/queue?deckId=1736899200123&limit=50" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

• 404No deck, note, note type or card has that id.
• 409The change alters the collection's schema and needs ?acceptFullSync=true (full_sync_required), or the card is in a state that does not allow this (card_state_error: suspended, buried, in a filtered deck, or an unsupported scheduler).
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Get the statistics of a search#

Returns the graphs of Anki's statistics screen for the cards a search matches (q, default every card) and the last days days of review history (0, the default, is all of it). The numbers are Anki's: the same counts, buckets and averages the desktop client draws, computed from the review log and the cards in place. Nothing is copied into another database. A request reads the review log once, so a big collection takes a moment; one that takes longer than 20 seconds is refused with 400 invalid_input (narrow the search or the days). The server keeps the graphs of a search in memory for up to five minutes, and never past the end of the day, while the collection is unchanged, so a repeat request is answered without reading the collection again; any change to the collection ends that.

Days are counted from the end of the current day, so 0 is today, -1 yesterday and 1 tomorrow; a day starts at the collection's rollover hour and is read in its localOffset (UTC when unset), as timing says. buttons, hours and trueRetention count answers over a month, three months, a year and all time. cardCounts counts cards by kind, with suspended and buried cards counted separately or together. eases (SM-2) and difficulty, stability and retrievability (FSRS) cover the cards that have the data; fsrs says whether the collection has FSRS turned on. retrievability is the chance of recalling each card now, from its memory state and the time since its last review. Keys of the count objects are numbers: a day, a percent bin or an interval in days.

Parameters

Example request

# Get the statistics of a search (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/stats" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

{
  "buttons": {
    "oneMonth": {
      "learning": [
        4,
        1,
        22,
        3
      ],
      "young": [
        6,
        3,
        40,
        5
      ],
      "mature": [
        2,
        1,
        31,
        4
      ]
    },
    "threeMonths": {
      "learning": [
        9,
        2,
        51,
        6
      ],
      "young": [
        12,
        5,
        88,
        9
      ],
      "mature": [
        5,
        2,
        70,
        8
      ]
    },
    "oneYear": {
      "learning": [
        9,
        2,
        51,
        6
      ],
      "young": [
        12,
        5,
        88,
        9
      ],
      "mature": [
        5,
        2,
        70,
        8
      ]
    },
    "allTime": {
      "learning": [
        9,
        2,
        51,
        6
      ],
      "young": [
        12,
        5,
        88,
        9
      ],
      "mature": [
        5,
        2,
        70,
        8
      ]
    }
  },
  "cardCounts": {
    "includingInactive": {
      "new": 120,
      "learn": 3,
      "relearn": 2,
      "young": 40,
      "mature": 85,
      "suspended": 0,
      "buried": 0
    },
    "excludingInactive": {
      "new": 118,
      "learn": 3,
      "relearn": 2,
      "young": 40,
      "mature": 84,
      "suspended": 1,
      "buried": 1
    }
  },
  "hours": {
    "oneMonth": [
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 40,
        "correct": 36
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 40,
        "correct": 36
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      },
      {
        "total": 0,
        "correct": 0
      }
    ],
    "threeMonths": [],
    "oneYear": [],
    "allTime": []
  },
  "today": {
    "answerCount": 42,
    "answerMillis": 301000,
    "correctCount": 38,
    "matureCorrect": 20,
    "matureCount": 22,
    "learnCount": 6,
    "reviewCount": 34,
    "relearnCount": 2,
    "earlyReviewCount": 0
  },
  "eases": {
    "eases": {
      "230": 4,
      "250": 60,
      "270": 9
    },
    "average": 250
  },
  "difficulty": {
    "eases": {},
    "average": 0
  },
  "intervals": {
    "intervals": {
      "1": 5,
      "7": 18,
      "30": 40
    }
  },
  "stability": {
    "intervals": {}
  },
  "futureDue": {
    "futureDue": {
      "0": 12,
      "1": 9,
      "2": 11
    },
    "haveBacklog": false,
    "dailyLoad": 14
  },
  "added": {
    "added": {
      "-30": 40,
      "-1": 6
    }
  },
  "reviews": {
    "count": {
      "-1": {
        "learn": 4,
        "relearn": 1,
        "young": 22,
        "mature": 30,
        "filtered": 0
      }
    },
    "time": {
      "-1": {
        "learn": 20000,
        "relearn": 5000,
        "young": 110000,
        "mature": 150000,
        "filtered": 0
      }
    }
  },
  "rolloverHour": 4,
  "retrievability": {
    "retrievability": {},
    "average": 0,
    "sumByCard": 0,
    "sumByNote": 0
  },
  "fsrs": false,
  "trueRetention": {
    "today": {
      "youngPassed": 20,
      "youngFailed": 2,
      "maturePassed": 18,
      "matureFailed": 2
    },
    "yesterday": {
      "youngPassed": 18,
      "youngFailed": 3,
      "maturePassed": 17,
      "matureFailed": 1
    },
    "week": {
      "youngPassed": 120,
      "youngFailed": 14,
      "maturePassed": 110,
      "matureFailed": 9
    },
    "month": {
      "youngPassed": 400,
      "youngFailed": 40,
      "maturePassed": 380,
      "matureFailed": 30
    },
    "year": {
      "youngPassed": 400,
      "youngFailed": 40,
      "maturePassed": 380,
      "matureFailed": 30
    },
    "allTime": {
      "youngPassed": 400,
      "youngFailed": 40,
      "maturePassed": 380,
      "matureFailed": 30
    }
  },
  "cards": 250,
  "reviewEntries": 1190,
  "timing": {
    "now": 1736899200,
    "daysElapsed": 412,
    "nextDayAt": 1736913600,
    "localOffsetSecs": 0
  }
}

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

List media files#

Lists the collection's media files by name, 100 at a time (limit up to 1000). prefix keeps only the names that start with it. When nextCursor is not null, pass it as cursor to get the next page. Each item has the file's size, its sha1 and sha256, the contentType it is served as, and the usn of its last change, which is the number the Anki media sync uses.

Parameters

Example request

# List media files (needs a key with the "read" scope)
curl "https://ankinize.com/api/v1/media?limit=50" \
  -H "Authorization: Bearer $ANKINIZE_API_KEY"

Response

• 400The request was understood but is not valid, for example an unknown deck or a fields key that names no field of the note type. The code is invalid_input, deck_error or card_type_error.
• 429The plan's rate limit is used up: a limit per minute on every plan, and a limit per day on Free. Nothing was changed. Wait Retry-After seconds and send the same request again.

Download a media file#

Returns the file's bytes. The type comes from the file name's extension only, never from the bytes, and every response says X-Content-Type-Options: nosniff and a Content-Security-Policy with sandbox, so a file from your collection cannot run script on this origin. Images, audio, video and fonts are shown inline; SVG, PDF and any other type are offered as downloads (Content-Disposition: attachment).

The ETag is the file's SHA-256, so If-None-Match answers 304. Range: bytes=... (one range) answers 206, which lets a browser seek in audio and video; a range past the end is 416.

Instead of a key, the request may carry the u, exp and sig query parameters of a signed link. A signed link opens that one file for reading until it expires, which is how a card shown in a sandboxed frame loads its pictures: GET /api/v1/cards/{id}/render puts such links into the card unless you pass mediaBaseUrl. The links last an hour.

Parameters

Example request