API Reference

Create a new task. This is the endpoint the web chat interface uses when a user submits a request. Requires an active session and CSRF token. Rate-limited to 30 requests per hour per user.

Headers

X-CSRFToken: <csrf-token>
Content-Type: application/json

Request Body

Example Request

curl -s -X POST https://tarsai.dev/api/tasks/ \
  -H "X-CSRFToken: <csrf-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 12,
    "title": "Add rate limiting to the login endpoint",
    "description": "Use django-ratelimit; allow 10 attempts per minute per IP."
  }'

Example Response — 201 Created

{
  "id": 1338,
  "title": "Add rate limiting to the login endpoint",
  "description": "Use django-ratelimit; allow 10 attempts per minute per IP.",
  "status": "pending",
  "status_display": "Pending",
  "project": "backend-api",
  "created_at": "2026-04-27T14:32:00.000Z"
}

Return a paginated list of tasks for the authenticated user, newest first by default. Used by the chat feed for infinite scroll.

Query Parameters

Example Request

curl -s "https://tarsai.dev/api/tasks/?page=1&per_page=20&status=completed"

Example Response — 200 OK

{
  "tasks": [
    {
      "id": 1338,
      "title": "Add rate limiting to the login endpoint",
      "status": "completed",
      "status_display": "Completed",
      "project": "backend-api",
      "branch_name": "tars/rate-limit-login-1338",
      "pr_url": "https://github.com/acme-corp/backend-api/pull/92",
      "error_message": null,
      "created_at": "2026-04-27T14:32:00.000Z",
      "completed_at": "2026-04-27T14:45:00.000Z"
    }
  ],
  "has_more": false,
  "next_page": null
}

Register a new worker. Returns an API key that must be passed with all subsequent worker requests.

Request Body

Example Request

curl -s -X POST https://tarsai.dev/api/workers/register/ \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "worker-us-east-01",
    "capacity": 2,
    "specs": "8-core / 16GB RAM"
  }'

Example Response — 201 Created

{
  "worker_id": 42,
  "api_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Signal that the worker is still alive. Send this every 15–30 seconds. Workers that miss heartbeats for more than 5 minutes are marked offline.

Headers

X-Worker-Key: <api-key>

Request Body (all optional)

Example Request

curl -s -X POST https://tarsai.dev/api/workers/heartbeat/ \
  -H "X-Worker-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Content-Type: application/json" \
  -d '{"current_load": 1, "status": "busy"}'

Example Response — 200 OK

{"ok": true}

Claim the next available task from the queue. Returns null if the worker is at capacity or no tasks are pending. Uses an optimistic scoring algorithm that considers task priority, wait time, and project affinity.

Headers

X-Worker-Key: <api-key>

Example Request

curl -s https://tarsai.dev/api/workers/next-task/ \
  -H "X-Worker-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479"

Example Response — task available

{
  "task": {
    "id": 1337,
    "title": "Fix the 500 error on password reset",
    "description": "Occurs when the reset token is expired. Should return 400 with a user-friendly message.",
    "priority": 5,
    "project": {
      "id": 12,
      "name": "backend-api",
      "github_repo": "acme-corp/backend-api",
      "default_branch": "main"
    }
  }
}

Example Response — no task available

{"task": null}

Update the status or metadata of an assigned task. Called at each stage of execution to report progress. Triggers email notifications and WebSocket broadcasts to the dashboard.

Headers

X-Worker-Key: <api-key>

Request Body

Task Lifecycle

A typical task progresses through these states:

pending → assigned → in_progress → reviewing → completed

On failure at any stage:

pending → assigned → in_progress → failed

Example Request — starting work

curl -s -X POST https://tarsai.dev/api/workers/task/1337/update/ \
  -H "X-Worker-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Content-Type: application/json" \
  -d '{"status": "in_progress"}'

Example Request — PR opened

curl -s -X POST https://tarsai.dev/api/workers/task/1337/update/ \
  -H "X-Worker-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "reviewing",
    "branch_name": "tars/fix-password-reset-1337",
    "pr_url": "https://github.com/acme-corp/backend-api/pull/88"
  }'

Example Response — 200 OK

{
  "ok": true,
  "task_id": 1337,
  "status": "reviewing"
}

Health check endpoint — no authentication required. Returns 200 OK when the server and database are reachable, or 503 Service Unavailable if the database is down.

Example Response — 200 OK

{
  "status": "ok",
  "db": true,
  "redis": true,
  "version": "1.0"
}

Example Response — 503 Service Unavailable

{
  "status": "error",
  "db": false,
  "redis": false,
  "version": "1.0"
}