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.
403	Forbidden	The API key does not have permission to perform the request.
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 returns the appropriate HTTP status code and a JSON response containing the error object.

The error object

{
  "error": {
    "message": "The deck name is missing.",
    "code": "validation_error",
    "param": "name"
  }
}

message string

A human-readable description of the error, intended to be displayed to the end user.

code string

A short, stable, machine-readable identifier for the error category. Use it to handle different error cases programmatically.

param nullable string

The name of the request parameter that caused the error, when applicable. Returns null in errors that are not related to a specific parameter.

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 you 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 objects 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 attributes of an object are references to other objects. By default, these attributes are returned as string IDs (or arrays of string IDs). You can request the full related objects by using the expand query parameter.

expand is passed as a query string parameter on GET endpoints (retrieve and list) whose response contains an expandable attribute. The list of expandable attributes is documented in the response object of each endpoint.

For example, deck_fields on a deck is an array of deck field IDs by default. You can retrieve the full deck field objects by including deck_fields in the expand parameter.

curl https://api.recall.cards/v1/decks/deck_5gvuzRdHW2ac?expand=deck_fields \
  -u YOUR_API_KEY:

To expand multiple attributes, pass them as a comma-separated list:

curl https://api.recall.cards/v1/decks/deck_5gvuzRdHW2ac?expand=deck_fields,card_layouts \
  -u YOUR_API_KEY:

Passing an attribute that is not documented as expandable for the endpoint returns a 400 Bad Request.

expand array of strings, optional

An array of attribute names to expand. Each attribute must be explicitly documented as expandable in the endpoint's response object.

Returns

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

Decks