api reference

The Tockwork REST API

Manage and run your automations from scripts, CI, or other tools. Everything the app can do with automations and runs, over plain JSON.

Authentication

Create an API token in Settings → API tokens, then send it as a Bearer token on every request. Tokens look like twk_… and are shown only once at creation.

curl https://tockwork.com/api/v1/automations \
  -H "Authorization: Bearer twk_YOUR_TOKEN"

Base URL: https://tockwork.com/api/v1

Endpoints

GET/automations

List your automations. Returns id, name, description, triggerType, cron, enabled, lastStatus, lastRunAt and createdAt for each.

curl https://tockwork.com/api/v1/automations \
  -H "Authorization: Bearer twk_YOUR_TOKEN"

POST/automations

Create an automation from a draft: name, description, triggerType (manual | cron | webhook), cron, delivery ({ email, chat }) and steps — each step a plain-text instruction with optional allowedTools (web_search, web_fetch, current_time, send_webhook). A minimal { "name": "…" } body also works.

curl -X POST https://tockwork.com/api/v1/automations \
  -H "Authorization: Bearer twk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning AI brief",
    "description": "Daily AI news summary",
    "triggerType": "cron",
    "cron": "0 8 * * 1-5",
    "delivery": { "email": true, "chat": false },
    "steps": [
      {
        "id": "step-1",
        "order": 0,
        "instruction": "Search the web for AI news from the last 24 hours and summarize the top 5 stories.",
        "allowedTools": ["web_search"]
      }
    ]
  }'

GET/automations/:id

Fetch one automation in full, including its plain-text steps (stepsJson). Webhook secrets are never returned.

curl https://tockwork.com/api/v1/automations/AUTOMATION_ID \
  -H "Authorization: Bearer twk_YOUR_TOKEN"

POST/automations/:id/run

Trigger a manual run. The run executes asynchronously; poll the runs endpoints for status. Returns { ok, eventId }.

curl -X POST https://tockwork.com/api/v1/automations/AUTOMATION_ID/run \
  -H "Authorization: Bearer twk_YOUR_TOKEN"

GET/automations/:id/runs?limit=20

Recent runs for an automation, newest first. Each run includes id, status, triggerSource, startedAt, finishedAt, durationMs, tokensIn, tokensOut and error. limit defaults to 20 (max 100).

curl "https://tockwork.com/api/v1/automations/AUTOMATION_ID/runs?limit=20" \
  -H "Authorization: Bearer twk_YOUR_TOKEN"

GET/runs/:id

One run with its step-by-step trace: every step’s order, instruction, status, output and error, plus the run’s final output.

curl https://tockwork.com/api/v1/runs/RUN_ID \
  -H "Authorization: Bearer twk_YOUR_TOKEN"

Errors

Errors are JSON with an error field and a matching HTTP status. Validation failures (400) also include an issues array describing what was wrong.

{ "error": "Unauthorized" }   // 401 — missing, invalid, or revoked token
{ "error": "not_found" }      // 404 — no such resource, or it isn't yours
{ "error": "invalid_body", "issues": [ … ] }   // 400 — validation failed
{ "error": "Rate limit exceeded" }             // 429 — slow down

Rate limit

Each token may make up to 120 requests per minute. Beyond that, requests return 429 until the minute window resets.