Start here

Getting started with the Twindem API

A terminal agent needs two values: a personal API key and the UUID of the project it is allowed to work on. The key never travels in a URL or request body.

Prerequisites

An active Twindem organization membership.
Access to at least one project.
A personal API key created under Twindem → API Keys.
Explicit Board, Docs, and/or Swagger grants for the target project.

Configure the shell

export TWINDEM_API_KEY='twd_live_…'
export TWINDEM_PROJECT_ID='<project-uuid>'
export TWINDEM_API_BASE='https://twindem.ai/api'

Do not commit these values.

Use an ignored local environment file, operating-system keychain, CI secret, or secret manager. Never paste a real key into TDocs or an OpenAPI example.

Inspect the key context

curl "$TWINDEM_API_BASE/auth/context" \
  -H "Authorization: Bearer $TWINDEM_API_KEY"

The response identifies the credential, user, organization, role, and per-project product grants:

{
  "credential": { "type": "api_key", "id": "…", "name": "Terminal agent", "prefix": "twd_live_abcd…" },
  "userId": "…",
  "orgId": "…",
  "role": "member",
  "grants": [
    { "projectId": "…", "board": "write", "docs": "write", "swagger": "read" }
  ]
}

Make the first calls

List visible Board projects

curl "$TWINDEM_API_BASE/board/projects" \
  -H "Authorization: Bearer $TWINDEM_API_KEY"

List work items

curl "$TWINDEM_API_BASE/board/projects/$TWINDEM_PROJECT_ID/work-items?limit=20" \
  -H "Authorization: Bearer $TWINDEM_API_KEY"

List project documentation pages

curl "$TWINDEM_API_BASE/docs/projects/$TWINDEM_PROJECT_ID/pages" \
  -H "Authorization: Bearer $TWINDEM_API_KEY"

List visible API contracts

curl "$TWINDEM_API_BASE/swagger/projects/$TWINDEM_PROJECT_ID/apis" \
  -H "Authorization: Bearer $TWINDEM_API_KEY"

A 403 on one product while another returns 200 normally means the key lacks that product grant; it does not imply the key itself is invalid.