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 ask in Checkvist OpenAPI group.

Checkvist API is based on HTTP protocol and 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:

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

For JSON response, the corresponding request should end with .json suffix. You can pass the resulting JSON object to your javascript function by passing the name of the function via callback parameter:

http://checkvist.com/checklists.json?callback=processor_for_my_checklists

Using JSON and callbacks, you can place the Checkvist API request inside a <script> tag, and operate on the results with a function elsewhere in the JavaScript code on the page.

Authentication (for non-public checklists)

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.

Alternatively, you can use token-based authentication. In this case, you should obtain a token first, and than pass it to all API call under token name. The token is valid only within limited period of time (30 minutes). To obtain the token, you should use the following API call:

Work with checklists

Create a checklist

Get list of active checklists

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

Get checklist information

Work with tasks

Get tasks

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

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

Create tasks

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

Update task 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>

Delete task

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)

task_count

total number of leaf tasks

task_completed

number of completed leaf tasks

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>
  </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

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.

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

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>
</note>