Skip to content
On this page

API

DANGER

The API is not stable, and may change at any time.

TaskRatchet has an API you can use to list, update, and create new tasks, among other things. Unfortunately, the API is not yet stable enough for me to prioritize documenting it publicly. If you would like more information regaring how you can use TaskRatchet's API, or you find anything in this document that seems inaccurate, please email me at nathan@taskratchet.com.

You can find your API user ID and token in your account settings.

Tooling

Examples

Authentication

The API uses two custom headers for authentication.

HeaderDescription
X-Taskratchet-UseridYour account ID, found in your account settings
X-Taskratchet-TokenYour API token, found in your account settings

Schema

Base URL: https://api.taskratchet.com/api1/

EndpointDescription
GET meGet your profile data
PUT meUpdate your profile data
GET me/tasksGet all your tasks
POST me/tasksCreate a new task
GET me/tasks/{task_id}Get a specific task
PUT me/tasks/{task_id}Update a specific task
GET statusGet API status details
GET timezonesList of valid timezones

GET me

Response FieldTypeDescription
idstringThe account's unique identifier
namestringUser's full name
emailstringUser's email address
timezonestringUser's current account timezone
cardsarrayList of user's payment methods
integrationsobjectUser's integration settings; currently only Beeminder

Example response:

{
    "id": "Zu0qDVncIgSuUbQfr261",
    "name": "Jon Doe",
    "email": "jon@doe.com",
    "timezone": "America/New_York",
    "cards": [],
    "integrations": {
        "beeminder": {
            "user": "jondoe",
            "goal_new_tasks": "tr_tasks"
        }
    }
}

PUT me

Input FieldTypeDescription
namestringUser's full name
emailstringUser's email address
timezonestringUser's timezone; for valid values, see GET timezones
new_passwordstringNew password
integrationsobjectUser's integration settings; currently only Beeminder

Response is the updated user object--see GET me.

GET me/tasks

Returns an array of tasks. Currently it returns all tasks ever associated with the user. In the future I hope to update it to be paginated and filterable.

Task FieldTypeDescription
idstringTask's unique identifier
taskstringTask's title
duestringTask's timezone-agnostic due string
due_timestampnumberTask's precise due time, taking the user's current timezone into account. Changing the user's timezone will change this number for all tasks.
centsnumberTask's stakes
completebooleanWhether or not the task has been completed
statusstringOne of "complete", "expired", or "pending"
timezonestringThe user's current timezone

Example response:

[
    {
        "id": "tdDPzh1GpZHAGZURVBf6",
        "task": "Take out the trash",
        "due": "2/21/2022, 11:59 PM",
        "due_timestamp": 1645505940,
        "cents": 500,
        "complete": false,
        "status": "pending",
        "timezone": "America/Cancun"
    }
]

POST me/tasks

Input FieldTypeDescription
taskstringTask title
duestringDue date and time in string of format 3/25/2020, 11:59 PM
centsnumberStakes in cents

On success, returns the created task.

Example response:

{
    "id": "tdDPzh1GpZHAGZURVBf6",
    "task": "Take out the trash",
    "due": "2/21/2022, 11:59 PM",
    "due_timestamp": 1645505940,
    "cents": 500,
    "complete": false,
    "status": "pending",
    "timezone": "America/Cancun"
}

GET me/tasks/{task_id}

Retrieve a single task with task_id. See GET me/tasks for more detail on the returned task object.

Example respone:

{
    "id": "tdDPzh1GpZHAGZURVBf6",
    "task": "Take out the trash",
    "due": "2/21/2022, 11:59 PM",
    "due_timestamp": 1645505940,
    "cents": 500,
    "complete": false,
    "status": "pending",
    "timezone": "America/Cancun"
}

GET status

Returns details about the API server instance that handled the request. Currently only returns the API's internal UTC time.

Example response:

{
    "utc_now": "2022-07-12T18:52:41.647995+00:00"
}

GET timezones

Returns an array of valid timezone values.