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_secret_key_goes_here:
# The colon prevents curl from asking for a password.

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." } }

Cards

Endpoints:

GET  /cards
POST /cards
GET  /cards/id
POST /cards/id
DELETE /cards/id

Create a card

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".
  • 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.
  • attachments optional
    array - An array of attachments to include with the card. Attachments can be accessed on the card via the markdown syntax: ![alt text](@media/foo.jpg). Each item in the array is a map with the following structure:
    • file-name required
      string - The file name (before the extension) must match the regex /[0-9a-zA-Z]{8,16}/. E.g. "j94fuC0R.jpg"
    • content-type required
      string - A MIME type representing the attachment.
    • data required
      string - The base64 encoded representation of the attachment data.

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",
  "attachments": [
    {
      "file-name": "foobar03.png",
      "content-type": "image/png",
      "data": "iVBORw0KGgoAAAANSUhEUgAAACgAAAAkCAIAAAB0Xu9BAAAABGdBTUEAALGPC/xhBQAAAuNJREFUWEetmD1WHDEQhDdxRMYlnBFyBIccgdQhKVcgJeQMpE5JSTd2uqnvIGpVUqmm9TPrffD0eLMzUn+qVnXPwiFd/PP6eLh47v7EaazbmxsOxjhTT88z9hV7GoNF1cUCvN7TTPv/gf/+uQPm862MWTL6fff4HfDx4S79/oVAlAUwqOmYR0rnazuFnhfOy/ErMKkcBFOr1vOjUi2MFn4nuMil6OPh5eGANLhW3y6u3aH7ijEDCxgCvzFmimvc95TekZLyMSeJC68Bkw0kqUy1K87FlpGZqsGFCyqEtQNDdFUtFctTiuhnPKNysid/WFEFLE2O102XJdEE+8IgeuGsjeJyGHm/xHvQ3JtKVsGGp85g9rK6xMHtvHO9+WACYjk5vkVM6XQ6OZubCJvTfPicYPeHO2AKFl5NuF5UK1VDUbeLxh2BcRGKTQE3irHm3+vPj6cfCod50Eqv5QxtwBQUGhZhbrGVuRia1B4MNp6edwBxld2sl1splfHCwfsvCZfrCQyWmX10djjOlWJSSy3VQlS6LmfrgNvaieRWx1LZ6s9co+P0DLsy3OdLU3lWRclQsVcHJBcUQ0k9/WVVrmpRzYQzpgAdQcAXxZzUnFX3proannrYH+Vq6KkLi+UkarH09mC8YPr2RMWOlEqFkQClsykGEv7CqCUbXcG8+SaGvJ4a8d4y6epND+pEhxoN0vWUu5ntXlFb5/JT7JfJJqoTdy9u9qc7ax3xJRHqJLADWEl23cFWl4K9fvoaCJ2BHpmJ3s3z+O0U/DmzdMjB9alWZtg4e3yxzPa7lUR7nkvxLHO9+tvJX3mtSDpwX8GajB283I8R8a7D2MhUZr1iNWdny256yYLd52DwRYBtRMvE7rsmtxIUE+zLKQCDO4jlxB6CZ8M17GhuY+XTE8vNhQiIiSE82ZsGwk1pht4ZSpT0YVpon6EvevOXXH8JxVR78QzNuamupW/7UB7wO/+7sG5V4ekXb4cL5Lyv+4IAAAAASUVORK5CYII="
    }
  ]
}

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",
  "~:attachments": [
    {
      "~:file-name": "foobar03.png",
      "~:content-type": "image/png",
      "~:data": "iVBORw0KGgoAAAANSUhEUgAAACgAAAAkCAIAAAB0Xu9BAAAABGdBTUEAALGPC/xhBQAAAuNJREFUWEetmD1WHDEQhDdxRMYlnBFyBIccgdQhKVcgJeQMpE5JSTd2uqnvIGpVUqmm9TPrffD0eLMzUn+qVnXPwiFd/PP6eLh47v7EaazbmxsOxjhTT88z9hV7GoNF1cUCvN7TTPv/gf/+uQPm862MWTL6fff4HfDx4S79/oVAlAUwqOmYR0rnazuFnhfOy/ErMKkcBFOr1vOjUi2MFn4nuMil6OPh5eGANLhW3y6u3aH7ijEDCxgCvzFmimvc95TekZLyMSeJC68Bkw0kqUy1K87FlpGZqsGFCyqEtQNDdFUtFctTiuhnPKNysid/WFEFLE2O102XJdEE+8IgeuGsjeJyGHm/xHvQ3JtKVsGGp85g9rK6xMHtvHO9+WACYjk5vkVM6XQ6OZubCJvTfPicYPeHO2AKFl5NuF5UK1VDUbeLxh2BcRGKTQE3irHm3+vPj6cfCod50Eqv5QxtwBQUGhZhbrGVuRia1B4MNp6edwBxld2sl1splfHCwfsvCZfrCQyWmX10djjOlWJSSy3VQlS6LmfrgNvaieRWx1LZ6s9co+P0DLsy3OdLU3lWRclQsVcHJBcUQ0k9/WVVrmpRzYQzpgAdQcAXxZzUnFX3proannrYH+Vq6KkLi+UkarH09mC8YPr2RMWOlEqFkQClsykGEv7CqCUbXcG8+SaGvJ4a8d4y6epND+pEhxoN0vWUu5ntXlFb5/JT7JfJJqoTdy9u9qc7ax3xJRHqJLADWEl23cFWl4K9fvoaCJ2BHpmJ3s3z+O0U/DmzdMjB9alWZtg4e3yxzPa7lUR7nkvxLHO9+tvJX3mtSDpwX8GajB283I8R8a7D2MhUZr1iNWdny256yYLd52DwRYBtRMvE7rsmtxIUE+zLKQCDO4jlxB6CZ8M17GhuY+XTE8vNhQiIiSE82ZsGwk1pht4ZSpT0YVpon6EvevOXXH8JxVR78QzNuamupW/7UB7wO/+7sG5V4ekXb4cL5Lyv+4IAAAAASUVORK5CYII="
    }
  ]
}

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

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
Content-Type: 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

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

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.
  • 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".
  • 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.
  • attachments optional
    array - An array of attachments to include with the card. Attachments can be accessed on the card via the markdown syntax: ![alt text](@media/foo.jpg). Each item in the array is a map with the following structure:
    • file-name required
      string - The file name (before the extension) must match the regex /[0-9a-zA-Z]{8,16}/. E.g. "j94fuC0R.jpg"
    • content-type required
      string - A MIME type representing the attachment.
    • data required
      string - The base64 encoded representation of the attachment data.

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",
  "attachments": [
    {
      "file-name": "foobar03.png",
      "content-type": "image/png",
      "data": "iVBORw0KGgoAAAANSUhEUgAAACgAAAAkCAIAAAB0Xu9BAAAABGdBTUEAALGPC/xhBQAAAuNJREFUWEetmD1WHDEQhDdxRMYlnBFyBIccgdQhKVcgJeQMpE5JSTd2uqnvIGpVUqmm9TPrffD0eLMzUn+qVnXPwiFd/PP6eLh47v7EaazbmxsOxjhTT88z9hV7GoNF1cUCvN7TTPv/gf/+uQPm862MWTL6fff4HfDx4S79/oVAlAUwqOmYR0rnazuFnhfOy/ErMKkcBFOr1vOjUi2MFn4nuMil6OPh5eGANLhW3y6u3aH7ijEDCxgCvzFmimvc95TekZLyMSeJC68Bkw0kqUy1K87FlpGZqsGFCyqEtQNDdFUtFctTiuhnPKNysid/WFEFLE2O102XJdEE+8IgeuGsjeJyGHm/xHvQ3JtKVsGGp85g9rK6xMHtvHO9+WACYjk5vkVM6XQ6OZubCJvTfPicYPeHO2AKFl5NuF5UK1VDUbeLxh2BcRGKTQE3irHm3+vPj6cfCod50Eqv5QxtwBQUGhZhbrGVuRia1B4MNp6edwBxld2sl1splfHCwfsvCZfrCQyWmX10djjOlWJSSy3VQlS6LmfrgNvaieRWx1LZ6s9co+P0DLsy3OdLU3lWRclQsVcHJBcUQ0k9/WVVrmpRzYQzpgAdQcAXxZzUnFX3proannrYH+Vq6KkLi+UkarH09mC8YPr2RMWOlEqFkQClsykGEv7CqCUbXcG8+SaGvJ4a8d4y6epND+pEhxoN0vWUu5ntXlFb5/JT7JfJJqoTdy9u9qc7ax3xJRHqJLADWEl23cFWl4K9fvoaCJ2BHpmJ3s3z+O0U/DmzdMjB9alWZtg4e3yxzPa7lUR7nkvxLHO9+tvJX3mtSDpwX8GajB283I8R8a7D2MhUZr1iNWdny256yYLd52DwRYBtRMvE7rsmtxIUE+zLKQCDO4jlxB6CZ8M17GhuY+XTE8vNhQiIiSE82ZsGwk1pht4ZSpT0YVpon6EvevOXXH8JxVR78QzNuamupW/7UB7wO/+7sG5V4ekXb4cL5Lyv+4IAAAAASUVORK5CYII="
    }
  ]
}

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",
  "~:attachments": [
    {
      "~:file-name": "foobar03.png",
      "~:content-type": "image/png",
      "~:data": "iVBORw0KGgoAAAANSUhEUgAAACgAAAAkCAIAAAB0Xu9BAAAABGdBTUEAALGPC/xhBQAAAuNJREFUWEetmD1WHDEQhDdxRMYlnBFyBIccgdQhKVcgJeQMpE5JSTd2uqnvIGpVUqmm9TPrffD0eLMzUn+qVnXPwiFd/PP6eLh47v7EaazbmxsOxjhTT88z9hV7GoNF1cUCvN7TTPv/gf/+uQPm862MWTL6fff4HfDx4S79/oVAlAUwqOmYR0rnazuFnhfOy/ErMKkcBFOr1vOjUi2MFn4nuMil6OPh5eGANLhW3y6u3aH7ijEDCxgCvzFmimvc95TekZLyMSeJC68Bkw0kqUy1K87FlpGZqsGFCyqEtQNDdFUtFctTiuhnPKNysid/WFEFLE2O102XJdEE+8IgeuGsjeJyGHm/xHvQ3JtKVsGGp85g9rK6xMHtvHO9+WACYjk5vkVM6XQ6OZubCJvTfPicYPeHO2AKFl5NuF5UK1VDUbeLxh2BcRGKTQE3irHm3+vPj6cfCod50Eqv5QxtwBQUGhZhbrGVuRia1B4MNp6edwBxld2sl1splfHCwfsvCZfrCQyWmX10djjOlWJSSy3VQlS6LmfrgNvaieRWx1LZ6s9co+P0DLsy3OdLU3lWRclQsVcHJBcUQ0k9/WVVrmpRzYQzpgAdQcAXxZzUnFX3proannrYH+Vq6KkLi+UkarH09mC8YPr2RMWOlEqFkQClsykGEv7CqCUbXcG8+SaGvJ4a8d4y6epND+pEhxoN0vWUu5ntXlFb5/JT7JfJJqoTdy9u9qc7ax3xJRHqJLADWEl23cFWl4K9fvoaCJ2BHpmJ3s3z+O0U/DmzdMjB9alWZtg4e3yxzPa7lUR7nkvxLHO9+tvJX3mtSDpwX8GajB283I8R8a7D2MhUZr1iNWdny256yYLd52DwRYBtRMvE7rsmtxIUE+zLKQCDO4jlxB6CZ8M17GhuY+XTE8vNhQiIiSE82ZsGwk1pht4ZSpT0YVpon6EvevOXXH8JxVR78QzNuamupW/7UB7wO/+7sG5V4ekXb4cL5Lyv+4IAAAAASUVORK5CYII="
    }
  ]
}

Delete a card

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.

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)

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.

Create a deck

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.
  • 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

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
Content-Type: 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

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

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.
  • 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

WARNING: This action cannot be undone. For a "soft" deletion you can update a deck and set its "trashed?" property to the current time.

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.

Retrieve a template

Retrieves a template that already exists.

Parameters

No parameters.

Example request

GET https://app.mochi.cards/api/templates/btmZUXWM
Content-Type: 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
          }
        }
      }
    },
    ...
  ]
}