RESTful API Documentation

Unfortunately, there still isn't complete documentation on using the RESTful API. However, here is a super quick overview with information about how to gleen more information.

Most methods have been documented to some degree, but there may still be mistakes or omissions.

Please edit this page and help improve it!

Overview

All the code for the API and be found in this file:

https://github.com/dsnopek/anki-sync-server/blob/master/AnkiServer/apps/rest_app.py

All of the endpoints take HTTP POST requests and accept/return JSON (except for the top-level URL, which is a GET request and returns text with version information). So, the API is actually not quite RESTful, it's more like a super simple HTTP RPC.

There is one magic URL, /list_collections which returns the names of all available collections. Every other URL will contain the collection name and is directly connected to a Handler class:

/collection/[NAME]/[METHOD] -> CollectionHandler
/collection/[NAME]/model/[MODEL_ID]/[METHOD] -> ModelHandler
/collection/[NAME]/note/[NOTE_ID]/[METHOD] -> NoteHandler
/collection/[NAME]/deck/[DECK_ID]/[METHOD] -> DeckHandler
/collection/[NAME]/card/[CARD_ID]/[METHOD] -> CardHandler

Replace [NAME] with the collection name and [METHOD] with a paricular method on the Handler class that you want to call. So, for example, POSTing to this URL:

/collection/mine/latest_notes

... will call the CollectionHandler.latest_notes() method in the rest_app.py file I linked above.

CollectionHandler

Models

Store fields definitions and templates for notes.

list_models

Returns a list of all models in a collection

Request

No parameters.

Response

array of objects, each representing a model

find_model_by_name

Returns a model that matches the given name

Request:

Required parameters:

model (string)

Response

object, representing a model. If no model is found with the given name, an empty response will be sent.

Notes

Information (in fields per the model) that can generate a card (based on a template from the model).

find_notes

Finds a set of notes

Anki source code for findNotes here

Request:

Optional parameters:

query (string) (omitting this will return all notes)
preload (boolean)

Response

array of objects, each representing a note.

latest_notes

TODO Description

Request:

Optional parameters:

updated_since(date)
limit (integer)
preload (boolean)

Response

TODO

add_note

TODO Description

Request:

Required parameters:

model (string)

Optional parameters:

fields (object)
tags (string)

Response

None

list_tags

list_models

Returns a list of all models in a collection

Request

No parameters.

Response

array of objects, each representing a model

Decks

Groups of cards.

list_decks

Returns a list of all decks in the collection.

Request

No parameters.

Response

array of objects, each representing a deck

select_deck

Switches to a deck specified by the given ID number or name.

Request

Required parameters:

deck (string or number)

Response

None

create_dynamic_deck

This will create a dynamic deck based on the given query. If a deck exists with the same name, the old deck will be cleared.

Request

Optional parameters

name(string) - defaults to "Custom Study Session"
query (string) - defaults to '' (TODO document query)
count (int) - default to 100
mode (string) - "random", "added", or "due". defaults to "random".

Response

Returns an object representing the newly created dynamic deck.

empty_dynamic_deck

If a dynamic deck exists with the given name, clears that deck.

Request

Optional parameters

name(string) - defaults to "Custom Study Session"

Response

None

Cards

A specific card in a deck with a history of review (generated from a note based on the template).

find_cards

Returns a set of cards that match the given query.

Request

Optional parameters

query(string) - defaults to '' (TODO document query)
order (boolean) - defaults to False
limit (int) - defaults to 0
offset (int) - defaults to 0
preload (boolean) - defaults to False

Response

List of objects representing cards that were retrieved by the query

latest_cards

Returns a list of cards ordered by last update date, with the most recently updated cards returned first.

Request

Optional parameters

updated_since (date string)
limit (int) - defaults to 10
preload (boolean) - defaults to False

Response

List of objects representing cards that were retrieved by the query

Scheduler

Controls card review, ie. intervals, what cards are due, answering a card, etc. These routes are accessed as collection routes, e.g. collection/{collectionName}/reset_scheduler.

reset_scheduler

Resets schedule for the given deck. Returns an list of new, learning, and review cards.

Request

Required parameters

deck (string or int) - Deck ID or name

Response

array:

{
  "new_cards": "int",
  "learning_cards": "int",
  "review_cards": "int"
}

extend_scheduler_limits

Extend the scheduler's limits to allow a certain number of new and review cards.

Request

Optional parameters

new_cards (int) - defaults to 0
review_cards (int) - defaults to 0

Response

None

next_card

Proceed to the next card in the deck. The timer for the card will be started.

Request

Required parameters

deck (string or int) - Deck ID or name

Response

object representing the next card in the deck

answer_card

Note: The scheduler must be set up before this route is called, or an error will occur and will not be displayed properly.

Request

Required parameters

id (long) - Card ID
ease (int)

Response

None

suspend_cards

Suspends cards matching the given IDs.

Request

Required parameters

ids (list) - list of Card IDs

Response

None

unsuspend_cards

Unsuspends cards matching the given IDs.

Request

Required parameters

ids (list) - list of Card IDs

Response

None

cards_recent_ease

Returns the most recent ease for each card.

Request

Optional parameters

ids (list) - list of Card IDs. If omitted, will select all cards.

Response

List of objects:

{
  "id": "long",
  "ease": "int",
  "timestamp": "int"
}

latest_revlog

Returns recent entries from the revlog.

Request

Optional parameters

updated_since (date string)
limit (int) - defaults to 100

Response

List of objects:

{
  "id": "long",
  "ease": "int",
  "timestamp": "int",
  "card_id": "int",
  "usn": "...",
  "interval": "...",
  "last_interval": "...",
  "factor": "...",
  "time": "...",
  "type": "..."
}

stats_report

Generates an HTML stats report based on user's performance

Request

Optional parameters

width (int) - defaults to 600
height (int) - defaults to 200
reports (list) - defaults to ['today', 'due', 'reps', 'interval', 'hourly', 'ease', 'card', 'footer']
include_css (boolean) - defaults to False
include_jquery (boolean) - defaults to False
include_flot (boolean) - defaults to False

Response

HTML stats report

Global / Misc

set_language

Sets the language used by Anki.

Request

Required parameters

code (string)

ImportExportHandler

Handler group for the 'collection' type, but it's not added by default.

import_file

Request

Required parameters

filetype (string) Either data or url must be specified:
data (blob) - If included, will import this data.
url (string) - If included, will download and import a file located at this URL.

ModelHandler

field_names

Returns a list of field namesmatching the given model ID in the URL.

Request

No required or optional parameters.

Response

List of field names

NoteHandler

A note is serialized with the following format:

{
  "id": "...",
  "guid": "...",
  "model": "...",
  "mid": "...",
  "mod": "...",
  "scm": "...",
  "tags": "...",
  "string_tags": "...",
  "fields": {},
  "flags": "...",
  "usn": "...",
}

index

Returns a note matching the given ID in the URL.

Request

No required or optional parameters.

Response

Object representing a serialized note

update

Updates the fields in a note matching the given ID in the URL.

Request

Required parameters

fields (object) - Keys are fields to update, values are the updated field values
tags (list) - updated list of tags for the note

Optional parameters

update_mod (boolean) - defaults to True. If False, the note's last-modified date will not be updated.

Response

Note

delete

Deletes a note matching the given ID in the URL.

Request

No required or optional parameters.

Response

None

add_tags

Adds tags to a note matching the given ID in the URL.

Request

Required parameters

tags (list) - list of new tags for the note

Optional parameters

update_mod (boolean) - defaults to True. If False, the note's last-modified date will not be updated.

Response

Note

remove_tags

Removes tags from a note matching the given ID in the URL.

Request

Required parameters

tags (list) - list of tags to remove from the note

Optional parameters

update_mod (boolean) - defaults to True. If False, the note's last-modified date will not be updated.

Response

Note

DeckHandler

index

Returns a deck matching the given ID or name in the URL.

Request

No required or optional parameters.

Response

Object representing a serialized deck

next_card

Proceeds to the next card in the deck's collection, and returns that card. See CollectionHandler.next_card.

Request

No required or optional parameters.

Response

Object representing a serialized card

get_conf

Request

No required or optional parameters.

Response

Deck configuration info

set_update_conf

Clears the configuration info for the given deck, and replaces it with any data passed in via the request.

Request

Deck configuration object

Response

None

CardHandler

A card is serialized in the following format:

{
  "id": "...",
  "isEmpty": "...",
  "css": "...",
  "question": "...",
  "answer": "...",
  "did": "...",
  "due": "...",
  "factor": "...",
  "ivl": "...",
  "lapses": "...",
  "left": "...",
  "mod": "...",
  "nid": "...",
  "odid": "...",
  "odue": "...",
  "ord": "...",
  "queue": "...",
  "reps": "...",
  "type": "...",
  "usn": "...",
  "timerStarted": "..."
}

Additionally, any of the fields note, deck, or latest_revlog may be present depending on the situation.

index

Returns the card matching the given ID in the URL.

Request

No required or optional parameters.

Response

Object representing a serialized deck

add_tags

Adds tags to the note for the card matching the given ID in the URL. See NoteHandler.add_tags.

Request

Required parameters

tags (list) - list of new tags for the note

Optional parameters

update_mod (boolean) - defaults to True. If False, the note's last-modified date will not be updated.

Response

Note

remove_tags

Removes tags from the note for the card matching the given ID in the URL. See NoteHandler.remove_tags.

Request

Required parameters

tags (list) - list of tags to remove from the note

Optional parameters

update_mod (boolean) - defaults to True. If False, the note's last-modified date will not be updated.

Response

Note

stats_report

Returns a status report for the card matching the given ID in the URL.

Request

No required or optional parameters.

Response

Returns card stats (from Anki collection)

latest_revlog

Returns the latest revision log for the card matching the ID in the URL.

Request

No required or optional parameters.

Response

Returns an object:

{
  "id": "...",
  "ease": "...",
  "timestamp": "..."
}