Cheddar

Lists Documentation

To interact with the tasks in a list, see the tasks documentation. It's also worth noting that lists do not support entities in their titles. Here are all of the methods for interacting with lists:

Show all lists
GET lists
Returns all of the authenticated user's lists (including archived lists).
Show a list
GET lists/:id
Returns a given list. Active tasks may be optionally included.
Update a list
PUT lists/:id
Updates a given list.
Create a list
POST lists
Creates a list.
Reorder lists
POST lists/reorder
Reorder the user's lists. (Not to be confused with reordering tasks inside a list.)

Show all lists

Returns all of the authenticated user's lists (including archived lists). This method requires authentication.

Note the "position" attribute of the list. You should display lists with this attribute in ascending order.

GET lists

Parameters

This method does not accept any parameters.

Example Request

$ curl -i "https://api.cheddarapp.com/v1/lists" \
  -H "Authorization: Bearer 637fe66c9cdd54f3b3c8457453c3ed95"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "active_completed_tasks_count": 0,
    "active_tasks_count": 9,
    "active_uncompleted_tasks_count": 10,
    "archived_at": null,
    "archived_completed_tasks_count": 0,
    "archived_tasks_count": 1,
    "archived_uncompleted_tasks_count": 1,
    "created_at": "2012-07-06T19:50:23Z",
    "id": 16608,
    "position": 1,
    "slug": "G70",
    "title": "List Mondaayyyy",
    "updated_at": "2013-05-13T05:37:42Z",
    "url": "https://api.cheddarapp.com/v1/lists/16608",
    "user": {
      "created_at": "2012-07-06T19:50:23Z",
      "first_name": null,
      "has_plus": false,
      "id": 9526,
      "last_name": null,
      "socket": {
        "api_key": "675f10a650f18b4eb0a8",
        "app_id": "15197",
        "auth_url": "https://api.cheddarapp.com/pusher/auth",
        "channel": "private-user-9526"
      },
      "updated_at": "2012-07-29T06:41:46Z",
      "url": "https://api.cheddarapp.com/v1/users/9526",
      "username": "demo"
    }
  },
  { … }
]

Show a list

Returns a given list. This method requires authentication.

GET lists/:id

Parameters

include_active_tasks
optional

Includes an array of task objects nested under the "tasks" key in root object. Defaults to false.

Example Values: true

Example Request

$ curl -i "https://api.cheddarapp.com/v1/lists/16608" \
  -H "Authorization: Bearer 637fe66c9cdd54f3b3c8457453c3ed95"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "active_completed_tasks_count": 0,
  "active_tasks_count": 9,
  "active_uncompleted_tasks_count": 10,
  "archived_at": null,
  "archived_completed_tasks_count": 0,
  "archived_tasks_count": 1,
  "archived_uncompleted_tasks_count": 1,
  "created_at": "2012-07-06T19:50:23Z",
  "id": 16608,
  "position": 1,
  "slug": "G70",
  "title": "List Mondaayyyy",
  "updated_at": "2013-05-13T05:37:42Z",
  "url": "https://api.cheddarapp.com/v1/lists/16608",
  "user": {
    "created_at": "2012-07-06T19:50:23Z",
    "first_name": null,
    "has_plus": false,
    "id": 9526,
    "last_name": null,
    "socket": {
      "api_key": "675f10a650f18b4eb0a8",
      "app_id": "15197",
      "auth_url": "https://api.cheddarapp.com/pusher/auth",
      "channel": "private-user-9526"
    },
    "updated_at": "2012-07-29T06:41:46Z",
    "url": "https://api.cheddarapp.com/v1/users/9526",
    "username": "demo"
  }
}

Update a list

Updates a given list. To archive a list, simply update it and set "list[archived_at]" to when it was archived. This method requires authentication.

PUT lists/:id

Parameters

You may only update some attributes using the following parameters:

list[title]
optional

The new title of the list. If you omit this parameter, the title will remain unchanged.

Example Values: "Updated Title"

list[archived_at]
optional

The time when the list was archived. If you set this to an empty string or null, it will unarchive the list. If this is set to a time, the list will be archived. Please do not set this to anything in the future. If you omit this parameter, the archived status will remain unchanged.

Example Values: null, "2012-07-02T18:50:53Z"

Example Request

$ curl -i "https://api.cheddarapp.com/v1/lists/16608" \
  -X PUT -d "list[title]=Updated%20Title" \
  -H "Authorization: Bearer 637fe66c9cdd54f3b3c8457453c3ed95"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "active_completed_tasks_count": 0,
  "active_tasks_count": 9,
  "active_uncompleted_tasks_count": 10,
  "archived_at": null,
  "archived_completed_tasks_count": 0,
  "archived_tasks_count": 1,
  "archived_uncompleted_tasks_count": 1,
  "created_at": "2012-07-06T19:50:23Z",
  "id": 16608,
  "position": 1,
  "slug": "G70",
  "title": "Updated Title",
  "updated_at": "2013-05-13T05:37:42Z",
  "url": "https://api.cheddarapp.com/v1/lists/16608",
  "user": {
    "created_at": "2012-07-06T19:50:23Z",
    "first_name": null,
    "has_plus": false,
    "id": 9526,
    "last_name": null,
    "socket": {
      "api_key": "675f10a650f18b4eb0a8",
      "app_id": "15197",
      "auth_url": "https://api.cheddarapp.com/pusher/auth",
      "channel": "private-user-9526"
    },
    "updated_at": "2012-07-29T06:41:46Z",
    "url": "https://api.cheddarapp.com/v1/users/9526",
    "username": "demo"
  }
}

Create a list

Creates a list. This method requires authentication.

POST lists

Parameters

list[title]
required

The title of the list.

Example Values: "Great TV Shows"

Example Request

$ curl -i "https://api.cheddarapp.com/v1/lists" \
  -X POST -d "list[title]=Great%20TV%20Shows" \
  -H "Authorization: Bearer 637fe66c9cdd54f3b3c8457453c3ed95"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "active_completed_tasks_count": 0,
  "active_tasks_count": 9,
  "active_uncompleted_tasks_count": 10,
  "archived_at": null,
  "archived_completed_tasks_count": 0,
  "archived_tasks_count": 1,
  "archived_uncompleted_tasks_count": 1,
  "created_at": "2012-07-06T19:50:23Z",
  "id": 16608,
  "position": 1,
  "slug": "G70",
  "title": "Great TV Shows",
  "updated_at": "2013-05-13T05:37:42Z",
  "url": "https://api.cheddarapp.com/v1/lists/16608",
  "user": {
    "created_at": "2012-07-06T19:50:23Z",
    "first_name": null,
    "has_plus": false,
    "id": 9526,
    "last_name": null,
    "socket": {
      "api_key": "675f10a650f18b4eb0a8",
      "app_id": "15197",
      "auth_url": "https://api.cheddarapp.com/pusher/auth",
      "channel": "private-user-9526"
    },
    "updated_at": "2012-07-29T06:41:46Z",
    "url": "https://api.cheddarapp.com/v1/users/9526",
    "username": "demo"
  }
}

Note: If the user does not have Cheddar Plus and tries to create more than two lists, the response will look like this:

HTTP/1.1 422
Content-Type: application/json; charset=utf-8

{
  "error": "plus_required",
  "error_description": "The user needs Cheddar Plus to create more than two lists."
}

You should send them to https://cheddarapp.com/account#plus to upgrade. If you are using the realtime API, you can listen for the user-update event. It will be triggered if their has_plus attribute changes.


Reorder lists

Reorder all of the user's lists. (Not to be confused with reordering tasks inside a list.) This method requires authentication.

POST lists/reorder

Parameters

list
required
All of the IDs of the user's lists in the new order. This can be form encoded parameters or a JSON array.

Example Values: list[]=23&list[]=19&list[]=193

Example Request

$ curl -i "https://api.cheddarapp.com/v1/lists/reorder" \
  -X POST -d "list[]=120408&list[]=120400&list[]=120401&list[]=120402&list[]=120403&list[]=120404&list[]=120405&list[]=120406&list[]=120407" \
  -H "Authorization: Bearer 637fe66c9cdd54f3b3c8457453c3ed95"

Example Response

HTTP/1.1 204 No Content