The Ultralist.io API

Welcome to the Ultralist API! You can use our API to fully customize your workflow.

The API is simple and REST-based, so any http client will work just fine.

Authentication

Test your authorization using the following:

curl https://api.ultralist.io/api/v1/user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api key id>"

Make sure to replace api key id with your API key.

In order to authenticate with Ultralist’s API, you’ll need to create a new API key. For Ultralist, API keys are json web tokens that are passed in the header of your http requests.

To create a new API key, go to your profile page.
Find the Api keys section and click the New API key button.
Copy the corresponding key to your clipboard.

Todo Lists

Retrieve todo lists

Endpoint

To retrieve todo lists for the user who owns the API key:

GET https://api.ultralist.io/api/v1/todo_lists

If you are an account admin, you can also retrieve todo lists for any user on your account:

GET https://api.ultralist.io/api/v1/users/<user_uuid>/todo_lists

Parameters

None.

Example

curl https://api.ultralist.io/api/v1/todo_lists \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api key id>"

Response

{
	"todolists": [
    {
      "name": "My first list",
      "uuid": "3273cd0c-db07-4dfd-804e-19ade2b84254",
      "user_id": "9fafff06-111f-4634-a74a-a11e4c3fc27a",
      "created_at": "2020-06-02T10:57:51Z",
      "updated_at": "2020-06-02T10:57:51Z",
      "todo_items_attributes": [
        {
          "uuid": "aa261516-bfbe-4490-8796-f511a19785cb",
          "position": null,
          "subject": "Chat with @bob",
          "due": "2020-05-01",
          "completed": false,
          "completedDate": null,
          "isPriority": true,
          "archived": false,
          "projects": null,
          "contexts": null,
          "createdAt": "2020-06-02T10:57:51.000Z",
          "notes": [
            "Bob is a great guy."
          ]
        },
        {
          "uuid": "600a5637-e9ed-4bd1-a27a-5993e5394d1a",
          "position": null,
          "subject": "Push the build to the jenkins server",
          "due": "2020-05-03",
          "completed": false,
          "completedDate": null,
          "isPriority": false,
          "archived": false,
          "projects": null,
          "contexts": null,
          "createdAt": "2020-06-02T10:57:51.000Z",
          "notes": []
        }
      ]
    }
	]
}

Create a todo list

Endpoint

To create a todo list for the user who owns the API key:

POST https://api.ultralist.io/api/v1/todo_lists

If you are an account admin, you can also create a todo list for any user on your account:

POST https://api.ultralist.io/api/v1/users/<user_uuid>/todo_lists

Parameters

Parameter	Description
uuid	A unique UUID for the todo list.
name	The todo list name.
todo_items_attributes	An array of todo items.

Example

curl -X POST https://api.ultralist.io/api/v1/todo_lists \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api key id>" \
  -d @todolist.json

todolist.json

{
  "todolist": {
    "name": "My first list",
    "uuid": "3273cd0c-db07-4dfd-804e-19ade2b84254",
    "todo_items_attributes": [
      {
        "uuid": "aa261516-bfbe-4490-8796-f511a19785cb",
        "subject": "Chat with @bob",
        "due": "2020-05-01",
        "completed": false,
        "completedDate": null,
        "isPriority": true,
        "archived": false,
        "notes": ["Bob is a great guy."]
      },
      {
        "uuid": "600a5637-e9ed-4bd1-a27a-5993e5394d1a",
        "subject": "Push the build to the jenkins server",
        "due": "2020-05-03",
        "completed": false,
        "completedDate": null,
        "isPriority": false,
        "archived": false,
        "notes": []
      }
    ]
  }
}

Response:

{
  "name": "My first list",
  "uuid": "3273cd0c-db07-4dfd-804e-19ade2b84254",
  "user_id": "9fafff06-111f-4634-a74a-a11e4c3fc27a",
  "created_at": "2020-06-02T10:57:51Z",
  "updated_at": "2020-06-02T10:57:51Z",
  "todo_items_attributes": [
    {
      "uuid": "aa261516-bfbe-4490-8796-f511a19785cb",
      "position": null,
      "subject": "Chat with @bob",
      "due": "2020-05-01",
      "completed": false,
      "completedDate": null,
      "isPriority": true,
      "archived": false,
      "projects": null,
      "contexts": null,
      "createdAt": "2020-06-02T10:57:51.000Z",
      "notes": [
        "Bob is a great guy."
      ]
    },
    {
      "uuid": "600a5637-e9ed-4bd1-a27a-5993e5394d1a",
      "position": null,
      "subject": "Push the build to the jenkins server",
      "due": "2020-05-03",
      "completed": false,
      "completedDate": null,
      "isPriority": false,
      "archived": false,
      "projects": null,
      "contexts": null,
      "createdAt": "2020-06-02T10:57:51.000Z",
      "notes": []
    }
  ]
}

Todo items

Get todo items for a user

Endpoint

To retrieve todo items for the user who owns the API key:

GET https://api.ultralist.io/api/v1/todo_items

If you are an account admin, you can also retrieve todo lists for any user on your account:

GET https://api.ultralist.io/api/v1/users/<user_uuid>/todo_items

Example

curl -X GET https://api.ultralist.io/api/v1/todo_items \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api key id>"

Response

{
  "todo_items": [
    {
      "id": 3,
      "uuid": "da145597-74ef-47b4-9e3c-880a0d99c03f",
      "position": null,
      "subject": "Seamlessly sync your lists with our powerful CLI tool.",
      "due": null,
      "completed": true,
      "completedDate": "2020-06-17",
      "isPriority": true,
      "archived": false,
      "projects": [],
      "contexts": [],
      "createdAt": "2020-06-10T09:58:50.000Z",
      "notes": [
        "[Head to our Github page](https://github.com/ultralist/ultralist) for details on installing the CLI tool."
      ]
    },
    {
      "id": 4,
      "uuid": "e4bfe43a-31da-477d-bbb8-a4f49e71cbed",
      "position": null,
      "subject": "You can add notes to any todo item.  Try clicking the notes icon on the right!",
      "due": null,
      "completed": false,
      "completedDate": null,
      "isPriority": false,
      "archived": false,
      "projects": null,
      "contexts": null,
      "createdAt": "2020-06-10T09:58:50.000Z",
      "notes": [
        "Markdown is supported in notes, so you can *add emphasis* and links."
      ]
    },
	]
}

Get todo items for a user

Accounts

Get your account info

This will return all of the information about your account, including users attached to your account.

Endpoint

GET https://api.ultralist.io/api/v1/account

Query parameters

None.

Example

curl https://api.ultralist.io/api/v1/account \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api key id>"

Response

{
  "invite_code": "eyJ0eXAiOiJGV1QiLCJhbGciO2JIUzI1NiJ9...",
  "cancelled_at": null,
  "free_trial_ends_at": "2020-06-24T09:58:50.000Z",
  "status": "trialing",
  "name": "gammons@gmail.com",
  "errors": "[]",
  "users": [
    {
      "email": "gammons@gmail.com",
      "name": "gammons@gmail.com",
      "uuid": "8f6de218-b1c0-4f49-8267-6e4505858e2c",
      "errors": "[]",
      "image_url": "https://lh3.googleusercontent.com/a-/AOh14GiFSeJmf9qVsk_efnvYuR4HCJrhFqVnR8jsiPSy56E=s50",
      "last_login_at": "2020-06-16T11:41:27.000Z"
    }
  ]
}