Quickstart
Make an API key, give the troop a task, watch it, answer the teammate and read the work.
This page takes you from a new API key to a teammate at work on a task. Each step is a curl command that you can
copy. You need a Troopy workspace with a troop, a terminal, and jq to read the answers.
1. Make an API key
- Open Settings > API keys.
- Type a Key name, such as
Quickstart. - Pick the Scopes
workspace:read,tasks:readandtasks:write. - Select Create key, then Copy key. Troopy shows the key only one time.
Put the key in your shell without typing it in a command. Paste it when read waits, then press Return:
read -rs TROOPY_API_KEY && export TROOPY_API_KEYexport API="https://troopy.ai/api/v1"2. Check the key
GET /me needs no scope. It tells you who the key acts as, in which workspace, and with which scopes:
curl -sS "$API/me" -H "Authorization: Bearer $TROOPY_API_KEY"{ "data": { "user": { "id": "6650c0ffee0000000000000a", "name": "Ada Lovelace", "email": "ada@example.com" }, "organization": { "id": "6650c0ffee0000000000000c", "name": "Lovelace Ltd", "role": "owner" }, "workspace": { "id": "6650c0ffee0000000000000b", "name": "Analytical Engines" }, "auth": { "type": "api_key", "scopes": ["workspace:read", "tasks:read", "tasks:write"] } }}A 401 unauthorized means that the key is wrong or revoked. Every call works in this workspace only.
3. Give the troop a task
Leave out assignee, and the Chief of Staff gives the task to the right teammate. The Idempotency-Key makes a
retry safe: a second send with the same key gives back the first task.
TASK=$(curl -sS -X POST "$API/tasks" \ -H "Authorization: Bearer $TROOPY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"title": "Write the October newsletter", "description": "Lead with the new loyalty card."}' | jq -r .data.key)echo "$TASK"The answer is the task, and .data.key is its key, such as VIR-12. The next steps use the key.
4. Watch the task
curl -sS "$API/tasks/$TASK" -H "Authorization: Bearer $TROOPY_API_KEY" | jq '{status, working, waiting}'Read status to know what to do. While a teammate works, working.doing says what it does now.
| Status | What it means | What you do |
|---|---|---|
todo | The teammate starts it soon. | Wait. |
in_progress | The teammate works on it now. | Wait. |
needs_you | The teammate asked a question, or a call waits for a yes. | Answer it, as step 5 shows. |
in_review | The teammate finished. A person looks at the work. | Read it, as step 6 shows. |
done | It is finished. | Nothing. |
backlog | Nobody works on it. | Give it a teammate, or leave it. |
canceled | Nobody does it. | Nothing. |
Read it again every 10 seconds or more. A real task takes minutes, not seconds.
5. Answer the teammate
When the status is needs_you, asks holds what the teammate asked. Each ask has an id, a kind and a
question. A decision also has options.
curl -sS "$API/tasks/$TASK" -H "Authorization: Bearer $TROOPY_API_KEY" | jq '.data.asks[] | {id, kind, question, options}'Send choice for a decision, or text for your own words:
curl -sS -X POST "$API/asks/$ASK_ID" \ -H "Authorization: Bearer $TROOPY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"choice": "Lead with the loyalty card"}'When nothing on the task waits for a person, the teammate starts again with your answers. A call that waits for a yes is an approval. Common flows shows how to decide it.
6. Read the work and reply
activity holds the comments and the changes of the task, oldest first:
curl -sS "$API/tasks/$TASK" -H "Authorization: Bearer $TROOPY_API_KEY" | jq -r '.data.activity[] | "\(.by.name): \(.text)"'A comment from you brings the teammate back to the task:
curl -sS -X POST "$API/tasks/$TASK/comments" \ -H "Authorization: Bearer $TROOPY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"text": "Make the subject line shorter, please."}'To finish, move the task to done with PATCH /tasks/{key} and {"status": "done"}.
The same steps from the CLI
Each operation is also a troopy command and an MCP tool. These commands do the steps above:
npx -y troopy loginnpx -y troopy whoaminpx -y troopy tasks create --title "Write the October newsletter"npx -y troopy tasks get --key VIR-12npx -y troopy tasks comment --key VIR-12 --text "Make the subject line shorter, please."