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

URL Method HTTP parameters Response
/auth/login.json get/post
  • username - User login (email)
  • remote_key - User's remote API Key from profile page (or user password)
  • callback - Optional javascript callback function (will get token as a parameter)
Returns quoted token string in the body, unless callback parameter is passed. If authentication failed, will return HTTP status 401 Unauthorized.

User information

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

URL Method HTTP parameters Response
/auth/curr_user.(json|xml) get Returns currently logged-in user JSON/XML data in the body.

Working with checklists

Get list of user checklists

URL Method HTTP parameters Response
/checklists.(json|xml) get
  • archived - If set to true, returns archived lists
  • order - id:asc or id:desc or updated_at:asc - allows to override the sorting
  • skip_stats - If true, the request will be executed faster, at the price of missing stats about number of users/tasks in each list
For JSON call, javascript array of JSON representations for user checklists. Sorting is the same as in user's Checkvist UI (default - recently updated checklists first). See checklist data fields.
For XML request:
  <checklists>
    <checklist1>
    <checklist2>
    <checklistN>
  </checklists>

Get checklist information

URL Method Response
/checklists/checklist_id.(json|xml) get JSON/XML representation for the checklist with given ID. See checklist data fields.

Create a checklist

URL Method HTTP parameters Response
/checklists.(json|xml) post
  • checklist[name] - checklist name
  • checklist[public] - 0|1 (optional)
JSON/XML representation for the created checklist. See checklist data fields.

Update a checklist

URL Method HTTP parameters Response
/checklists/checklist_id.(json|xml) put
  • checklist[name] - checklist name
  • checklist[public] - 0|1 (optional)
Update checklist name/public status. Returns JSON/XML representation for the updated checklist. See checklist data fields.

Delete a checklist

URL Method Response
/checklists/checklist_id.(json|xml) delete Delete the checklist (with all its data). Returns JSON/XML representation for the deleted checklist. See checklist data fields. Actually, at the moment of the call, the list is marked for deletion only. Actual data deletion occurs later, once a day.

Working with list items

Get list items

URL Method HTTP parameters Response
/checklists/checklist_id/tasks.(json|xml) get
  • with_notes - If set, the result will contain information about notes added to the tasks
  • order - id:asc or id:desc or updated_at:asc - allows to override the sorting
List of representations for the list items of checklist with given ID. List items are sorted by parent_id, position. For JSON, returns a javascript array of items. For XML, returns a structure like below:
<tasks>
    <task1>
    <task2>
    <taskN>
</tasks>
/checklists/checklist_id/tasks/task_id.(json|xml) get
  • with_notes - If set, the result will contain information about notes added to the tasks
List of XML/JSON representations for the given task and its parents. Original list item is the first, and than go parents, one after another, till the root parent task.
<tasks>
    <task>
    <task_parent>
    <task_parent_parent>
    <task_root_parent>
</tasks>

Create list items

URL Method HTTP parameters Response
/checklists/checklist_id/tasks.(json|xml) post
  • task[content] - task text
  • task[parent_id] - id of the parent task (optional)
  • task[tags] - comma-separated list of tags to set on the task
  • task[due_date] - due for the task, in Checkvist's smart syntax format'
  • task[position] - 1-based position of the task (omit to add to the end of the list)
  • task[status] - task status (optional)
JSON/XML representation for the created task.
/checklists/checklist_id/import.(json|xml) post
  • add_files[1],add_files[2] - can contain file attachment data for PRO users
  • checklist_id - May have format 'tag:tagname' in this case the first user list tagged with tagname will be chosen for the operation
  • import_content - list items in the same format, as supported by Checkvist's import function.
  • import_content_note - If present, content of the field becomes the note for the first created list item
  • parent_id - Optional ID of the parent list item
  • parse_tasks - If present, recognize ^due and #tags syntax in imported list items
  • position - Optional 1-based position for the first imported list item
  • replace_existing - danger - replace the whole content of the list with imported content
  • separate_with_empty_line - if set to 'singleItem', all text is imported as a single list item. If set to any other value, import will separate the list items with an empty line. By default (not set), each line is treated as a separate list item
  • status - Optional status for the first imported task; can be 0,1,2
Created list items, organized to hierarchy according to input data.
List items are added to the beginning of the target list.
For JSON, returns a javascript array of tasks. For XML, returns a structure like below:
<tasks>
    <task1>
    <task2>
    <taskN>
</tasks>

Update list item information

URL Method HTTP parameters Response
/checklists/checklist_id/tasks/task_id.(json|xml) put
  • task[content] - new task text
  • task[parent_id] - new parent_id task
  • task[tags] - comma-separated list of tags to set on the task
  • task[due_date] - due for the task, in Checkvist's smart syntax format'
  • task[position] - 1-based position of the task
  • parse - If true, recognize ^due and #tags syntax in the updated item
Updates the task information and returns JSON/XML representation for it. This method won't change task status.

Close/open/invalidate

The following actions allow to change task status. You can

Available status change actions are

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.

URL Method Response
/checklists/checklist_id/tasks/task_id/action.(json|xml) post Updates the task status and returns representation for it and for its children. XML sample:
<tasks>
    <changed_task>
    <child1>
    <child2>
    <childN>
</tasks>
For JSON, javascript array of tasks is returned. If there are no children, only one element is returned under the tasks node and only one element in resulting JSON array.

Set repeating task information

URL Method HTTP parameters Response
/checklists/checklist_id/tasks/task_id/repeat.(json|xml) post
  • repeat[period] - daily|weekly|monthly|yearly
  • repeat[period_count] - it is '5' in repeat every 5 weeks (optional, default 1)
  • repeat[start_date] - the start date for the first repeating due
  • repeat[end_date] - the end date for the repeating due (optional)
Sets the repeating task information and returns the updated task.

Delete list item

URL Method Response
/checklists/checklist_id/tasks/task_id.(json|xml) delete Deletes the list item including its children and returns the deleted list item representation.

Working with notes

Get task notes

URL Method Response
/checklists/checklist_id/tasks/task_id/comments.(json|xml) GET Get list of existing notes for the task with id task_id. Data format is similar to the case, when notes are included into the task data.

Create a note for a task

URL Method HTTP parameters Response
/checklists/checklist_id/tasks/task_id/comments.(json|xml) POST
  • comment[comment] - comment text
Creates a new note for the task with id task_id and returns created note

Update a note

URL Method HTTP parameters Response
/checklists/checklist_id/tasks/task_id/comments/note_id.(json|xml) PUT
  • comment[comment] - comment text
Updates note text for a note with id note_id and returns created note

Delete a note

URL Method Response
/checklists/checklist_id/tasks/task_id/comments/note_id.(json|xml) DELETE Delete a note with id note_id and returns deleted 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.
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>

FAQ

Some frequently asked questions - to save
your and our time.

Reference

More detailed description of Checkvist
features.

Open API

Integrate Checkvist with other tools that can
connect to the web.

Google+ RSS