REST API v1

Two ways to drive a workspace from outside the app, both backed by the same server-side core and the same permission model the app uses:

API keys

Keys are created in Workspace home, API & MCP by anyone whose workspace role has the Change workspace settings permission (owners by default). API keys are part of the Pro plan.

A key acts as one workspace member and carries scopes:

• Every call is first authorised as that member. Their workspace role, the permissions matrix and their board role (owner / editor / contributor / viewer) apply exactly as in the app. Private boards they cannot open do not exist to the key.
• The key's scopes then clamp what is left. A read-only key held by an owner cannot write; an items:delete key held by a viewer still cannot delete.

The full key is shown once at creation; only its SHA-256 hash is stored. Revoke a key from the same tab; it stops working immediately. See Permissions and sharing for the roles and matrix a key inherits.

Basics

Base URL https://tallyweek.com/api/v1. JSON in, JSON out. Every response is { "ok": true, "data": … } or { "ok": false, "error": "…" } with a matching HTTP status (400 bad input, 401 bad key, 403 not allowed, 404 not found).

Board ids may be the UUID or the numeric short id from the board URL. Wherever a user is expected, pass a user id, email, or full name.

curl -H "Authorization: Bearer jk_…" https://tallyweek.com/api/v1/me

Workspace

Folders

Boards

GET /boards/:id returns statuses (keys + labels, including custom ones), columns (built-in owner/status/priority/due plus custom columns with ids and settings), column_order, hidden_native_columns, groups[].items[] (each item with values[], assignees[], subitems[], url) and automations.

Groups

Columns

Column types: text number date checkbox dropdown phone long_text timeline link files email rating progress tags time_tracking country connect dependency mirror, plus priority (creates a preset dropdown).

Items

values is keyed by column id or name. Shapes by type: text-like: string; number: number; rating: 0 to 5; progress: 0 to 100; date: YYYY-MM-DD; checkbox: boolean; dropdown: an option label; timeline: {start,end}; link: url string or {url,text}; tags: [strings]; country: 2-letter code; files: [{url,name,size?,type?}]; time_tracking: seconds; connect/dependency: [item ids]. null clears a value.

Status accepts a key (backlog in_motion in_review blocked shipped or a board's custom s_… key) or its label. Priority: low medium high urgent.

Sharing

What happens on a write

Writes go through the same paths the app uses: status changes record activity and notify assignees, moves reorder items, updates deliver @mentions and notifications. Every change is logged in the item's activity as the acting member, streams to open boards in real time, and runs the board's automations (item created, status, priority, column changed). Email notifications are not sent for API-made changes; in-app notifications are.

Example: build a board from scratch

K="Authorization: Bearer jk_…"; B=https://tallyweek.com/api/v1

curl -s -H "$K" -H 'Content-Type: application/json' $B/boards \
  -d '{"name":"Launch plan","template":"project"}'
# returns data.id, data.groups[], data.columns[]

curl -s -H "$K" -H 'Content-Type: application/json' $B/boards/<id>/columns \
  -d '{"name":"Channel","type":"dropdown","options":["Email","Social","Ads"]}'

curl -s -H "$K" -H 'Content-Type: application/json' $B/boards/<id>/items \
  -d '{"name":"Draft announcement","groupName":"To do","status":"in_motion","priority":"high",
       "dueDate":"2026-10-01","assignees":["dana@example.com"],"values":{"Channel":"Email","Progress":25}}'

Related

• MCP server: the same operations as tools for AI assistants.
• Boards and columns: what each column type stores.
• Pricing: API keys are included in Pro.