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.

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 an empty array)
• 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.

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: ```json { "new_cards": [...], "learning_cards": [...], "review_cards": [...] }

### 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
TODO

### latest_revlog
TODO

### stats_report
TODO

## Global / Misc
### set_language
TODO

# ModelHandler
### field_names
TODO

# NoteHandler
### index
TODO

### update
TODO

### delete
TODO

### add_tags
TODO

### remove_tags
TODO

# DeckHandler
### index
TODO

### next_card
TODO

### get_conf
TODO

### set_update_conf
TODO

# CardHandler
### index
TODO

### add_tags
TODO

### remove_tags
TODO

### stats_report
TODO

### latest_revlog
TODO