-
Notifications
You must be signed in to change notification settings - Fork 95
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!
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.
Store fields definitions and templates for notes.
Returns a list of all models in a collection
No parameters.
array of objects, each representing a model
Returns a model that matches the given name
-
model
(string)
object, representing a model. If no model is found with the given name, an empty response will be sent.
Information (in fields per the model) that can generate a card (based on a template from the model).
Finds a set of notes
-
query
(string) (omitting this will return all notes) -
preload
(boolean)
array of objects, each representing a note.
TODO Description
-
updated_since
(date) -
limit
(integer) -
preload
(boolean)
TODO
TODO Description
-
model
(string)
-
fields
(object) -
tags
(string)
None
Returns a list of all models in a collection
No parameters.
array of objects, each representing a model
Groups of cards.
Returns a list of all decks in the collection.
No parameters.
array of objects, each representing a deck
Switches to a deck specified by the given ID number or name.
-
deck
(string or number)
None
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.
-
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".
Returns an object representing the newly created dynamic deck.
If a dynamic deck exists with the given name, clears that deck.
-
name
(string) - defaults to "Custom Study Session"
None
A specific card in a deck with a history of review (generated from a note based on the template).
Returns a set of cards that match the given query.
-
query
(string) - defaults to '' (TODO document query) -
order
(boolean) - defaults toFalse
-
limit
(int) - defaults to 0 -
offset
(int) - defaults to 0 -
preload
(boolean) - defaults toFalse
List of objects representing cards that were retrieved by the query
Returns a list of cards ordered by last update date, with the most recently updated cards returned first.
-
updated_since
(date string) -
limit
(int) - defaults to 10 -
preload
(boolean) - defaults toFalse
List of objects representing cards that were retrieved by the query
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
.
Resets schedule for the given deck. Returns an list of new, learning, and review cards.
-
deck
(string or int) - Deck ID or name
array:
{
"new_cards": "int",
"learning_cards": "int",
"review_cards": "int"
}
Extend the scheduler's limits to allow a certain number of new and review cards.
-
new_cards
(int) - defaults to 0 -
review_cards
(int) - defaults to 0
None
Proceed to the next card in the deck. The timer for the card will be started.
-
deck
(string or int) - Deck ID or name
object representing the next card in the deck
Note: The scheduler must be set up before this route is called, or an error will occur and will not be displayed properly.
-
id
(long) - Card ID -
ease
(int)
None
Suspends cards matching the given IDs.
-
ids
(list) - list of Card IDs
None
Unsuspends cards matching the given IDs.
-
ids
(list) - list of Card IDs
None
Returns the most recent ease for each card.
-
ids
(list) - list of Card IDs. If omitted, will select all cards.
List of objects:
{
"id": "long",
"ease": "int",
"timestamp": "int"
}
Returns recent entries from the revlog.
-
updated_since
(date string) -
limit
(int) - defaults to 100
List of objects:
{
"id": "long",
"ease": "int",
"timestamp": "int",
"card_id": "int",
"usn": "...",
"interval": "...",
"last_interval": "...",
"factor": "...",
"time": "...",
"type": "..."
}
Generates an HTML stats report based on user's performance
-
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 toFalse
-
include_jquery
(boolean) - defaults toFalse
-
include_flot
(boolean) - defaults toFalse
HTML stats report
Sets the language used by Anki.
-
code
(string)
Handler group for the 'collection' type, but it's not added by default.
-
filetype
(string) Eitherdata
orurl
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.
Returns a list of field namesmatching the given model ID in the URL.
No required or optional parameters.
List of field names
A note is serialized with the following format:
{
"id": "...",
"guid": "...",
"model": "...",
"mid": "...",
"mod": "...",
"scm": "...",
"tags": "...",
"string_tags": "...",
"fields": {},
"flags": "...",
"usn": "...",
}
Returns a note matching the given ID in the URL.
No required or optional parameters.
Object representing a serialized note
Updates the fields in a note matching the given ID in the URL.
-
fields
(object) - Keys are fields to update, values are the updated field values -
tags
(list) - updated list of tags for the note
-
update_mod
(boolean) - defaults toTrue
. IfFalse
, the note's last-modified date will not be updated.
Note
Deletes a note matching the given ID in the URL.
No required or optional parameters.
None
Adds tags to a note matching the given ID in the URL.
-
tags
(list) - list of new tags for the note
-
update_mod
(boolean) - defaults toTrue
. IfFalse
, the note's last-modified date will not be updated.
Note
Removes tags from a note matching the given ID in the URL.
-
tags
(list) - list of tags to remove from the note
-
update_mod
(boolean) - defaults toTrue
. IfFalse
, the note's last-modified date will not be updated.
Note
Returns a deck matching the given ID or name in the URL.
No required or optional parameters.
Object representing a serialized deck
Proceeds to the next card in the deck's collection, and returns that card. See CollectionHandler.next_card.
No required or optional parameters.
Object representing a serialized card
No required or optional parameters.
Deck configuration info
Clears the configuration info for the given deck, and replaces it with any data passed in via the request.
Deck configuration object
None
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.
Returns the card matching the given ID in the URL.
No required or optional parameters.
Object representing a serialized deck
Adds tags to the note for the card matching the given ID in the URL. See NoteHandler.add_tags.
-
tags
(list) - list of new tags for the note
-
update_mod
(boolean) - defaults toTrue
. IfFalse
, the note's last-modified date will not be updated.
Note
Removes tags from the note for the card matching the given ID in the URL. See NoteHandler.remove_tags.
-
tags
(list) - list of tags to remove from the note
-
update_mod
(boolean) - defaults toTrue
. IfFalse
, the note's last-modified date will not be updated.
Note
Returns a status report for the card matching the given ID in the URL.
No required or optional parameters.
Returns card stats (from Anki collection)
Returns the latest revision log for the card matching the ID in the URL.
No required or optional parameters.
Returns an object:
{
"id": "...",
"ease": "...",
"timestamp": "..."
}