Overview API Reference Webhooks

API Reference

Integrate with Task Tracker programmatically using our JSON API.

Authentication

API access requires a JSON Web Token (JWT). You can create tokens in the UI by visiting the API Tokens page.

Creating a Token

Navigate to the API Tokens section.
Click "New Token".
Provide a name and select a scope.
Copy the token—it will only be shown once.

Scopes

Tokens can have one of two scopes:

user: Full account access. Can trigger or complete any task.
task:<id>: Single-task access. Can only trigger or complete the specified task.

Token Lifecycle

Tokens are active until revoked or expired (if an expiration date was set). If revoked, any API calls using that token will return 401 Unauthorized.

Endpoints

Tasks

Trigger a Task

`POST /api/v1/tasks/:id/trigger`

Manually triggers a task, creating a new pending occurrence and dispatching webhooks. Returns 200 OK with an empty body on success.

curl -X POST https://tasks.newstrom.life/api/v1/tasks/1/trigger \
  -H "Authorization: Bearer YOUR_TOKEN"

Complete a Task

`POST /api/v1/tasks/:id/complete`

Marks the most recent pending occurrence of a task as completed. If no pending occurrence exists, creates a new completed occurrence. Returns 200 OK with an empty body on success.

curl -X POST https://tasks.newstrom.life/api/v1/tasks/1/complete \
  -H "Authorization: Bearer YOUR_TOKEN"

Errors

The API uses standard HTTP status codes.

2xx: Success
401: Unauthorized (missing or invalid token)
403: Forbidden (token does not have the required scope)
404: Not Found (resource does not exist or is out of scope)
422: Unprocessable Entity (validation errors)
429: Too Many Requests (rate limit exceeded—see below)

Rate Limits

Each account is limited to 300 requests per 5 minutes and 2,000 requests per hour across all tokens and web activity. Individual write endpoints (trigger and complete) are additionally limited to 60 requests per minute.

429 Response

When a request exceeds a limit, the API responds with 429 Too Many Requests, a Retry-After header indicating the number of seconds to wait, and the following JSON body:

{ "error": "Too Many Requests" }

Clients should respect the Retry-After header and back off accordingly.

Internal API

The internal API powers first-party clients (mobile apps, etc.). It lives under /internal_api and uses a stricter response contract than /api/v1. Third-party integrators should use the /api/v1 endpoints documented above.

Endpoints are added in later phases. This section documents the cross-cutting response contract that all /internal_api endpoints conform to.

Success Envelopes

Successful responses use one of three shapes:

Collections (paginated index endpoints) return an envelope with a data array and meta block:

{
  "data": [ /* resources */ ],
  "meta": { "page": 1, "per_page": 25, "total": 137, "next_page": 2 }
}

Single resources (show, create, update) return the bare resource JSON (no envelope), with status 200 or 201.
Command actions (e.g. trigger, complete, status transitions, DELETE, sign-out) return 204 No Content with an empty body. Callers refetch if they need the post-command state.

Error Envelope

Every non-2xx response from /internal_api/* uses the same envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "Name can't be blank",
    "details": "...optional long-form explanation...",
    "fields": { "name": ["can't be blank"] },
    "retry_after": 30
  }
}

code is a stable, machine-readable identifier. fields appears only on 422 responses and maps attribute names to error messages. retry_after (seconds) appears only on 429 responses and mirrors the Retry-After header.

Error Codes

Code	Typical Status	Meaning
`unauthorized`	401	Missing, invalid, expired, or revoked token.
`forbidden`	403	Token lacks the required scope.
`not_found`	404	Resource does not exist or is out of scope.
`user_not_enrolled`	409	User must complete web enrollment before using this client.
`validation_failed`	422	Request body failed validation. See `fields`.
`rate_limited`	429	Rate limit exceeded. See `retry_after`.
`conflict`	409	Request conflicts with current resource state.
`server_error`	500	Unexpected server error.

Pagination

Collection endpoints accept ?page= and ?per_page= query parameters. per_page defaults to 25 and caps at 100. Results are sorted by each endpoint's documented default sort; no client-controllable ?sort= is supported in v1.

Status Codes

The internal API uses this restricted set: 200, 201, 204, 400, 401, 403, 404, 409, 422, 429, 500.

Rate Limits

An IP-based pre-auth rate limit of 120 requests per minute applies to all /internal_api/* traffic. Per-endpoint limits are documented with each endpoint. Rate-limited responses carry a Retry-After header plus the rate_limited error envelope.