Appearance
API v2
WARNING
This version of the API is in active development. The API and its associated documentation are likely to be incomplete and/or incorrect, and may change without notice.
Authentication
To use the TaskRatchet API, you need an API key. This key is used to authenticate your requests and is required for all endpoints.
Example request with API key:
bash
curl "https://api.taskratchet.com/api2/me" \
-H "Authorization: ApiKey-v2 YOUR_API_V2_TOKEN"Please reach out to [email protected] to get an API key.
Rate Limiting
Rate limiting is handled at the edge by Cloudflare. Limits are configured per route pattern:
/api2/*: 100 requests per 15 minutes
Rate-limited requests receive HTTP 429 (Too Many Requests) responses.
Schema
Base URL: https://api.taskratchet.com/api2/
| Endpoint | Description |
|---|---|
GET /api2/me | Get your profile data |
PUT /api2/me | Update your profile |
DELETE /api2/me | Delete your account |
GET /api2/me/tasks | Get all your tasks |
POST /api2/me/tasks | Create a new task |
GET /api2/me/tasks/:task_id | Get a single task |
PUT /api2/me/tasks/:task_id | Update a task |
POST /api2/me/tasks/:task_id/uncle | Give up on a task and trigger charge |
POST /api2/me/token | Reset your API v2 token |
GET /api2/me/token | Get your API v2 token |
GET /api2/me
| Response Field | Type | Description |
|---|---|---|
| id | string | The account's unique identifier |
| name | string | User's full name (optional) |
| string | User's email address | |
| timezone | string | Deprecated. User's IANA timezone (optional) |
| integrations | object | User's integration settings; currently only Beeminder |
| has_stripe_customer | boolean | Whether the user has a Stripe customer account |
Example response:
json
{
"id": "Zu0qDVncIgSuUbQfr261",
"name": "Jon Doe",
"email": "[email protected]",
"timezone": "America/New_York",
"integrations": {
"beeminder": {
"user": "jondoe",
"goal_new_tasks": "tr_tasks"
}
},
"has_stripe_customer": true
}PUT /api2/me
Updates the authenticated user's profile. The request body should be a JSON object with at least one of the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | false | User's full name |
| string | false | User's email address | |
| timezone | string | false | Deprecated. User's IANA timezone |
| email_global_unsubscribe | boolean | false | Unsubscribe from all emails (e.g. daily reminders) |
| beeminder_user | string | false | Beeminder username for the connected integration |
| beeminder_token | string | false | Beeminder auth token for the connected integration |
| beeminder_goal_new_tasks | string | false | Beeminder goal slug for new-task tracking |
Example request:
bash
curl -X PUT "https://api.taskratchet.com/api2/me" \
-H "Authorization: ApiKey-v2 YOUR_API_V2_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Jane Doe"}'On success, returns the updated user profile object (same shape as GET /api2/me).
DELETE /api2/me
Deletes the user's account. This action is irreversible.
GET /api2/me/tasks
Returns an array of tasks. This route is paginated.
Query params:
| Param | Type | Required | Description |
|---|---|---|---|
| page | number | false | Page number (default: 0) |
| status | string | false | Filter by task status (pending, complete, expired) |
| due_before | number | false | Unix timestamp; only return tasks due before this time |
| due_after | number | false | Unix timestamp; only return tasks due after this time |
Response format:
| Response Field | Type | Description |
|---|---|---|
| id | string | The task's unique identifier |
| task | string | The task description |
| due | number | Unix timestamp of the task's due date |
| cents | number | The task's stakes in cents |
| complete | boolean | Whether the task is complete |
| status | string | The task's status (pending, complete, expired) |
| chargeStatus | string | Present only when a charge has been initiated. One of: notified, authorized, captured (optional) |
| contested | boolean | Present and true only when the user has contested the charge (optional) |
Example request:
bash
curl "https://api.taskratchet.com/api2/me/tasks?page=0" \
-H "Authorization: ApiKey-v2 YOUR_API_V2_TOKEN"Example response:
json
[
{
"id": "tdDPzh1GpZHAGZURVBf6",
"task": "Take out the trash",
"due": 1614556800,
"cents": 100,
"complete": false,
"status": "pending"
},
{
"id": "xkL9mN2OpQrStUvWxYz3",
"task": "File tax return",
"due": 1614470400,
"cents": 500,
"complete": false,
"status": "expired",
"chargeStatus": "notified"
}
]POST /api2/me/tasks
Creates a new task. The request body should be a JSON object with the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
| task | string | true | The task description (must be non-empty) |
| due | number | true | Unix timestamp of the task's due date |
| cents | number | true | The task's stakes in cents (minimum 100) |
| recurrence | object | false | The task's recurrence settings |
| recurrence.days | number | true | Number of days between recurrences |
On success, the response will be the created task object.
Example response:
json
{
"id": "tdDPzh1GpZHAGZURVBf6",
"task": "Take out the trash",
"due": 1614556800,
"cents": 100,
"complete": false,
"status": "pending"
}GET /api2/me/tasks/:task_id
Returns a single task by ID.
Example request:
bash
curl "https://api.taskratchet.com/api2/me/tasks/tdDPzh1GpZHAGZURVBf6" \
-H "Authorization: ApiKey-v2 YOUR_API_V2_TOKEN"Example response:
json
{
"id": "tdDPzh1GpZHAGZURVBf6",
"task": "Take out the trash",
"due": 1614556800,
"cents": 100,
"complete": false,
"status": "pending"
}PUT /api2/me/tasks/:task_id
Updates an existing task. All fields are optional, but at least one must be provided.
| Field | Type | Required | Description |
|---|---|---|---|
| complete | boolean | false | Mark the task complete or incomplete (cannot mark as complete if expired) |
| cents | number | false | Update the stakes in cents (can only be increased, minimum 100) |
| due | number | false | Update the due date as a Unix timestamp (can only be moved earlier) |
INFO
Stakes can only be increased and deadlines can only be moved earlier — you cannot make a task easier after creating it.
Example request:
bash
curl -X PUT "https://api.taskratchet.com/api2/me/tasks/tdDPzh1GpZHAGZURVBf6" \
-H "Authorization: ApiKey-v2 YOUR_API_V2_TOKEN" \
-H "Content-Type: application/json" \
-d '{"complete": true}'On success, returns the updated task object.
Example response:
json
{
"id": "tdDPzh1GpZHAGZURVBf6",
"task": "Take out the trash",
"due": 1614556800,
"cents": 100,
"complete": true,
"status": "complete"
}POST /api2/me/tasks/:task_id/uncle
Gives up on a task early ("cries uncle"), triggering the charge process before the deadline. This sends a charge notification email and begins the charge flow. Can only be called once per task — returns 409 Conflict if the task has already been uncled or a charge has already been initiated.
Example request:
bash
curl -X POST "https://api.taskratchet.com/api2/me/tasks/tdDPzh1GpZHAGZURVBf6/uncle" \
-H "Authorization: ApiKey-v2 YOUR_API_V2_TOKEN"Returns 200 OK with body ok on success.
POST /api2/me/token
Reset your account's API v2 token. This will invalidate the old token and generate a new one.
You'll need to be authenticated in order to reset your token. If you don't already have a token, contact support for help.
GET /api2/me/token
Returns the current API v2 token for the authenticated user.