Docs · v1

A small REST API for your tasks, your tabs, and your agents.

The Chrome extension uses it to sync. You can use it to let a script or an AI assistant read what you're working on and file things into it. Base URL:

https://tabdocket.com/api/public/v1

Two ways to authenticate

The extension sends a Supabase session token. Agents and scripts send an API key that starts with td_live_. Both go in the Authorization: Bearer header.

Agents can never delete

There is no delete endpoint and no delete scope. A key cannot set deleted_at, cannot move a task to trash, and cannot call /sync. Deleting is yours alone.

Everything is attributed

Tasks, tabs and notes record whether you or an agent created them, so you always know which rows arrived while you were away.

Endpoints

GET/mesession or key

Who the credential belongs to, the current plan, and the scopes you hold.

{
  "id": "8f1c…",
  "email": "you@example.com",
  "plan": "annual",
  "credential": "api_key",
  "scopes": ["read", "write"]
}

GET/entitlementsession or key

A cache-friendly answer to “is this account Pro?”, used by the extension.

{
  "pro": true,
  "plan": "annual",
  "source": "stripe",
  "expires_at": "2026-11-02T00:00:00.000Z",
  "recheck_after": "2026-08-11T09:12:00.000Z"
}

GET/sync?since=<iso timestamp>session only

Everything that changed since a timestamp, across projects, tasks, tabs and notes. Tombstones come back as rows with deleted_at set.

{
  "server_time": "2026-08-04T09:12:00.000Z",
  "changes": { "sync_tasks": [ … ], "sync_tabs": [ … ] }
}

POST/syncsession only

Push up to 500 change records. Last write wins on updated_at; anything stale comes back in rejected with the server's winning row.

curl -X POST https://tabdocket.com/api/public/v1/sync \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '[{
    "table": "sync_tasks",
    "id": "0f3c…",
    "updated_at": "2026-08-04T09:11:00.000Z",
    "payload": { "title": "Tax return", "status": "todo" }
  }]'

GET/tasks?status=&project_id=&since=&limit=session or key (read)

Your open tasks, newest change first. Deleted tasks are never returned.

curl https://tabdocket.com/api/public/v1/tasks?limit=20 \
  -H "Authorization: Bearer $TABDOCKET_KEY"

POST/taskssession or key (write)

Create a task. Agent-created rows are marked created_by: agent.

curl -X POST https://tabdocket.com/api/public/v1/tasks \
  -H "Authorization: Bearer $TABDOCKET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Compare CRM vendors", "status": "todo" }'

GET/tasks/{id}session or key (read)

One task with all of its saved tabs and notes.

PATCH/tasks/{id}session or key (write)

Update title, status, colour or project. Keys cannot set deleted_at or move a task into a trash bucket.

POST/tasks/{id}/tabssession or key (write)

File up to 100 tabs into a task, in order.

curl -X POST https://tabdocket.com/api/public/v1/tasks/0f3c…/tabs \
  -H "Authorization: Bearer $TABDOCKET_KEY" \
  -H "Content-Type: application/json" \
  -d '[{ "url": "https://vendor.com/pricing", "title": "Vendor pricing" }]'

POST/tasks/{id}/notessession or key (write)

Add a note to a task — what the agent found, or where it stopped.

POST/inbox/tabssession or key (write)

Send tabs when the agent doesn't know which task they belong to. They land in an “Agent inbox” task for you to sort.

GET/projectssession or key (read)

Your projects, so an agent can put a new task in the right one.

POST/projectssession or key (write)

Create a project.

Connecting an agent

1. Create a key in your account, under “API keys and integrations”. Give it read, write, or both.
2. Store it as an environment variable — TABDOCKET_KEY — in your agent's secrets. Never paste it into a prompt.
3. Point the agent at https://tabdocket.com/api/public/v1 and tell it what it may do: read your tasks, create tasks, file tabs and notes. It physically cannot delete.
4. Watch the calls arrive in the activity list on your account page, and revoke the key any time.

Limits and errors

60 requests per minute and 600 per hour per key. Over that: 429 with Retry-After.
401 for a missing, invalid or revoked credential. 403 for a missing scope.
DELETE and PUT return 405 for every path.
Errors are JSON: { "error": "…" }.
API keys are a Pro feature; the free version never talks to a server at all.