Open API

Checkvist provides Open API which can be used for integration with other tools. The API offers only limited functionality, though allows both read and write operations. If you have questions regarding OpenAPI, feel free to join Checkvist OpenAPI group.

The searchable OpenAPI documentation is available (generated from /openapi.yaml)

Checkvist API uses REST principles for obtaining and updating data. Most read operations can return either XML or JSON response.

To emulate HTTP request methods like PUT or DELETE, you can use POST method and pass additional parameter _method with the required method name.

For XML response, the main part of the URL shall end with .xml suffix. For example:

https://checkvist.com/checklists/42.xml

For JSON response, the corresponding request should end with .json suffix.

Authentication (for non-public lists)

If your HTTP client can handle basic HTTP authentication, you can use it to identify the user working with Checkvist API. As a password, you can use either real password of the user, or user can use Remote API key obtained from user profile page.

As a better approach, you can use a token-based authentication. In this case, you should obtain a token first, and than pass it to all API calls either under token parameter, or in X-Client-Token HTTP header.

The token is valid only within a limited period of time (1 day). After that, within 90 days, the token can be refreshed with a special refresh_token call. Old token is deleted after that, and the new one returned.

To obtain the token, you should use the following API call:

Ahd here is the refresh_token call, which allows to get the new token without providing username/remote_key.

If user has 2-step verification enabled, API calls for obtaining the token should use Remote API key. Otherwise they should also contain 2-factor authentication code from the authentication app as the parameter token2fa.

User information

To obtain information about the current user, use the following API call:

Working with checklists

Get list of user checklists

  <checklists>
    <checklist1>
    <checklist2>
    <checklistN>
  </checklists>

Get checklist information

Create a checklist

Update a checklist

Delete a checklist

Working with list items

Get list items

<tasks>
    <task1>
    <task2>
    <taskN>
</tasks>

<tasks>
    <task>
    <task_parent>
    <task_parent_parent>
    <task_root_parent>
</tasks>

Create list items

<tasks>
    <task1>
    <task2>
    <taskN>
</tasks>

Update list item information

Add or remove tags

Tags are normally set with the task[tags] parameter of the create and update calls, which replace the whole set of tags on the list item. To remove a single tag without resending the rest use the dedicated call below.

<tasks>
    <task1>
    <task2>
    <taskN>
</tasks>

Close/open/invalidate

The following actions allow to change task status. You can

• change status of individual task (for leaf tasks only)
• for non-leaf tasks, status of its children will be changed. In Checkvist, the status of a non-leaf task is defined as a cumulative status of its children.

Available status change actions are

• close
• invalidate (in Checkvist UI, such tasks are marked with italics)
• reopen

These actions are presented in the final part of action URL below, like close.xml or invalidate.json. The performed action corresponds to the action name.

<tasks>
    <changed_task>
    <child1>
    <child2>
    <childN>
</tasks>

Set repeating task information

Delete list item

Working with notes

Get task notes

Create a note for a task

Update a note

Delete a note

Timestamp format

All timestamp fields below (updated_at, created_at) follow the same conventions:

• In XML responses, timestamps are formatted according to ISO 8601 (e.g. 2009-05-16T11:20:31Z).
• In JSON responses, timestamps are formatted as YYYY/MM/DD HH:MM:SS +0000 in UTC (e.g. 2005/02/01 15:15:10 +0000), which is parseable by the JavaScript Date constructor.

updated_at and created_at on a task are JSON-only — they are omitted from XML responses. A JSON updated_at may be the empty string when the item has never been updated.

Checklist representation

JSON and XML representations of a checklist have the following fields:

id

 

name

 

public (boolean)

true for checklist which can be accessed in read-only mode by anyone. Access to such checklists doesn't require authentication.

role

1-author, 2-writer, 3-reader

updated_at

Timestamp when the checklist was last updated (includes updates to tasks, but excludes updates to comments). See Timestamp format.

tags

[JSON] Javascript hash from tag name => isPrivate status of the tag

tags_as_text

[JSON] Comma-separated list of tag names

task_count

total number of leaf tasks

task_completed

number of completed leaf tasks

read_only

true if user access is read only in this list

archived

true if user archived this this (user-visible setting)

Checklist XML example

  <checklist>
    <id>1</id>
    <name>EAP checklist</name>
    <public>false</public>
    <role>1</role>
    <updated_at>2009-05-16T11:20:31Z</updated_at>
    <task_count>3</task_count>
    <task_completed>1</task_completed>
    <read_only>true</read_only>
  </checklist>

Task representation in output

id

 

content

Task content

status

0-open, 1-closed, 2-invalidated

checklist_id

Containing checklist ID

parent_id

Parent task ID. Empty for root-level tasks (or 0 in case of JSON output)

comments_count

Number of notes for this task

position

1 - based position of the task under its parent

priority

[JSON] Optional task priority, 1..9

deleted

Attribute is present only after task deletion (and has value true). In other cases information about deleted tasks is not included to results.

assignee_ids

[JSON] Javascript array of IDs of assignees of the task

tasks

[JSON] Javascript array of children task IDs

tags

[JSON] Javascript hash from tag name => isPrivate status of the tag. When modifying a task, accepts both hash and comma-separated string of tag names.

tags_as_text

[JSON] Comma-separated list of tag names. Can also be used when modifying a task.

update_line

[JSON] Information about last change in the task (text string like 'updated by kir')

updated_at

[JSON] Timestamp of the last change in the task. See Timestamp format.

created_at

[JSON] When the list item was created. See Timestamp format.

notes

When with_notes parameter is set to "true", this field contains a list of notes added to this task. The list of fields for each note is described below. For XML, there is a node <notes> with subnodes <node>. For JSON, property nodes refers to Javascript array of note objects.

Task XML example

  <task>
      <content>Root task</content>
      <id>3</id>
      <checklist_id>1</checklist_id>
      <comments_count>0</comments_count>
      <parent_id nil="true"></parent_id>
      <position>3</position>
      <status>0</status>
      <notes type="array"/>
  </task>

Note representation

id

 

comment

Note text

task_id

Containing task ID

user_id

ID of user who added this note

username

username of a user who added this note

updated_at

Timestamp of the last change of the note. See Timestamp format.

created_at

Timestamp of the note creation. See Timestamp format.

Note XML example

<note type="Comment">
  <comment>some note1</comment>
  <created_at>2009-06-12T19:50:00Z</created_at>
  <id>53</id>
  <task_id>4</task_id>
  <updated_at>2009-06-12T19:50:00Z</updated_at>
  <user_id>123</user_id>
  <username>kir</username>
</note>