API reference

With the Recall API, you can manage decks, fields, cards, and layouts programmatically.

It is organized around REST. It accepts JSON-encoded requests, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

https://api.recall.cards

Authentication

Recall uses API keys to authenticate requests. You can view and manage your API keys in your account settings.

Authentication to the API is performed via HTTP basic authentication. Provide your API key as the basic auth username value. You do not need to provide a password.

curl https://api.recall.cards/v1/decks \
  -u YOUR_API_KEY:
# The colon prevents curl from asking for a password.

HTTP status codes and errors

Recall uses conventional HTTP response codes to indicate the success or failure of an API request.

Codes in the 2xx range indicate success. Codes in the 4xx range indicate client errors related to the information provided, and codes in the 5xx range indicate server errors.

Code	Status	Description
200	OK	Everything worked as expected.
201	Created	The request has been fulfilled and resulted in a new resource being created.
204	No Content	The request has been fulfilled and resulted in no content being returned.
400	Bad Request	The request was invalid, often due to missing or invalid parameters.
401	Unauthorized	No valid API key was provided.
404	Not Found	The requested resource was not found.
429	Too Many Requests	Too many requests hit the API too quickly.
500	Internal Server Error	An error occurred on Recall's side.

When an error occurs, the API will return the appropriate HTTP status code and a JSON response containing an error object with a message property.

Example error response

{
  "error": {
    "message": "The requested deck was not found.",
  }
}

Pagination

All API resources have support for bulk fetches through “list” API methods. These methods share a common structure and accept the parameters limit, starting_after, and ending_before.

Both starting_after and ending_before accept an existing object ID value and allow to list objects after or before the given object. You can use either the starting_after or ending_before parameter, but not both simultaneously.

limit optional, default is 10

The maximum number of objects to return, ranging between 1 and 100.

starting_after optional

A cursor to use in pagination. starting_after is an object ID that defines your place in the list. For example, if you make a card list request and receive 100 cards, ending with card_2sdInOpM83eo, your subsequent call can include starting_after=card_2sdInOpM83eo to fetch the next page of the list.

ending_before optional

A cursor to use in pagination. Similarly to starting_after, ending_before is an object ID that allows you to fetch object in the previous page of the list.

List response format

{
  "object": "list",
  "has_more": true
  "data": [
    //...
  ],
}

object string, value is "list"

The type of object returned.

data array

An array containing the actual response elements.

has_more boolean

Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

Expanding responses

Some objects allow you to request additional information as an expanded response by using the expand parameter. This parameter is available on all API requests that return an expandable object, or a list of expandable objects.

For example, you can get deck fields details when you request a deck by adding the expand parameter to the request.

curl https://api.recall.cards/v1/decks/deck_5gvuzRdHW2ac \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "expand": ["deck_fields"]
  }'

expand array of strings, optional

An array of object names to expand. Possible expandable objects in a response are indicated in the documentation of the concerned endpoints.

Returns

{
  "id": "deck_5gvuzRdHW2ac",
  "object": "deck",
  // ...
  "deck_fields": [
    {
      "id": "field_5gvuzRdHW2ac",
      "object": "deck_field",
      // ...
    },
    {
      "id": "field_uYS9PpONoqTP",
      "object": "deck_field",
      // ...
    }
  ]
}

Decks