hello@thetandem.app 30-day Platinum trial · free for up to 3 users · 5 free clients per user
Home / Guides / Using the REST API

Using the REST API

October 3, 2026 · Updated · 3 min read

The Tandem App REST API lets your own scripts and tools work with people, channels, messages (including files, reactions and pins), tasks (with comments and checklists), Docs pages and Numbers spreadsheets, and search. It uses a personal access token, so a script can see and do exactly what you can, and nothing more. This guide covers creating a token, the endpoints and a few examples.

Step 1: create a token

  1. Open My account (your name at the bottom of the sidebar) and go to API tokens.
  2. Give the token a Name that says what uses it, for example Nightly report.
  3. Choose Read only or Read and write. Pick read only unless the script needs to change anything.
  4. Choose how long it works for (30 days, 90 days or a year), and, under Channels, whether it may use every channel you can see or only the ones you tick. A token limited to certain channels can't search or make channels.
  5. Click Create token and copy it now. It won't be shown again.

You can have up to 20 tokens. The list shows when each was last used; click Revoke on any you no longer need, and anything using it stops working straight away. Treat a token like a password: keep it out of code repositories and shared documents.

Step 2: make a request

The API lives at your workspace's own address:

https://your-company.thetandem.app/api/v1

Send the token in the Authorization header of every request, and ask for JSON:

curl -H "Authorization: Bearer YOUR_TOKEN" -H "Accept: application/json" https://your-company.thetandem.app/api/v1/me

The How to use the API link next to your tokens opens a reference page inside your workspace with ready-made examples for your address.

Endpoints

The reference page in your workspace lists every endpoint with its parameters, ready-made examples and a Try it panel. In short:

  • You and people: GET /me, GET /users, GET /users/{id}.
  • Channels: list, read, make (POST /channels), rename, archive, join, leave, and see, add or remove members.
  • Messages: read (newest first, a page at a time, or one message with its thread), post (with files as multipart/form-data), edit, delete, react and pin.
  • Tasks: list (filter by status or assignee), read one in full, create, change any detail, delete, comment, and add or tick checklist items.
  • Docs and Numbers: list documents and their pages, read a page as Markdown, plain text or HTML, create pages, and read spreadsheets as rows of values.
  • Search: GET /search?q=, with the same filters as the app.

Anything that changes something needs a read-and-write token. The whole API is also published as an OpenAPI 3.1 document at /api/v1/openapi.json on your workspace's address, for Postman, Insomnia or code generators. Nothing that runs the workspace (roles, security settings, closing it) is in the API.

Examples

Post a message to #deploys:

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"text": "Deployed v2.1"}' https://your-company.thetandem.app/api/v1/channels/deploys/messages

Create a task in #operations:

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"title": "Renew the domain", "due_on": "2026-11-01", "priority": "high"}' https://your-company.thetandem.app/api/v1/channels/operations/tasks

Limits and errors

  • Up to 120 requests a minute, and 30 a minute for posting messages or creating tasks.
  • Answers are JSON. Problems always come back as {"error": "...", "code": "..."} with a suitable status code, for example 401 unauthenticated for a missing or revoked token, 403 token_read_only when a read-only token tries to write, and 422 validation_failed (with an errors list per field) when something sent is invalid.
  • Lists come a page at a time: send back next_before or next_after for the next page.
  • Add an Idempotency-Key header to a write and you can safely retry it: the same key returns the first answer instead of doing it twice.
  • If your account is deactivated, its tokens stop working.

Other ways to connect

To let another tool post into a channel without a personal token, an owner or admin can create an incoming webhook. To run your own code when someone types a command, see slash commands.

Related

Try it in your own workspace.Every new workspace tries Platinum free for 30 days, then stays free for up to 3 users.
Start free

← Back to guides