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.

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

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

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 checklist was updated the last time (includes updates to tasks, but excludes updates to comments). For XML requests the timestamp is formatted according to ISO 8601. For JSON requests the date is formatted like 2005/02/01 15:15:10 +0000 (and can be parsed by javascript's Date class)

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

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

deleted

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

tasks

[JSON] Javascript array of children task IDs

tags

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

tags_as_text

[JSON] Comma-separated list of tag names

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 (like 2005/02/01 15:15:10 +0000, can be passed to javascript Date object). May be empty string if the task was never updated.

created_at

[JSON] When the list item was created

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 (like 2005/02/01 15:15:10 +0000, can be passed to javascript Date object)

created_at

Timestamp of the note creation (same format as above)

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>