Using the API

Everything the Roster app does goes through the same JSON API, so anything you can do on a page you can do from a script. The rest of this section lists every endpoint, grouped by area: its parameters, its body, examples in several languages, and what comes back. It's generated from the routes themselves, so it's always current.

Signing inCopy Anchor Link

The API uses the same sign-in as the app: email and password, then a session cookie. Make an account for your integration (say, bots@acme.example), invite it to the workspace as a member, and sign in with it:

ROSTER=https://roster.example.com
curl -c cookies.txt -H 'content-type: application/json' \
  -d '{"email":"bots@acme.example","password":"…"}' \
  "$ROSTER/api/auth/sign-in/email"

-c cookies.txt keeps the session cookie; send it back with -b cookies.txt on every call. Sessions last 7 days and renew while they're used. Sign out with POST /api/auth/sign-out.

Your workspaceCopy Anchor Link

Almost everything is under /api/workspaces/<workspace id>/. GET /api/me lists your workspaces:

curl -b cookies.txt "$ROSTER/api/me"
WS=$(curl -s -b cookies.txt "$ROSTER/api/me" | jq -r '.workspaces[0].id')

A first scriptCopy Anchor Link

Hire someone from a role template, then give it a note:

HIRE=$(curl -s -b cookies.txt -H 'content-type: application/json' \
  -d '{"displayName":"Quinn","slug":"quinn","template":"support"}' \
  "$ROSTER/api/workspaces/$WS/hires" | jq -r .id)

curl -b cookies.txt -H 'content-type: application/json' \
  -d '{"text":"Refunds over $500 need Dana to approve."}' \
  "$ROSTER/api/workspaces/$WS/hires/$HIRE/notes"

What comes backCopy Anchor Link

• JSON, with ids as strings and times as ISO 8601 (2026-11-03T09:00:00.000Z).
• Lists that grow (timecards, files, work) come in pages: { items, next }. Pass next as ?before= to get the next page; next is null on the last one.
• Secrets are never sent back. A connection lists which are set in secretsSet.
• Costs aren't part of the workspace API.

ErrorsCopy Anchor Link

Errors are JSON with a sentence you can show people, and per-field problems when a request needs fixing:

{ "error": "Some fields need fixing.", "fields": { "slug": ["use lowercase letters, digits and dashes (max 40)"] } }

LimitsCopy Anchor Link

Sign-in, sign-up and invitations allow 10 requests a minute per address; everything else, 600 a minute per address and 300 a minute per person.

Live updatesCopy Anchor Link

GET /api/workspaces/<id>/events is a stream of Server-Sent Events: one event each time something happens in the workspace, naming the hire and task it's about. Fetch what you need again when one arrives.

curl -N -b cookies.txt "$ROSTER/api/workspaces/$WS/events"

The OpenAPI documentCopy Anchor Link

The reference is also an OpenAPI 3.1 document at /api/openapi.json, for generating a client or importing into a tool like Postman.