Overview

The Checkmarkable API is available in a beta form, anchored at /api/v1. It is RESTful and easy to use and play with.

Requests

In general all REST collections and resources are available using the following patterns:

GET /api/v1/data/{COLLECTION}
GET /api/v1/data/{COLLECTION}/{ID}
GET /api/v1/data/{COLLECTION}/{ID}/{SUB-COLLECTION}

Some collections and resources also accept PUT, POST and DELETE requests. These resources are documented below.

Responses

All API requests will return JSON. Resources will return an object hash containing pointers to other resources. Collections will return a JSON hash with the following structure:

{
    total: 3,
    offset: 0,
    limit: 10,
    data: [ {…}, {…}, {…} ]
}

Note: As of this time, most collections are arbitrarily limited to the most recent 10 items. There is no pagination mechanism yet.

Adding or Updating Content

To update a resource, make a PUT request to the resource's URL. This will update just the properties that are in the JSON request.

Resources can be deleted with the DELETE method, provided you have the appropriate permissions.

Activity feeds

Each resource has an activity feed available as JSON or ATOM. The activity streams can be found at:

/api/v1/data/{COLLECTION}/{ID}/activity
/api/v1/data/{COLLECTION}/{ID}/activity.atom

You may use the since parameter to pass a timestamp. This would request only stream entries at or after that time.

API Resources and Collections

Authorization

Checkmarkable uses an access token or session auth to validate API requests. This token is per-user and will be reset when the user changes their password.

To use your access token, specify an Authorization header in your HTTP requests set to:

Authorization: auth_token YOUR-AUTH-TOKEN

Example usage

curl -H 'Authorization: auth_token YOUR-AUTH-TOKEN' https://checkmarkable.com/api/v1/data/me

Users

/data/me

{

    "last_login": {
        "at": "2012-03-08T19:19:49Z"
    },
    "name": "Luke Closs",
    "invited_by_id": null,
    "image": "https://secure.gravatar.com/avatar/2619aab19b8c079875cfe40e805478?s=20&d=identicon",
    "url_path": "/u/6",
    "created": {
        "at": "2012-03-07T23:52:03Z"
    },
    "email": "lukec@primeradiant.com",
    "id": 6,
    "is_staff": false,
    "how_signed_up": "Organic/purple"

}

There is an admin-only API to view other users. As inter-user behaviour is opened up, we will expand the /data/users API.

/data/password

This API is used to change a user's password. PUT JSON to this URL with old and new fields. If the old password is valid and the new password is valid, the password will be changed. If there was an error, the response code 400 will be returned along with an error message.

Teams

The teams API returns the list of your teams. Individual teams can be fetched by ID or URL name.

/api/v1/data/teams
      

A teams resource also has sub-collections for checklists and conversations.

Creating a team

You can create a team by POSTing a JSON blob to /data/teams a JSON hash containing a name field and optional description field.

Command line example:

curl -X POST -H 'Authorization: auth_token YOUR-AUTH-TOKEN' https://checkmarkable.com/api/v1/data/teams -H 'Content-Type: application/json' --data-binary '{"name":"Test team from API"}'

Updating a team

You may update a team by PUTting a JSON hash to the URL for that team resource. (eg: /data/teams/{TEAM_ID})

PUT /api/v1/data/teams/{ID or url_name}

The PUT request body should be a JSON hash, that may contain the following hash keys:

  • description
  • name
  • ws_fireworks

Checklists

Embedding a Checklist

You can embed a checklist into another website using our embed widget. This feature currently only works for personal checklists with a non-private licence.

Navigate to your checklist and click the "Sharing" link in the sidebar. Follow the instructions to embed the Checklist into your web page.

REST API

The checklists API returns the list of all your checklists.

/api/v1/data/checklists
     

Individual checklists can be fetched by ID.

/api/v1/data/checklists{ID}

You can also fetch the checklists that are on a team or community using a subcollection:

/api/v1/data/teams/{ID}/checklists
/api/v1/data/communities/{ID}/checklists

Creating a checklist

You can create a checklist by POSTing a JSON hash to /data/checklists containing:

  • description
  • license
  • name
  • notification_email
  • owner_team
  • owner_user

Command line example:

curl -X POST -H 'Authorization: auth_token YOUR-AUTH-TOKEN' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"Test checklist from API", "owner_user":XXX}' \
https://checkmarkable.com/api/v1/data/checklists

Creating checklist steps

Once you have a checklist, you can create new checklist steps by POSTing a JSON hash to /data/checklist_steps containing:

  • checklist_id
  • description
  • name
  • sort_order

Command line example:

curl -X POST -H 'Authorization: auth_token YOUR-AUTH-TOKEN' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"Step one", "checklist_id":XXX_YOUR_ID_HERE, "sort_order":1}' \
https://checkmarkable.com/api/v1/data/checklist_steps

Updating a checklist or a checklist step

You can update a checklist or checklist step by PUTting a JSON hash to /data/checklists/{CHECKLIST_ID} or /data/checklist_steps/{STEP_ID}. The hash may contain the same keys as used to create the resource.

Command line example:

curl -X PUT -H 'Authorization: auth_token YOUR-AUTH-TOKEN' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"The FIRST step"}' \
https://checkmarkable.com/api/v1/data/checklist_steps/XXX_YOUR_STEP_ID

Worksheets

The worksheets API returns the list of all of your worksheets. Individual worksheets can be fetched by ID.

/api/v1/data/worksheets
     

You can also fetch the worksheets for a particular checklist using a sub-collection:

/api/v1/data/checklists/{ID}/worksheets

Creating a worksheet from a checklist

You can create a worksheet by POSTing a JSON hash to /data/worksheets containing:

  • checklist_id
  • description
  • name
  • notification_email
  • url

Command line example:

curl -X POST -H 'Authorization: auth_token YOUR-AUTH-TOKEN' \
    -H 'Content-Type: application/json' \
    --data-binary '{"name":"Test worksheet from API", "checklist_id":"YOUR_CHECKLIST_ID_GOES_HERE"}' \
    https://checkmarkable.com/api/v1/data/worksheets

Note: you need to put a valid checklist_id into the above command.

Worksheet Steps

Worksheet steps are listed as part of the Worksheet resource, but can be modified using a PUT API:

PUT /api/v1/data/worksheet_steps/{ID}

The PUT request body should be a JSON hash, that may contain the following hash keys:

  • checked_off
  • description
  • name
  • notes
  • skip_notes
  • skipped
  • wrong
  • wrong_notes

Conversations

The conversations API returns conversation resources. At this time, there is no way to retrieve a collection of all conversations. However, you may retrieve conversations for a particular team or community through a sub-collection request.

/api/v1/data/conversations/{ID}
/api/v1/data/teams/{ID}/conversations
/api/v1/data/communities/{ID}/conversations

Conversation Entries

Conversations are composed of conversation entries. You may fetch the conversation entries for a particular conversation using this API call:

/api/v1/data/conversations/{ID}/conversation_entries

You may also fetch specific conversation entries:

/api/v1/data/conversation_entries/{ID}
×