Documentation

API Reference

The Mochi API is organized around REST. It accepts JSON or transit+json encoded request bodies and returns either json or transit+json encoded responses. When making requests with JSON, keyword parameters must be sent as strings.

Base URL:

https://app.mochi.cards/api/

Authentication

Mochi uses API Keys to authenticate requests. You can view and manage your API Keys in the Account Settings window within the app.

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

curl https://app.mochi.cards/api/decks -u my_api_key:
# The colon prevents curl from asking for a password.

Tip

Basic auth credentials must be base64 encoded. Run the above cURL command with -v to see the base64 encoded version of your API key.

Pagination

Some requests return a list of resources. The response will be an object with a docs property and a bookmark property. The docs property will contain alist of the documents, and the bookmark property can be used in subsequent requests to fetch the next logical page of the collection. Not every request that returns a bookmark has additional pages.

{
  "bookmark": "g1AAAABAeJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYpzZGdmBxqXeTuB5Dlg8igyWQA7BRJR",
  "docs": [
    {
      "id": "HJBMBGBO",
      "sort": 6,
      "name": "New Deck"
    },
    ...
  ]
}

Errors

Mochi uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a document was not found, etc.). Codes in the 5xx range indicate an error with Mochi's servers (these are rare).

In most cases the API will also return a JSON or Transit response with more information about the error. In the case of validation errors, there will be a key corresponding to each field that failed validation.

Example error responses:

500 { "errors" ["Something went wrong!"] }
403 { "errors" ["Please upgrade to use this feature."] }
422 { "errors" { "content": ":content field cannot be nil." } }

Rate limits

The Mochi API uses rate limit to protect against bursts of traffic and help maximize stability. If you send many requests in quick succession, you might see error responses with status code 429.

Concurrency limiter

The concurrency limiter restricts the number of concurrent active requests. Currently API calls are limited to one concurrent request per account. You must wait for the previous request to return before issuing a new request.

Cards

Endpoints:

GET    /cards       -- List cards
POST   /cards       -- Create a card
GET    /cards/:id   -- Retrieve a card
POST   /cards/:id   -- Update a card
DELETE /cards/:id   -- Delete a card

Create a card

POST https://app.mochi.cards/api/cards/

Cards can be created one at a time. Cards can be stored in a deck and can contain markdown content.

Parameters

content required
string - The markdown content of the card.
deck-id required
keyword - The deck ID that the card belongs too.
template-id optional
keyword - The ID of the template to use for this card.
archived? optional
boolean - Whether the card is archived or not.
review-reverse? optional
boolean - Whether the card should also be reviewed in reverse order (bottom to top).
pos optional
string - The relative position of the card within the deck. Cards are sorted lexicographically by the value of this attribute. For example if card A has a :pos of "6" and card B has a :pos of "7", you can create a new card in between them by setting its :pos to "6V".
manual-tags optional
set of strings - A set (or an array in JSON) of tags to add to the card. Use this when you want to attach tags to a card without adding them to the content of the card. Tags should not include the initial # character.
fields optional
map - A map of field IDs (keyword) to field values. If the fields attribute is present, the content field can be left blank (it will be ignored when the card is rendered). The field IDs should correspond to the fields defined on the template used by the card. Fields can be displayed within a template using the following syntax: << Field name >>. Each value in the map is another map with the following structure:
- id required
  keyword - The ID of the field. Should be the same as the key for this value.
- value required
  string - The value to be used for this field on this card.

Example request

POST https://app.mochi.cards/api/cards/
Content-Type: application/json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

{
  "content": "New card from API. ![](@media/foobar03.png)",
  "deck-id": "btmZUXWM",
  "template-id": "8BtaEAXe",
  "fields": {
    "name": {
      "id": "name",
      "value": "Hello,"
    },
    "JNEnw1e7": {
      "id": "JNEnw1e7",
      "value": "World!"
    },
  },
  "review-reverse?": false,
  "archived?": false,
  "pos": "6V",
  "manual-tags": ["philosophy", "philosophy/aristotle"]
}

POST https://app.mochi.cards/api/cards/
Content-Type: application/transit+json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

{
  "~:content": "New card from API. ![](@media/foobar03.png)",
  "~:deck-id": "~:btmZUXWM",
  "~:template-id": "~:8BtaEAXe",
  "~:fields": {
    "~:name": {
      "~:id": "~:name",
      "~:value": "Hello,"
    },
    "~:JNEnw1e7": {
      "~:id": "~:JNEnw1e7",
      "~:value": "World!"
    },
  },
  "~:review-reverse?": false,
  "~:archived?": false,
  "~:pos": "6V",
  "~:tags": {"~#set": ["philosophy", "philosophy/aristotle"]}
}

Returns

This will return the created card if successful. Will return an error if something goes wrong, usually if required parameters are missing, or if supplied parameters fails validation.

Retrieve a card

GET https://app.mochi.cards/api/cards/:card-id

Retrieves a card that already exists. The returned data will look identical to the data returned from the card creation request.

Parameters

No parameters.

Example request

GET https://app.mochi.cards/api/cards/btmZUXWM
Accept: application/json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

Returns

Example response

{
  "updated-at": {
    "date": "2021-09-11T14:23:53.250Z"
  },
  "tags": [],
  "content": "New card from API.",
  "name": null,
  "deck-id": "btmZUXWM",
  "pos": "00F",
  "references": [],
  "id": "QQJ8ssvL",
  "reviews": [],
  "created-at": {
    "date": "2021-09-10T01:29:49.879Z"
  },
  "new?": false,
  "archived?": true,
  "template-id": null
}

{
  "~:updated-at": {
    "~#dt": 1631370233250
  },
  "~:tags": {
    "~#set": []
  },
  "~:content": "New card from API.",
  "~:name": null,
  "~:deck-id": "~:btmZUXWM",
  "~:pos": "00F",
  "~:references": {
    "~#set": []
  },
  "~:id": "~:QQJ8ssvL",
  "~:reviews": [],
  "~:created-at": {
    "~#dt": 1631237389879
  },
  "~:new?": false,
  "~:archived?": true,
  "~:template-id": null
}

List cards

GET https://app.mochi.cards/api/cards/

Lists cards in pages of 10 cards per page. Use the bookmark attribute to request the next page. Optionally specific a deck-id to fetch only cards for that deck.

Parameters

deck-id optional
string - Only return cards for the deck specified by this deck ID.
limit optional
number - The number of cards to return per page. The limit can range from 1 and 100, and the default is 10.
bookmark optional
string - A cursor for use in pagination. Returned from a previous list request that has additional documents.

Example request

# Without a bookmark
GET https://app.mochi.cards/api/cards/

# With a bookmark
GET https://app.mochi.cards/api/cards?bookmark=some-bookmark

# With a deck-id
GET https://app.mochi.cards/api/cards?deck-id=my-deck-id

Returns

A dictionary with a docs property that contains an array of up to limit cards, and a bookmark property that can be used to fetch the next page of results.

Example response

{
  "bookmark": "g1AAAABAeJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYpzGGY5BzimZYaD5Dlg8igyWQAw3xHv",
  "docs": [
    {
      "tags": [],
      "content": "# Hello, world!",
      "name": "Hello world",
      "deck-id": "eH53Hxe8",
      "fields": {},
      "pos": "1",
      "references": [],
      "id": "00UlY4dd",
      "reviews": [],
      "created-at": {
        "date": "2021-09-09T02:49:58.535Z"
      }
    },
    ...
  ]
}

{
  "~:bookmark": "g1AAAABAeJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYpzGGY5BzimZYaD5Dlg8igyWQAw3xHv",
  "~:docs": [
    {
      "~:tags": {
        "~#set": []
      },
      "~:content": "# Hello, world!",
      "~:name": "Hello world",
      "~:deck-id": "~:eH53Hxe8",
      "~:fields": {},
      "~:pos": "1",
      "~:references": {
        "~#set": []
      },
      "~:id": "~:00UlY4dd",
      "~:reviews": [],
      "~:created-at": {
        "~#dt": 1631155798535
      }
    },
    ...
  ]
}

Update a card

POST https://app.mochi.cards/api/cards/:card-id

Updating a card accepts most of the same parameters as creating a card. The ID of the card must be passed in as part of the URL.

Parameters

content optional
string - The markdown content of the card.
deck-id optional
keyword - The deck ID that the card belongs too.
template-id optional
keyword - The ID of the template to use for this card.
archived? optional
boolean - Whether the card is archived or not.
trashed? optional
timestamp - Whether the card is in the trash or not. Timestamps should be ISO 8601 format, matching javascript's Date#toJSON method.
review-reverse? optional
boolean - Whether the card should also be reviewed in reverse order (bottom to top).
pos optional
string - The relative position of the card within the deck. Cards are sorted lexicographically by the value of this attribute. For example if card A has a :pos of "6" and card B has a :pos of "7", you can create a new card in between them by setting its :pos to "6V".
manual-tags optional
set of strings - A set (or an array in JSON) of tags to add to the card. Use this when you want to attach tags to a card without adding them to the content of the card. Tags should not include the initial # character. Setting this will overwrite whatever value for this field was already set on the card.
fields optional
map - A map of field IDs (keyword) to field values. The field IDs should correspond to the fields defined on the template used by the card. Fields can be displayed within a template using the following syntax: << Field name >>. Each value in the map is another map with the following structure:
- id required
  keyword - The ID of the field. Should be the same as the key for this value.
- value required
  string - The value to be used for this field on this card.

Example request

POST https://app.mochi.cards/api/cards/00UlY4dd
Content-Type: application/json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

{
  "content": "New card from API. ![](@media/foobar03.png)",
  "deck-id": "btmZUXWM",
  "review-reverse?": false,
  "archived?": false,
  "pos": "6V",
  "manual-tags": ["philosophy", "philosophy/aristotle"]
}

POST https://app.mochi.cards/api/cards/00UlY4dd
Content-Type: application/transit+json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

{
  "~:content": "New card from API. ![](@media/foobar03.png)",
  "~:deck-id": "~:btmZUXWM",
  "~:review-reverse?": false,
  "~:archived?": false,
  "~:pos": "6V",
  "~:tags": {"~#set": ["philosophy", "philosophy/aristotle"]}
}

Delete a card

DELETE https://app.mochi.cards/api/cards/:card-id

Permanently deletes a card and its attachments.

Warning

This action cannot be undone. For a "soft" deletion you can update a card and set its trashed? property to the current time (as an ISO 8601 timestamp).

Parameters

None.

Example request

DELETE https://app.mochi.cards/api/cards/00UlY4dd
Content-Type: application/json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

DELETE https://app.mochi.cards/api/cards/00UlY4dd
Content-Type: application/transit+json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

Add an attachment

You can add an attachment to a card using a separate request. This request must be sent as form data with the content-type of form/multi-part.

Parameters

None.

Example request

POST https://app.mochi.cards/api/cards/00UlY4dd/attachments/Q9DlrByP.mp3
Content-Type: multipart/form-data; boundary=------------------------924hzYpC8yIyyc579xl9Zw
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

POST https://app.mochi.cards/api/cards/00UlY4dd/attachments/Q9DlrByP.mp3
Content-Type: multipart/form-data; boundary=------------------------924hzYpC8yIyyc579xl9Zw
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

Example curl request

curl -POST https://app.mochi.cards/api/cards/00UlY4dd/attachments/Q9DlrByP.mp3 -u my_api_key: \
    -H "Content-Type: multipart/form-data" \
    -F file="@/path/to/attachment/my_recording.mp3"

Example fetch request

const formData = new FormData();
formData.append("file", someBlob, "Q9DlrByP.mp3");
fetch("https://app.mochi.cards/api/cards/00UlY4dd/attachments/Q9DlrByP.mp3", {
    method: "POST",
    body formData
});

Example python request

imoprt requests

def add_attachment(file_name, card_id):
    url = f"https://app.mochi.cards/api/cards/{card_id}/attachments/{file_name}"
    basic = HTTPBasicAuth(api_key, "")
    with open(file_name, 'rb') as audio_file:
        data = {
            'file': (file_name, audio_file, 'audio/wav')
        }
        requests.post(url, files=data, auth=basic)

Delete an attachment

You can delete an attachment from a card by sending a DELETE request.

Parameters

None.

Example request

DELETE https://app.mochi.cards/api/cards/00UlY4dd/attachments/Q9DlrByP.mp3

POST https://app.mochi.cards/api/cards/00UlY4dd/attachments/Q9DlrByP.mp3

Example curl request

curl -DELETE https://app.mochi.cards/api/cards/00UlY4dd/attachments/Q9DlrByP.mp3 -u my_api_key:

Decks

Decks are the containers of cards. They can also contain other nested decks. Various properties can be set on a deck to control how cards a reviewed, and how the cards are displayed on the deck page.

Endpoints:

GET    /decks       -- List decks
POST   /decks       -- Create a deck
GET    /decks/:id   -- Retrieve a deck
POST   /decks/:id   -- Update a deck
DELETE /decks/:id   -- Delete a deck

Create a deck

POST http://localhost:8090/api/decks/

Decks fundamentally act as collections of cards. In addition to cards, decks can also contain other decks to create heirarchies of content. There are also a number of properties on the deck that control how cards are displayed and reviewd.

Parameters

name required
string - A string representing the name of the deck.
parent-id optional
keyword - The ID of a parent deck to nest this deck under.
sort optional
integer - Decks are sorted numerically based on this number.
trashed? optional
timestamp - Whether the deck is in the trash or not. Cards and child decks within a trashed deck will also be effectively trashed. Timestamps should be ISO 8601 format, matching javascript's Date#toJSON method.
archived? optional
boolean - Whether the deck is archived. Cards in archived will not show up as new cards or be due for review.
sort-by optional
keyword - Determines how cards are sorted on the deck page. Does not effect reviews or new card learning order. One of :none :lexigraphically :lexicographically :created-at :updated-at :retention-rate-asc :interval-length
cards-view optional
keyword - Determined how cards will be displayed on the deck page. One of :list :grid :note :column.
show-sides? optional
boolean - Whether or not to show all sides of a card on the deck page or not.
sort-by-direction optional
boolean - When true cards sort order will be reversed.
review-reverse? optional
boolean - Whether or not to reveal the sides of a cards in the deck in reverse order or not (bottom to top) in addition to the normal order (top to bottom).

Example request

POST http://localhost:8090/api/decks/
Content-Type: application/json
Accept: application/json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

{
  "name": "My new deck",
  "parent-id": "HJBMBGBO",
  "sort": 1,
  "archived?": true,
  "trashed?": "2012-04-23T18:25:43.511Z",
  "show-sides?": true,
  "sort-by-direction": true,
  "review-reverse?": true
}

POST http://localhost:8090/api/decks/
Content-Type: application/transit+json
Accept: application/transit+json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

{
  "~:name": "My new deck",
  "~:parent-id": "~:HJBMBGBO",
  "~:sort": 1,
  "~:archived?": true,
  "~:sort-by": "~:lexicographically",
  "~:trashed?": { "~#dt": 1645620058825 },
  "~:cards-view": "~:list",
  "~:show-sides?": true,
  "~:sort-by-direction": true,
  "~:review-reverse?": true
}

Returns

Returns the deck that was created, including its ID any any other fields that were populated automatically.

Example response

{
  "sort-by-direction": true,
  "name": "My new deck",
  "show-sides?": true,
  "cards-view": "list",
  "id": "RMb5BZ67",
  "review-reverse?": true,
  "parent-id": "HJBMBGBO",
  "sort-by": "lexicographically",
  "archived?": true,
  "sort": 1
}

{
  "~:sort-by-direction": true,
  "~:name": "My new deck",
  "~:show-sides?": true,
  "~:cards-view": "~:list",
  "~:id": "~:6vXRDbq0",
  "~:review-reverse?": true,
  "~:parent-id": "~:HJBMBGBO",
  "~:sort-by": "~:lexicographically",
  "~:archived?": true,
  "~:sort": 1
}

Retrieve a deck

GET https://app.mochi.cards/api/decks/:deck-id

Retrieves a deck that already exists. The returned data will look identical to the data returned from the deck creation request.

Parameters

No parameters.

Example request

GET https://app.mochi.cards/api/decks/btmZUXWM
Accept: application/json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

Returns

Returns the deck in whichever encoding is specified in the Accept header.

Example response

{
  "sort-by-direction": true,
  "name": "My new deck",
  "show-sides?": true,
  "cards-view": "list",
  "id": "RMb5BZ67",
  "review-reverse?": true,
  "parent-id": "HJBMBGBO",
  "sort-by": "lexicographically",
  "archived?": true,
  "sort": 1
}

{
  "~:sort-by-direction": true,
  "~:name": "My new deck",
  "~:show-sides?": true,
  "~:cards-view": "~:list",
  "~:id": "~:6vXRDbq0",
  "~:review-reverse?": true,
  "~:parent-id": "~:HJBMBGBO",
  "~:sort-by": "~:lexicographically",
  "~:archived?": true,
  "~:sort": 1
}

List all decks

GET https://app.mochi.cards/api/decks/

Parameters

:bookmark optional
string - A cursor for use in pagination. Returned from a previous list request that has additional documents.

Example request

# Without a bookmark
GET https://app.mochi.cards/api/decks/

# With a bookmark
GET https://app.mochi.cards/api/decks?bookmark=somebookmarkgoeshere

Returns

A list of documents containing a bookmark.

Example response

{
  "bookmark": "g1AAAABAeJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYpzGGY5BzimZYaD5Dlg8igyWQAw3xHv",
  "docs": [
    {
      "id": "HJBMBGBO",
      "sort": 6,
      "name": "New Deck"
    },
    ...
  ]
}

{
  "~:bookmark": "g1AAAABAeJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYpzGGY5BzimZYaD5Dlg8igyWQAw3xHv",
  "~:docs": [
    {
      "~:id": "~:HJBMBGBO",
      "~:sort": 6,
      "~:name": "New Deck"
    },
    ...
    ...
  ]
}

Update a deck

POST https://app.mochi.cards/api/decks/:deck-id

Parameters

name optional
string - A string representing the name of the deck.
parent-id optional
keyword - The ID of a parent deck to nest this deck under.
sort optional
integer - Decks are sorted numerically based on this number.
trashed? optional
timestamp - Whether the deck is in the trash or not. Cards and child decks within a trashed deck will also be effectively trashed. Timestamps should be ISO 8601 format, matching javascript's Date#toJSON method.
archived? optional
boolean - Whether the deck is archived. Cards in archived will not show up as new cards or be due for review.
sort-by optional
keyword - Determines how cards are sorted on the deck page. Does not effect reviews or new card learning order. One of :none :lexigraphically :lexicographically :created-at :updated-at :retention-rate-asc :interval-length
cards-view optional
keyword - Determined how cards will be displayed on the deck page. One of :list :grid :note :column.
show-sides? optional
boolean - Whether or not to show all sides of a card on the deck page or not.
sort-by-direction optional
boolean - When true cards sort order will be reversed.
review-reverse? optional
boolean - Whether or not to reveal the sides of a cards in the deck in reverse order or not (bottom to top) in addition to the normal order (top to bottom).

Example request

POST https://app.mochi.cards/api/decks/RMb5BZ67
Content-Type: application/json
Accept: application/json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

{
  "name": "My new deck",
  "parent-id": "HJBMBGBO",
  "sort": 1,
  "archived?": true,
  "trashed?": "2012-04-23T18:25:43.511Z",
  "show-sides?": true,
  "sort-by-direction": true,
  "review-reverse?": true
}

POST https://app.mochi.card/api/decks/
Content-Type: application/transit+json
Accept: application/transit+json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

{
  "~:name": "My new deck",
  "~:parent-id": "~:HJBMBGBO",
  "~:sort": 1,
  "~:archived?": true,
  "~:sort-by": "~:lexicographically",
  "~:trashed?": { "~#dt": 1645620058825 },
  "~:cards-view": "~:list",
  "~:show-sides?": true,
  "~:sort-by-direction": true,
  "~:review-reverse?": true
}

Returns

Returns the deck that was updated.

Example response

{
  "sort-by-direction": true,
  "name": "My new deck",
  "show-sides?": true,
  "cards-view": "list",
  "id": "RMb5BZ67",
  "review-reverse?": true,
  "parent-id": "HJBMBGBO",
  "sort-by": "lexicographically",
  "archived?": true,
  "sort": 1
}

{
  "~:sort-by-direction": true,
  "~:name": "My new deck",
  "~:show-sides?": true,
  "~:cards-view": "~:list",
  "~:id": "~:6vXRDbq0",
  "~:review-reverse?": true,
  "~:parent-id": "~:HJBMBGBO",
  "~:sort-by": "~:lexicographically",
  "~:archived?": true,
  "~:sort": 1
}

Delete a deck

DELETE https://app.mochi.cards/api/decks/:deck-id

Permanently deletes a deck. TODO: Cards and decks in the deleted deck are not deleted.

Warning

This action cannot be undone. For a "soft" deletion you can update a deck and set its trashed? property to the current time as an ISO 8601 timestamp.

Parameters

None.

Example request

DELETE https://app.mochi.cards/api/decks/RMb5BZ67
Content-Type: application/json
Accept: application/json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

DELETE https://app.mochi.card/api/decks/
Content-Type: application/transit+json
Accept: application/transit+json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

Returns

Nothing.

Templates

Templates can be applied to decks and / or cards. Templates allow you to render content to cards using fields.

Endpoints:

GET  /templates       -- List templates
POST /templates       -- Create a template
GET  /templates/:id   -- Retrieve a template

Create a template

POST https://app.mochi.cards/api/templates/

Templates define the structure and layout for cards using field placeholders. Templates can contain markdown content and field references that get populated with card-specific data. TIP: You can use the "Retrieve a template" endpoint to examine the structure of an existing template and use that as the basis for creating a new one.

Parameters

name required
string - The name of the template (1-64 characters).
content required string - The markdown content of the template with field placeholders like << Field name >>.
pos optional
string - The relative position of the template for sorting. Templates are sorted lexicographically by this value.
fields required map - A map of field IDs (keyword) to field definitions. Each field defines how content should be input and processed. Each field is a map with the following structure:
- id required
  keyword - The ID of the field. Should be the same as the key for this field.
- name optional
  string - The human-readable name for this field.
- type optional
  keyword - The field type. One of :text :boolean :number :draw :ai :speech :image :translate :transcription :dictionary :pinyin :furigana.
- pos optional
  string - The relative position for sorting fields within the template.
- content optional
  string - Default content or instructions for this field.
- options optional
  map - Field-specific options like :multi-line?, :hide-term, :ai-task, etc.
style optional
map - Styling options for the template:
- text-alignment optional
  keyword - Text alignment. One of :left :center :right.
options optional
map - Template-level options:
- show-sides-separately? optional
  boolean - Whether to show template sides separately during review.

Example request

POST https://app.mochi.cards/api/templates/
Content-Type: application/json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

{
  "name": "Vocabulary Card",
  "content": "# << Word >>\n\n**Definition:** << Definition >>\n\n**Example:** << Example >>",
  "pos": "a",
  "fields": {
    "word": {
      "id": "word",
      "name": "Word",
      "type": "text",
      "pos": "a"
    },
    "definition": {
      "id": "definition", 
      "name": "Definition",
      "type": "text",
      "pos": "b",
      "options": {
        "multi-line?": true
      }
    },
    "example": {
      "id": "example",
      "name": "Example", 
      "type": "text",
      "pos": "c",
      "options": {
        "multi-line?": true
      }
    }
  },
  "style": {
    "text-alignment": "left"
  },
  "options": {
    "show-sides-separately?": false
  }
}

POST https://app.mochi.cards/api/templates/
Content-Type: application/transit+json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

{
  "~:name": "Vocabulary Card",
  "~:content": "# << Word >>\n\n**Definition:** << Definition >>\n\n**Example:** << Example >>",
  "~:pos": "a",
  "~:fields": {
    "~:word": {
      "~:id": "~:word",
      "~:name": "Word",
      "~:type": "~:text",
      "~:pos": "a"
    },
    "~:definition": {
      "~:id": "~:definition",
      "~:name": "Definition", 
      "~:type": "~:text",
      "~:pos": "b",
      "~:options": {
        "~:multi-line?": true
      }
    },
    "~:example": {
      "~:id": "~:example",
      "~:name": "Example",
      "~:type": "~:text", 
      "~:pos": "c",
      "~:options": {
        "~:multi-line?": true
      }
    }
  },
  "~:style": {
    "~:text-alignment": "~:left"
  },
  "~:options": {
    "~:show-sides-separately?": false
  }
}

Returns

Returns the created template with its generated ID and any automatically populated fields.

Example response

{
  "id": "XyZ123Ab",
  "name": "Vocabulary Card",
  "content": "# << Word >>\n\n**Definition:** << Definition >>\n\n**Example:** << Example >>",
  "pos": "a",
  "fields": {
    "word": {
      "id": "word",
      "name": "Word", 
      "type": "text",
      "pos": "a"
    },
    "definition": {
      "id": "definition",
      "name": "Definition",
      "type": "text", 
      "pos": "b",
      "options": {
        "multi-line?": true
      }
    },
    "example": {
      "id": "example", 
      "name": "Example",
      "type": "text",
      "pos": "c",
      "options": {
        "multi-line?": true
      }
    }
  },
  "style": {
    "text-alignment": "left"
  },
  "options": {
    "show-sides-separately?": false
  }
}

{
  "~:id": "~:XyZ123Ab",
  "~:name": "Vocabulary Card", 
  "~:content": "# << Word >>\n\n**Definition:** << Definition >>\n\n**Example:** << Example >>",
  "~:pos": "a",
  "~:fields": {
    "~:word": {
      "~:id": "~:word",
      "~:name": "Word",
      "~:type": "~:text", 
      "~:pos": "a"
    },
    "~:definition": {
      "~:id": "~:definition",
      "~:name": "Definition",
      "~:type": "~:text",
      "~:pos": "b", 
      "~:options": {
        "~:multi-line?": true
      }
    },
    "~:example": {
      "~:id": "~:example",
      "~:name": "Example", 
      "~:type": "~:text",
      "~:pos": "c",
      "~:options": {
        "~:multi-line?": true
      }
    }
  },
  "~:style": {
    "~:text-alignment": "~:left"
  },
  "~:options": {
    "~:show-sides-separately?": false
  }
}

Retrieve a template

Retrieves a template that already exists.

Parameters

No parameters.

Example request

GET https://app.mochi.cards/api/templates/btmZUXWM
Accept: application/json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

Returns

Returns the template in whichever encoding is specified in the Accept header.

Example response

{
  "id": "YDELNZSu",
  "name": "Simple flashcard",
  "content": "# << Front >>\n---\n<< Back >>",
  "pos": "s",
  "fields": {
    "name": {
      "id": "name",
      "name": "Front",
      "pos": "a"
    },
    "Ysrde7Lj": {
      "id": "Ysrde7Lj",
      "name": "Back",
      "pos": "m",
      "options": {
        "multi-line?": true
      }
    }
  }
}

{
  "~:id": "~:YDELNZSu",
  "~:name": "Simple flashcard",
  "~:content": "# << Front >>\n---\n<< Back >>",
  "~:pos": "s",
  "~:fields": {
    "~:name": {
      "~:id": "~:name",
      "~:name": "Front",
      "~:pos": "a"
    },
    "~:Ysrde7Lj": {
      "~:id": "~:Ysrde7Lj",
      "~:name": "Back",
      "~:pos": "m",
      "~:options": {
        "~:multi-line?": true
      }
    }
  }
}

List all templates

Parameters

:bookmark optional
string - A cursor for use in pagination. Returned from a previous list request that has additional documents.

Example request

# Without a bookmark
GET https://app.mochi.cards/api/templates/

# With a bookmark
GET https://app.mochi.cards/api/templates?bookmark=somebookmarkgoeshere

Returns

A list of documents containing a bookmark.

Example response

{
  "bookmark": "g1AAAABAeJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYpzVBn4JgaaVZiC5Dlg8igyWQAxwRHd",
  "docs": [
    {
      "id": "YDELNZSu",
      "name": "Simple flashcard",
      "content": "# << Front >>\n---\n<< Back >>",
      "pos": "s",
      "fields": {
        "name": {
          "id": "name",
          "name": "Front",
          "pos": "a"
        },
        "Ysrde7Lj": {
          "id": "Ysrde7Lj",
          "name": "Back",
          "pos": "m",
          "options": {
            "multi-line?": true
          }
        }
      }
    },
    ...
  ]
}

{
  "~:bookmark": "g1AAAABAeJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYpzVBn4JgaaVZiC5Dlg8igyWQAxwRHd",
  "~:docs": [
    {
      "~:id": "~:YDELNZSu",
      "~:name": "Simple flashcard",
      "~:content": "# << Front >>\n---\n<< Back >>",
      "~:pos": "s",
      "~:fields": {
        "~:name": {
          "~:id": "~:name",
          "~:name": "Front",
          "~:pos": "a"
        },
        "~:Ysrde7Lj": {
          "~:id": "~:Ysrde7Lj",
          "~:name": "Back",
          "~:pos": "m",
          "~:options": {
            "~:multi-line?": true
          }
        }
      }
    },
    ...
  ]
}

Due

You can query for cards that are due on a specified date.

Endpoints:

GET  /due           -- List cards due on some date
GET  /due/:deck-id  -- List cards due on some date for a given deck

Get all due cards

POST https://app.mochi.cards/api/templates/

Parameters

date optional
timestamp - The date that the returned cards are due. If omitted it will use today's date. Timestamps should be ISO 8601 format, matching javascript's Date#toJSON method.

Example request

GET https://app.mochi.cards/api/due/
Accept: application/json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

GET https://app.mochi.cards/api/due/
Accept: application/transit+json
Authorization: Basic NDZiYjA4YTY5ODAzNmFiMjk3MjU4ZWFlOg==

Returns

Returns a list of cards that are due on the given date.

Example response

{
  "cards": [
    {
      "content": "Hello, world!",
      "name": "Hello, world!",
      "deck-id": "gT59NKG0",
      "attachments": { ... },
      "pos": "Q",
      "id": "MtYuPqpQ",
      "reviews": [
        {
          "date": {
            "date": "2025-12-12T00:00:00.000Z"
          },
          "due": {
            "date": "2025-12-12T00:00:00.000Z"
          },
          "remembered?": true
        }
      ],
      "created-at": {
        "date": "2025-12-08T06:58:38.724Z"
      },
      "new?": false
    }
  ]
}

{
  "~:cards": [
    {
      "~:content": "Hello, world!",
      "~:name": "Hello, world!",
      "~:deck-id": "~:gT59NKG0",
      "~:attachments": { ... },
      "~:pos": "Q",
      "~:id": "~:MtYuPqpQ",
      "~:reviews": [
        {
          "~:date": "~t1765497600000",
          "~:due": "~t1765497600000",
          "~:remembered?": true
        }
      ],
      "~:created-at": {
        "~#dt": 1765177118724
      },
      "~:new?": false
    }
  ]
}

Mochi

Flashcards & notes.

An app to help you learn and remember things.

API Reference

Authentication

Pagination

Errors

Rate limits

Concurrency limiter

Cards

Create a card

Parameters

content required

deck-id required

template-id optional

archived? optional

review-reverse? optional

pos optional

manual-tags optional

fields optional

Returns

Retrieve a card

Parameters

Returns

List cards

Parameters

Returns

Update a card

Parameters

Delete a card

Parameters

Add an attachment

Parameters

Delete an attachment

Parameters

Decks

Create a deck

Parameters

Returns

Retrieve a deck

Parameters

Returns

List all decks

Parameters

Returns

Update a deck

Parameters

Returns

Delete a deck

Parameters

Returns

Templates

Create a template

Parameters

Returns

Retrieve a template

Parameters

Returns

List all templates

Parameters

Returns

Due

Get all due cards

Parameters

Returns

`content` required

`deck-id` required

`template-id` optional

`archived?` optional

`review-reverse?` optional

`pos` optional

`manual-tags` optional

`fields` optional