API reference

Who am I

GET /api/v1/me

The person the API key belongs to, their organization and role, the key's workspace, and its scopes. Use it to check a key works.

• CLI: troopy whoami. MCP tool: troopy_whoami
• Scopes: any valid key
• At most 120 calls per 60 seconds per 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"
      ]
    }
  }
}

Your Telegram

GET /api/v1/me/telegram

Whether your Telegram is linked to this workspace. Once linked, what you send Troopy's bot goes to the Chief of Staff here, and its replies and approvals come back there.

• CLI: troopy telegram status. MCP tool: troopy_telegram_status
• Scopes: agents:read
• At most 60 calls per 60 seconds per key

{
  "data": {
    "available": true,
    "bot": "TroopyBot",
    "linked": true,
    "username": "ada_lovelace",
    "linkedAt": "2026-09-01T09:00:00.000Z",
    "workspaceBot": {
      "username": "lovelace_chief_bot",
      "disabled": null,
      "canOpen": true,
      "createdAt": "2026-09-01T09:05:00.000Z"
    },
    "createBotUrl": null
  }
}

Link your Telegram

POST /api/v1/me/telegram

A one-time link to Troopy's bot, good for 10 minutes: the Telegram account that opens it and presses Start is linked to you in this workspace, and unlinked from anywhere else. It then talks to teammates and decides approvals as you, so this needs a key with every scope.

• CLI: troopy telegram connect
• Scopes: workspace:read workspace:write organization:write brain:read brain:write agents:read agents:write apps:read apps:write tasks:read tasks:write code:write research:read research:write tests:read tests:write incidents:read incidents:write analytics:read analytics:write crm:read crm:write customers:read customers:write vault:read vault:write outreach:read outreach:write disputes:write
• At most 10 calls per 60 seconds per key

{
  "data": {
    "available": true,
    "bot": "TroopyBot",
    "linked": false,
    "username": null,
    "linkedAt": null,
    "workspaceBot": {
      "username": "lovelace_chief_bot",
      "disabled": null,
      "canOpen": true,
      "createdAt": "2026-09-01T09:05:00.000Z"
    },
    "createBotUrl": null,
    "url": "https://t.me/TroopyBot?start=Qm9vayBtZSBhIGNha2U",
    "expiresAt": "2026-09-01T09:10:00.000Z"
  }
}

Unlink your Telegram

DELETE /api/v1/me/telegram

Unlinks your Telegram from this workspace. Its conversations stay here.

• CLI: troopy telegram disconnect. MCP tool: troopy_disconnect_telegram
• Scopes: agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "available": true,
    "bot": "TroopyBot",
    "linked": false,
    "username": null,
    "linkedAt": null,
    "workspaceBot": {
      "username": "lovelace_chief_bot",
      "disabled": null,
      "canOpen": true,
      "createdAt": "2026-09-01T09:05:00.000Z"
    },
    "createBotUrl": null
  }
}

Your products

GET /api/v1/me/products

Troopy's products, each with its page in the app, and whether your sidebar lists it in this workspace. The products of your sidebar come first, in its order. Until you pin products, the sidebar lists Docs, Email, Canvas and the CRM.

• CLI: troopy products list
• Scopes: workspace:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "docs",
      "name": "Docs",
      "path": "/documents",
      "pinned": true
    },
    {
      "id": "crm",
      "name": "CRM",
      "path": "/crm",
      "pinned": true
    },
    {
      "id": "analytics",
      "name": "Analytics",
      "path": "/analytics",
      "pinned": false
    }
  ]
}

Pin products to your sidebar

PATCH /api/v1/me/products

Sets the products that your sidebar lists in this workspace, in the order that you send them. Send every product to pin. A product that you leave out goes off the sidebar, and stays on the Products page.

• CLI: troopy products pin
• Scopes: workspace:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": [
    {
      "id": "docs",
      "name": "Docs",
      "path": "/documents",
      "pinned": true
    },
    {
      "id": "crm",
      "name": "CRM",
      "path": "/crm",
      "pinned": true
    },
    {
      "id": "analytics",
      "name": "Analytics",
      "path": "/analytics",
      "pinned": true
    }
  ]
}

Your notifications

GET /api/v1/me/notifications

What Troopy told you about in this workspace, the newest first: decisions that wait for you, work to review, drafts, replies and more, as you chose in Settings > Notifications. Pass `next` as cursor for the page after.

• CLI: troopy notifications list
• Scopes: workspace:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee00000000000071",
      "kind": "decision",
      "by": {
        "type": "agent",
        "id": "6650c0ffee00000000000011",
        "name": "Iris",
        "handle": "writer"
      },
      "verb": "needs your decision on",
      "title": "VIR-12 Write the newsletter",
      "text": "Which of the two subject lines do we send?",
      "href": "/tasks/VIR-12",
      "read": false,
      "at": "2026-10-15T09:00:00.000Z"
    }
  ],
  "unread": 1,
  "next": null
}

Mark notifications read

POST /api/v1/me/notifications/read

Marks these notifications read, or all of them when you send no ids. An email that waits for a notification that you read does not go.

• CLI: troopy notifications read
• Scopes: workspace:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "unread": 0
  }
}

Dismiss a notification

DELETE /api/v1/me/notifications/{id}

Takes one notification out of your bell. The same event does not bring it back.

• CLI: troopy notifications dismiss
• Scopes: workspace:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "unread": 0
  }
}

Clear your notifications

DELETE /api/v1/me/notifications

Empties your bell in this workspace. Emails that you chose without the bell still go.

• CLI: troopy notifications clear
• Scopes: workspace:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "unread": 0
  }
}

What Troopy tells you about

GET /api/v1/me/notification-settings

Each event that Troopy can tell you about, and how: in the bell of the app, by email, or both. Your choices apply in every workspace.

• CLI: troopy notifications settings
• Scopes: workspace:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "kind": "decision",
      "title": "A teammate needs your decision",
      "line": "An approval, or a question that only a person can answer.",
      "app": true,
      "email": true
    },
    {
      "kind": "reply",
      "title": "A teammate replied to you",
      "line": "In a conversation that you started, or in your thread of the troop chat.",
      "app": true,
      "email": null
    }
  ]
}

Change what Troopy tells you about

PATCH /api/v1/me/notification-settings

Turns the bell or the email of some events on or off, for you, in every workspace. An event that Troopy sends no email for stays without one. The events that you leave out stay as they are.

• CLI: troopy notifications set
• Scopes: workspace:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": [
    {
      "kind": "decision",
      "title": "A teammate needs your decision",
      "line": "An approval, or a question that only a person can answer.",
      "app": true,
      "email": true
    },
    {
      "kind": "reply",
      "title": "A teammate replied to you",
      "line": "In a conversation that you started, or in your thread of the troop chat.",
      "app": true,
      "email": null
    }
  ]
}

What happened in the workspace

GET /api/v1/activity

What the people and the teammates of the workspace did, the newest first: comments, new tasks, moves, tasks given to someone, and files. Filter by who did it, a teammate's handle or a person's id, and by kind. Pass `next` as cursor for the page after.

• CLI: troopy activity. MCP tool: troopy_activity
• Scopes: tasks:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee00000000000081",
      "by": {
        "type": "agent",
        "id": "6650c0ffee00000000000011",
        "name": "Iris",
        "handle": "writer"
      },
      "what": "comment",
      "verb": "commented on",
      "task": {
        "id": "6650c0ffee00000000000031",
        "key": "VIR-12",
        "title": "Write the newsletter"
      },
      "text": "The draft is in Docs, with two subject lines to pick from.",
      "at": "2026-10-15T09:00:00.000Z"
    }
  ],
  "next": null
}

What's new in Troopy

GET /api/v1/changelog

Every update to Troopy, the newest first, each with where to try it. `fresh` marks the updates that are new to you. POST /changelog/seen marks them seen.

• CLI: troopy changelog. MCP tool: troopy_changelog
• Scopes: any valid key
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "id": "notifications",
      "date": "2026-10-15",
      "kind": "new",
      "title": "A bell for what needs you",
      "body": "The bell at the top of the sidebar counts what is new for you.",
      "link": {
        "label": "Choose your notifications",
        "href": "/settings?tab=notifications"
      },
      "fresh": true
    }
  ]
}

Mark What's new seen

POST /api/v1/changelog/seen

Marks every update of GET /changelog seen for you, as of now.

• CLI: troopy changelog seen
• Scopes: any valid key
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "fresh": 0
  }
}

Search the Troopy guides

GET /api/v1/guides

Searches the guides of troopy.ai/docs, which tell how each part of Troopy works and how to use it. Each hit names a guide, the part of it that fits, some of its words and its address. GET /guide reads a guide or one part of it.

• CLI: troopy guides search. MCP tool: troopy_search_guides
• Scopes: any valid key
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "slug": "apps/stripe",
      "title": "Stripe",
      "section": "Connect Stripe",
      "anchor": "connect-stripe",
      "snippet": "Open Settings > Apps, and select Connect on the card of Stripe…",
      "url": "https://troopy.ai/docs/apps/stripe#connect-stripe"
    }
  ]
}

Read a Troopy guide

GET /api/v1/guide

Reads one guide of troopy.ai/docs as markdown: the whole guide, or one part of it with the parts under it. Name the part by its anchor, from GET /guides or from sections. A text of more than 5,000 characters stops there, and cut is true: read it one part at a time.

• CLI: troopy guides read. MCP tool: troopy_read_guide
• Scopes: any valid key
• At most 60 calls per 60 seconds per key

{
  "data": {
    "slug": "apps/stripe",
    "title": "Stripe",
    "summary": "What teammates read in Stripe, how to make a restricted key, and what Customers, Analytics and Disputes take from it.",
    "url": "https://troopy.ai/docs/apps/stripe#connect-stripe",
    "sections": [
      {
        "anchor": "connect-stripe",
        "heading": "Connect Stripe"
      }
    ],
    "text": "## Connect Stripe\n\n1. Open **Settings** > **Apps**.",
    "cut": false
  }
}

Stop using the workspace's Telegram bot

DELETE /api/v1/telegram/bot

Troopy stops running the workspace's own bot; people talk to the Chief of Staff through Troopy's shared bot again. Its owner deletes it in @BotFather. Needs an owner or admin.

• CLI: troopy telegram remove-bot
• Scopes: workspace:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "available": true,
    "bot": "TroopyBot",
    "linked": true,
    "username": "ada_lovelace",
    "linkedAt": "2026-09-01T09:00:00.000Z",
    "workspaceBot": null,
    "createBotUrl": null
  }
}

Get the workspace

GET /api/v1/workspace

The workspace the key belongs to: its name, its business's website, description and logo, when it was created and how many people can reach it.

• CLI: troopy workspace get. MCP tool: troopy_get_workspace
• Scopes: workspace:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "id": "6650c0ffee0000000000000b",
    "name": "Analytical Engines",
    "website": "https://analytical.example.com",
    "description": null,
    "logoUrl": "https://cdn.troopy.ai/workspaces/6650c0ffee0000000000000b/logo-4f3c2a1e.png",
    "timezone": "Europe/London",
    "region": "GB",
    "language": "en",
    "postalAddress": null,
    "outreachSending": false,
    "troopRoom": "troop",
    "learnFromTalk": false,
    "learnFromWork": true,
    "engineering": {
      "planApproval": "always",
      "planApprovers": "everyone",
      "releaseMode": "button",
      "releasers": "managers",
      "mergeMethod": "squash",
      "requireChecks": true,
      "tries": 3
    },
    "autoRelease": null,
    "artGrant": null,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "memberCount": 3
  }
}

Update the workspace

PATCH /api/v1/workspace

Renames the workspace, changes the website, description and logo its teammates learn the business from, or its preferences: time zone, region, the language teammates write in, and how engineering tickets go from Analyze to Release. Send at least one field; null clears website, description or logo.

• CLI: troopy workspace rename. MCP tool: troopy_rename_workspace
• Scopes: workspace:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000000b",
    "name": "Analytical Engines",
    "website": "https://analytical.example.com",
    "description": null,
    "logoUrl": "https://cdn.troopy.ai/workspaces/6650c0ffee0000000000000b/logo-4f3c2a1e.png",
    "timezone": "Europe/London",
    "region": "GB",
    "language": "en",
    "postalAddress": null,
    "outreachSending": false,
    "troopRoom": "troop",
    "learnFromTalk": false,
    "learnFromWork": true,
    "engineering": {
      "planApproval": "always",
      "planApprovers": "everyone",
      "releaseMode": "button",
      "releasers": "managers",
      "mergeMethod": "squash",
      "requireChecks": true,
      "tries": 3
    },
    "autoRelease": null,
    "artGrant": null,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "memberCount": 3
  }
}

Share the public dashboard

PATCH /api/v1/public-dashboard

Turns on a live, read-only view of the workspace at a link that anyone can open. It shows the troop and its status, the board with the thread of each task, and Docs. It shows no email, settings or vault, no CRM, Customers or Analytics, and no files on tasks. Tasks that hold the words of customers, leads or senders of mail stay out too. on false stops the link, and on true brings the same link back. reset gives a new link, and the old one stops working. indexable lets search engines index the view. Send no field to read it as it is. Owners and admins.

• CLI: troopy workspace dashboard
• Scopes: workspace:write
• At most 30 calls per 60 seconds per key

{
  "data": {
    "on": true,
    "indexable": false,
    "url": "https://troopy.ai/share/troop/6650c0ffee00000000000001/k3yZ...Q"
  }
}

Turn on auto-release

POST /api/v1/workspace/auto-release

Lets Troopy release each engineering ticket that passed every gate, with no person pressing Release, until a date at most 30 days out. It releases at most dailyCap changes in 24 hours (1 to 10), and only changes up to maxSize. It merges only a commit that GitHub's checks passed, and never a ticket with the label incident. Before a grant, Release must be how changes go live, GitHub's checks must be required, and people must have released 3 changes in the last 30 days. It ends when its date comes, when the engineering settings change, when the person who granted it is no longer an owner or admin, or when GitHub refuses a merge for a reason that a person must handle. A new grant takes the place of the old one. Owners and admins.

• CLI: troopy workspace auto-release
• Scopes: workspace:write code:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000000b",
    "name": "Analytical Engines",
    "website": "https://analytical.example.com",
    "description": null,
    "logoUrl": "https://cdn.troopy.ai/workspaces/6650c0ffee0000000000000b/logo-4f3c2a1e.png",
    "timezone": "Europe/London",
    "region": "GB",
    "language": "en",
    "postalAddress": null,
    "outreachSending": false,
    "troopRoom": "troop",
    "learnFromTalk": false,
    "learnFromWork": true,
    "engineering": {
      "planApproval": "always",
      "planApprovers": "everyone",
      "releaseMode": "button",
      "releasers": "managers",
      "mergeMethod": "squash",
      "requireChecks": true,
      "tries": 3
    },
    "autoRelease": {
      "on": true,
      "until": "2026-10-20T00:00:00.000Z",
      "dailyCap": 3,
      "maxSize": "medium",
      "grantedBy": "Ada Lovelace",
      "grantedAt": "2026-10-06T09:00:00.000Z",
      "endedAt": null,
      "why": null,
      "today": 0
    },
    "artGrant": null,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "memberCount": 3
  }
}

Turn off auto-release

DELETE /api/v1/workspace/auto-release

Ends the workspace's auto-release grant. Then each ticket that is ready to release waits for a person to press Release. Owners and admins.

• CLI: troopy workspace auto-release-off. MCP tool: troopy_end_auto_release
• Scopes: workspace:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000000b",
    "name": "Analytical Engines",
    "website": "https://analytical.example.com",
    "description": null,
    "logoUrl": "https://cdn.troopy.ai/workspaces/6650c0ffee0000000000000b/logo-4f3c2a1e.png",
    "timezone": "Europe/London",
    "region": "GB",
    "language": "en",
    "postalAddress": null,
    "outreachSending": false,
    "troopRoom": "troop",
    "learnFromTalk": false,
    "learnFromWork": true,
    "engineering": {
      "planApproval": "always",
      "planApprovers": "everyone",
      "releaseMode": "button",
      "releasers": "managers",
      "mergeMethod": "squash",
      "requireChecks": true,
      "tries": 3
    },
    "autoRelease": null,
    "artGrant": null,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "memberCount": 3
  }
}

List members

GET /api/v1/members

The people who can reach the workspace, oldest first: the organization's owners and admins, and the members invited into it.

• CLI: troopy members list. MCP tool: troopy_list_members
• Scopes: workspace:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "role": "owner",
      "joinedAt": "2026-09-01T09:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

List workspaces

GET /api/v1/workspaces

The workspaces in the key's organization that its owner can reach, oldest first. A key still acts in its own workspace only.

• CLI: troopy workspace list. MCP tool: troopy_list_workspaces
• Scopes: workspace:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee0000000000000b",
      "name": "Analytical Engines",
      "createdAt": "2026-09-01T09:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Create a workspace

POST /api/v1/workspaces

Adds a workspace to the key's organization, for another business, brand or client. Its owners and admins reach it at once. Needs an owner or admin.

• CLI: troopy workspace create. MCP tool: troopy_create_workspace
• Scopes: organization:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000000d",
    "name": "Northwind Bakery",
    "website": null,
    "description": null,
    "logoUrl": null,
    "timezone": null,
    "region": null,
    "language": "en",
    "postalAddress": null,
    "outreachSending": false,
    "troopRoom": "troop",
    "learnFromTalk": false,
    "learnFromWork": true,
    "engineering": {
      "planApproval": "always",
      "planApprovers": "everyone",
      "releaseMode": "button",
      "releasers": "managers",
      "mergeMethod": "squash",
      "requireChecks": true,
      "tries": 3
    },
    "autoRelease": null,
    "artGrant": null,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "memberCount": 1
  }
}

Get the organization

GET /api/v1/organization

The organization the key's workspace belongs to: its name, the caller's role in it, the AI plan its teammates run on, where their names come from and its answers to setup's survey.

• CLI: troopy organization get. MCP tool: troopy_get_organization
• Scopes: workspace:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "id": "6650c0ffee0000000000000c",
    "name": "Lovelace Ltd",
    "role": "owner",
    "aiProvider": "claude",
    "troopNames": "greek-myth",
    "profile": {
      "teamSize": "2_10",
      "revenue": "10k_50k",
      "jobRole": "founder",
      "businessModel": "services",
      "industries": [
        "technology"
      ]
    }
  }
}

Update the organization

PATCH /api/v1/organization

Renames the organization, picks the AI plan its teammates run on, picks where their names come from, or answers setup's survey; send any of them. Changing the plan keeps the old one signed in on each computer, as the first fallback. A new troopNames renames every teammate still going by a theme's name or its job title; ones a person named keep theirs. profile changes only the answers it names. Needs an owner or admin.

• CLI: troopy organization update. MCP tool: troopy_update_organization
• Scopes: organization:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000000c",
    "name": "Lovelace Ltd",
    "role": "owner",
    "aiProvider": "claude",
    "troopNames": "greek-myth",
    "profile": {
      "teamSize": "2_10",
      "revenue": "10k_50k",
      "jobRole": "founder",
      "businessModel": "services",
      "industries": [
        "technology"
      ]
    }
  }
}

Get the plan of the workspace

GET /api/v1/billing

The plan of the workspace at Troopy: the Trial, Pro, Max or Ultra, what the plan lets it do, whether its teammates work, and when it renews or ends. Each workspace pays for itself, and people are free. Owners and admins change the plan in Settings > Billing. Needs an owner or admin.

• CLI: troopy billing get. MCP tool: troopy_get_billing
• Scopes: workspace:read
• At most 60 calls per 60 seconds per key

{
  "data": {
    "billed": true,
    "state": "active",
    "plan": "pro",
    "interval": "month",
    "works": true,
    "big": false,
    "limits": {
      "teammates": 20,
      "voiceMinutes": 30,
      "picturesPerDay": 20,
      "runs": {
        "rounds": 20,
        "runsPerDay": 500,
        "usdPerRun": 10
      }
    },
    "trialEnd": "2026-10-20T09:00:00.000Z",
    "periodEnd": "2026-11-20T09:00:00.000Z",
    "cancelAt": null
  }
}

Get the computer

GET /api/v1/computer

The workspace's cloud computer, where its teammates work: whether it has launched, each launch step, and how each AI plan of the organization is signed in there. Poll it while launching or while a sign-in code waits for approval.

• CLI: troopy computer get. MCP tool: troopy_get_computer
• Scopes: workspace:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "status": "ready",
    "steps": [
      {
        "id": "computer",
        "label": "Setting up your computer",
        "state": "done"
      },
      {
        "id": "tools",
        "label": "Installing AI tools",
        "state": "done"
      }
    ],
    "error": null,
    "color": "sky",
    "connection": {
      "provider": "chatgpt",
      "method": "device_code",
      "status": "pending",
      "userCode": "VHSQ-DCS73",
      "verificationUrl": "https://auth.openai.com/codex/device",
      "expiresAt": "2026-09-01T09:15:00.000Z",
      "keyHint": null,
      "connectedAt": null,
      "error": null,
      "limitedUntil": null,
      "lapsedAt": null
    },
    "statusUrl": "https://troopy.ai/api/v1/computer"
  }
}

Launch the computer

POST /api/v1/computer

Creates the workspace's cloud computer and installs its AI tools, in about two minutes. Answers 202 at once; poll statusUrl until status is ready. Launching again retries a failed launch from the step that failed, and changes nothing once it is ready. Needs an AI plan (PATCH /organization) and an owner or admin.

• CLI: troopy computer launch. MCP tool: troopy_launch_computer
• Scopes: organization:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "status": "provisioning",
    "steps": [
      {
        "id": "computer",
        "label": "Setting up your computer",
        "state": "done"
      },
      {
        "id": "tools",
        "label": "Installing AI tools",
        "state": "done"
      }
    ],
    "error": null,
    "color": "sky",
    "connection": {
      "provider": "chatgpt",
      "method": "device_code",
      "status": "pending",
      "userCode": "VHSQ-DCS73",
      "verificationUrl": "https://auth.openai.com/codex/device",
      "expiresAt": "2026-09-01T09:15:00.000Z",
      "keyHint": null,
      "connectedAt": null,
      "error": null,
      "limitedUntil": null,
      "lapsedAt": null
    },
    "statusUrl": "https://troopy.ai/api/v1/computer"
  }
}

Update the computer

PATCH /api/v1/computer

Picks the colour the workspace's computer wears: its picture in Troopy, and its screen's wallpaper from the computer's next start. Setup asks for it once the computer is launching. Needs a launched computer and an owner or admin.

• CLI: troopy computer update. MCP tool: troopy_update_computer
• Scopes: organization:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "status": "ready",
    "steps": [
      {
        "id": "computer",
        "label": "Setting up your computer",
        "state": "done"
      },
      {
        "id": "tools",
        "label": "Installing AI tools",
        "state": "done"
      }
    ],
    "error": null,
    "color": "tangerine",
    "connection": {
      "provider": "chatgpt",
      "method": "device_code",
      "status": "pending",
      "userCode": "VHSQ-DCS73",
      "verificationUrl": "https://auth.openai.com/codex/device",
      "expiresAt": "2026-09-01T09:15:00.000Z",
      "keyHint": null,
      "connectedAt": null,
      "error": null,
      "limitedUntil": null,
      "lapsedAt": null
    },
    "statusUrl": "https://troopy.ai/api/v1/computer"
  }
}

Reset setup

DELETE /api/v1/computer

Deletes the workspace's computer and everything on it, with every sign-in there, so its setup launches it again. The organization's AI plans stay. Cannot be undone. Needs an owner or admin.

• CLI: troopy computer reset
• Scopes: organization:write
• At most 5 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "reset": true
  }
}

Connect the AI plan

POST /api/v1/computer/connection

Signs one of the organization's AI plans in on the workspace's computer. Plans with method api_key take apiKey, which Troopy checks with the provider and stores only on the computer. Plans with method device_code take nothing and answer with a userCode to approve at verificationUrl; poll GET /ai-plans until the plan is connected. Plans with method paste_code take nothing and answer with a verificationUrl to sign in at; call again with the code the provider shows there. Needs a launched computer and an owner or admin.

• CLI: troopy ai connect. MCP tool: troopy_connect_ai
• Scopes: organization:write
• At most 10 calls per 60 seconds per key

{
  "data": {
    "provider": "chatgpt",
    "method": "device_code",
    "status": "pending",
    "userCode": "VHSQ-DCS73",
    "verificationUrl": "https://auth.openai.com/codex/device",
    "expiresAt": "2026-09-01T09:15:00.000Z",
    "keyHint": null,
    "connectedAt": null,
    "error": null,
    "limitedUntil": null,
    "lapsedAt": null
  }
}

Disconnect the AI plan

DELETE /api/v1/computer/connection

Signs the AI plan out of the workspace's computer and removes its key or tokens there. The teammates of the workspace stop until it is connected again. Needs an owner or admin.

• CLI: troopy ai disconnect. MCP tool: troopy_disconnect_ai
• Scopes: organization:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "provider": "chatgpt",
    "method": "device_code",
    "status": "none",
    "userCode": null,
    "verificationUrl": null,
    "expiresAt": null,
    "keyHint": null,
    "connectedAt": null,
    "error": null,
    "limitedUntil": null,
    "lapsedAt": null
  }
}

Open the computer's screen

POST /api/v1/computer/desktop

A link to the workspace's computer screen, to watch its teammates work and take over the mouse and keyboard, for instance to sign in to a site. Every teammate has its own browser on it, with its own sign-ins; name one in agent to bring its window to the front. The link carries its own access token: whoever has it controls the computer, so treat it as a secret and never log it. The default is a 60 fps stream that can be embedded; vnc true asks for a slower view that works on strict networks and must open as a page of its own. preparing true means the screen is still being set up: call again in a few seconds. Boots a stopped computer first, which can take up to two minutes. Needs an owner or admin.

• CLI: troopy computer desktop
• Scopes: organization:write
• At most 20 calls per 60 seconds per key

{
  "data": {
    "url": "https://boat.dev/desktop/bx_f7k2q9hd#token=...",
    "preparing": false
  }
}

List an AI plan's models

GET /api/v1/ai-plans/{plan}/models

The models teammates can run on with this plan, and the efforts each takes, for PATCH /agents/{handle} and PATCH /ai-plans/{plan} (model, effort). A ChatGPT plan offers what its signed-in account may use, read on the workspace's computer (empty until the plan has run there once). A Claude plan offers Claude's current models. A plan with an API key offers the chat models that its provider lists for the key, read on the workspace's computer. Grok and Copilot offer none: they run on the default model of their CLI. `efforts` are the efforts that the plan's default model takes.

• CLI: troopy ai models. MCP tool: troopy_list_ai_models
• Scopes: workspace:read
• At most 30 calls per 60 seconds per key

{
  "data": {
    "plan": "chatgpt",
    "models": [
      {
        "id": "gpt-5.5",
        "name": "GPT-5.5",
        "description": "Strong reasoning for everyday work.",
        "efforts": [
          "low",
          "medium",
          "high",
          "xhigh"
        ]
      }
    ],
    "efforts": [
      "low",
      "medium",
      "high",
      "xhigh"
    ]
  }
}

Get the AI plan's usage

GET /api/v1/computer/connection/usage

How much of its AI plan the organization has used: the account it is signed in as, each usage window with the share used and when it resets, and whether it is out of usage. Read on the workspace's computer, where the plan's credentials stay, and kept for up to 5 minutes. Plans Troopy can't read yet answer with supported false. Needs a connected plan.

• CLI: troopy ai usage. MCP tool: troopy_get_ai_usage
• Scopes: workspace:read
• At most 30 calls per 60 seconds per key

{
  "data": {
    "plan": "chatgpt",
    "provider": "chatgpt",
    "supported": true,
    "email": "ada@example.com",
    "tier": "pro",
    "signInExpiresAt": "2026-10-06T10:59:32.000Z",
    "limits": [
      {
        "label": "Weekly limit",
        "usedPercent": 3,
        "resetsAt": "2026-09-30T20:51:01.000Z"
      }
    ],
    "limitReached": false,
    "bankedResets": 2,
    "checkedAt": "2026-09-26T15:10:00.000Z"
  }
}

List the AI plans

GET /api/v1/ai-plans

The organization's AI plans in order, each with how it is signed in on the workspace's computer. Teammates start on the default (the first) and move down the list when a plan is out of usage.

• CLI: troopy ai plans. MCP tool: troopy_list_ai_plans
• Scopes: workspace:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "provider": "chatgpt",
      "method": "device_code",
      "status": "connected",
      "userCode": null,
      "verificationUrl": null,
      "expiresAt": null,
      "keyHint": null,
      "connectedAt": "2026-09-01T09:15:00.000Z",
      "error": null,
      "limitedUntil": null,
      "lapsedAt": null,
      "id": "chatgpt",
      "label": null,
      "name": "ChatGPT",
      "isDefault": true,
      "model": null,
      "effort": null
    }
  ]
}

Add an AI plan

POST /api/v1/ai-plans

Adds a plan to the end of the list, as a fallback (or as the default when it is the first). A provider can be added more than once, one plan per account (three ChatGPT accounts). Connect it next with POST /computer/connection and its id. Needs an owner or admin.

• CLI: troopy ai plans add. MCP tool: troopy_add_ai_plan
• Scopes: organization:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": [
    {
      "provider": "chatgpt",
      "method": "device_code",
      "status": "connected",
      "userCode": null,
      "verificationUrl": null,
      "expiresAt": null,
      "keyHint": null,
      "connectedAt": "2026-09-01T09:15:00.000Z",
      "error": null,
      "limitedUntil": null,
      "lapsedAt": null,
      "id": "chatgpt",
      "label": null,
      "name": "ChatGPT · Account 1",
      "isDefault": true,
      "model": null,
      "effort": null
    },
    {
      "provider": "chatgpt",
      "method": "device_code",
      "status": "none",
      "userCode": null,
      "verificationUrl": null,
      "expiresAt": null,
      "keyHint": null,
      "connectedAt": null,
      "error": null,
      "limitedUntil": null,
      "lapsedAt": null,
      "id": "chatgpt-3f9a1c",
      "label": "Work",
      "name": "ChatGPT · Work",
      "isDefault": false,
      "model": null,
      "effort": null
    }
  ]
}

Order the AI plans

PATCH /api/v1/ai-plans

Puts the plans in a new order: the first becomes the default, the rest are fallbacks tried in that order. Send every plan on the list, each once. Needs an owner or admin.

• CLI: troopy ai plans order. MCP tool: troopy_order_ai_plans
• Scopes: organization:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": [
    {
      "provider": "chatgpt",
      "method": "device_code",
      "status": "connected",
      "userCode": null,
      "verificationUrl": null,
      "expiresAt": null,
      "keyHint": null,
      "connectedAt": "2026-09-01T09:15:00.000Z",
      "error": null,
      "limitedUntil": null,
      "lapsedAt": null,
      "id": "chatgpt",
      "label": null,
      "name": "ChatGPT",
      "isDefault": true,
      "model": null,
      "effort": null
    }
  ]
}

Set an AI plan's model

PATCH /api/v1/ai-plans/{plan}

Sets the model and the effort that teammates use on this plan when they pick none, from GET /ai-plans/{plan}/models. Send either or both. Null goes back to the default of the plan's CLI. On a plan with an API key, null takes the model that Troopy picks from the list of its provider at the next round. A teammate's own model and effort come first (PATCH /agents/{handle}). A new model that doesn't take the effort goes back to its default effort. Needs an owner or admin.

• CLI: troopy ai plans set-model. MCP tool: troopy_update_ai_plan
• Scopes: organization:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": [
    {
      "provider": "chatgpt",
      "method": "device_code",
      "status": "connected",
      "userCode": null,
      "verificationUrl": null,
      "expiresAt": null,
      "keyHint": null,
      "connectedAt": "2026-09-01T09:15:00.000Z",
      "error": null,
      "limitedUntil": null,
      "lapsedAt": null,
      "id": "chatgpt",
      "label": null,
      "name": "ChatGPT",
      "isDefault": true,
      "model": "gpt-5.5",
      "effort": "high"
    }
  ]
}

Remove an AI plan

DELETE /api/v1/ai-plans/{plan}

Takes a plan off the list and signs it out of the computer of every workspace. The last plan can't be removed. Needs an owner or admin.

• CLI: troopy ai plans remove
• Scopes: organization:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": [
    {
      "provider": "chatgpt",
      "method": "device_code",
      "status": "connected",
      "userCode": null,
      "verificationUrl": null,
      "expiresAt": null,
      "keyHint": null,
      "connectedAt": "2026-09-01T09:15:00.000Z",
      "error": null,
      "limitedUntil": null,
      "lapsedAt": null,
      "id": "chatgpt",
      "label": null,
      "name": "ChatGPT",
      "isDefault": true,
      "model": null,
      "effort": null
    }
  ]
}

Search the brain

GET /api/v1/brain/search

Searches the workspace's brain by keyword and by meaning at once, and returns the best docs (interviews and research reports too) and sources with a snippet each. A person's search also finds their own private notes (private: true). Start here before answering anything about the business.

• CLI: troopy brain search. MCP tool: troopy_search_brain
• Scopes: brain:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "type": "doc",
      "id": "acme-ltd",
      "title": "Acme Ltd",
      "kind": "company",
      "snippet": "Orders every Monday; pays on 30-day terms.",
      "uri": null,
      "score": 0.032,
      "at": "2026-09-01T09:00:00.000Z",
      "private": false
    }
  ]
}

List docs

GET /api/v1/docs

The workspace's docs, most recently changed first or by name: of one kind, in one folder, or the archived ones. Archived docs are left out unless you ask for them.

• CLI: troopy docs list. MCP tool: troopy_list_docs
• Scopes: brain:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "slug": "acme-ltd",
      "kind": "company",
      "title": "Acme Ltd",
      "version": 3,
      "folder": "Customers",
      "pinned": false,
      "archived": false,
      "support": false,
      "properties": [],
      "cover": null,
      "research": null,
      "createdBy": {
        "type": "agent",
        "id": "6650c0ffee0000000000000b",
        "name": "Chief of Staff"
      },
      "updatedBy": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "createdAt": "2026-08-20T09:00:00.000Z",
      "updatedAt": "2026-09-01T09:00:00.000Z",
      "preview": "Our biggest wholesale customer. Orders every Monday; pays on 30-day terms."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Read a doc

GET /api/v1/docs/{slug}

One doc: its text (body), its dated timeline and its version, which an update must send back. view=text gives the text a part at a time (about 4,000 characters) and the newest 10 lines of its timeline: nextOffset says where to read on. A link to /documents/<slug> in a message names a doc by its slug.

• CLI: troopy docs get. MCP tool: troopy_get_doc
• Scopes: brain:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "slug": "acme-ltd",
    "kind": "company",
    "title": "Acme Ltd",
    "version": 3,
    "folder": "Customers",
    "pinned": false,
    "archived": false,
    "support": false,
    "properties": [],
    "cover": null,
    "research": null,
    "createdBy": {
      "type": "agent",
      "id": "6650c0ffee0000000000000b",
      "name": "Chief of Staff"
    },
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-08-20T09:00:00.000Z",
    "updatedAt": "2026-09-01T09:00:00.000Z",
    "length": 74,
    "nextOffset": null,
    "body": "Our biggest wholesale customer. Orders every Monday; pays on 30-day terms.",
    "timeline": [
      {
        "at": "2026-09-01T09:00:00.000Z",
        "text": "Moved from 14-day to 30-day payment terms.",
        "sourceId": null,
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        }
      }
    ],
    "source": null,
    "shared": false,
    "sources": []
  }
}

Create a doc

POST /api/v1/docs

Adds a doc: a document, a record about one person, company or product, or an interview. Search first so you don't duplicate one. Without a slug, one is made from the title. A folder that does not exist yet is made. A document takes the values of the properties of its collection (GET /doc-fields), by their ids. A record has no properties. A teammate never sets properties.

• CLI: troopy docs create. MCP tool: troopy_create_doc
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "slug": "acme-ltd",
    "kind": "company",
    "title": "Acme Ltd",
    "version": 1,
    "folder": "Customers",
    "pinned": false,
    "archived": false,
    "support": false,
    "properties": [],
    "cover": null,
    "research": null,
    "createdBy": {
      "type": "agent",
      "id": "6650c0ffee0000000000000b",
      "name": "Chief of Staff"
    },
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-08-20T09:00:00.000Z",
    "updatedAt": "2026-09-01T09:00:00.000Z",
    "length": 74,
    "nextOffset": null,
    "body": "Our biggest wholesale customer. Orders every Monday; pays on 30-day terms.",
    "timeline": [],
    "source": null,
    "shared": false,
    "sources": []
  }
}

Rewrite a doc

PATCH /api/v1/docs/{slug}

Rewrites a doc's title, kind, body or some of its properties. Send the version you read; if the doc changed since, this answers 409 stale_version. The old text and properties stay in the doc's history. To record a new fact with its date, add a timeline entry instead. A teammate never sets properties.

• CLI: troopy docs edit. MCP tool: troopy_update_doc
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "slug": "acme-ltd",
    "kind": "company",
    "title": "Acme Ltd",
    "version": 4,
    "folder": "Customers",
    "pinned": false,
    "archived": false,
    "support": false,
    "properties": [],
    "cover": null,
    "research": null,
    "createdBy": {
      "type": "agent",
      "id": "6650c0ffee0000000000000b",
      "name": "Chief of Staff"
    },
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-08-20T09:00:00.000Z",
    "updatedAt": "2026-09-01T09:00:00.000Z",
    "length": 74,
    "nextOffset": null,
    "body": "Our biggest wholesale customer. Orders every Monday; pays on 30-day terms.",
    "timeline": [
      {
        "at": "2026-09-01T09:00:00.000Z",
        "text": "Moved from 14-day to 30-day payment terms.",
        "sourceId": null,
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        }
      }
    ],
    "source": null,
    "shared": false,
    "sources": []
  }
}

Add to a doc's timeline

POST /api/v1/docs/{slug}/timeline

Records something that happened, with its date, under a doc. Timelines are never edited, only added to, so they keep the history the text leaves out. Cite the source it came from when there is one.

• CLI: troopy docs log. MCP tool: troopy_add_doc_timeline_entry
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "slug": "acme-ltd",
    "kind": "company",
    "title": "Acme Ltd",
    "version": 3,
    "folder": "Customers",
    "pinned": false,
    "archived": false,
    "support": false,
    "properties": [],
    "cover": null,
    "research": null,
    "createdBy": {
      "type": "agent",
      "id": "6650c0ffee0000000000000b",
      "name": "Chief of Staff"
    },
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-08-20T09:00:00.000Z",
    "updatedAt": "2026-09-01T09:00:00.000Z",
    "length": 74,
    "nextOffset": null,
    "body": "Our biggest wholesale customer. Orders every Monday; pays on 30-day terms.",
    "timeline": [
      {
        "at": "2026-09-01T09:00:00.000Z",
        "text": "Moved from 14-day to 30-day payment terms.",
        "sourceId": null,
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        }
      }
    ],
    "source": null,
    "shared": false,
    "sources": []
  }
}

Add an image to a doc

POST /api/v1/docs/{slug}/images

Stores an image for a doc's text: PNG, JPEG, GIF or WebP, as base64, up to 10 MB. Returns its url: put `` in the doc's body to show it. Images are private and download with your key; deleting the doc deletes them.

• CLI: troopy docs add-image
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "url": "/api/docs/acme-ltd/images/0b6f3a52-1c1e-4b8e-9d55-2f7f0f0e6a11.png",
    "contentType": "image/png",
    "size": 8
  }
}

A doc's history

GET /api/v1/docs/{slug}/versions

The versions of a doc, newest first, with no text: who wrote each one and when, its name, and whether it is a restore. The first is the doc as it is now. A version is the end of one sitting of one author, or one write of a teammate or the API.

• CLI: troopy docs history. MCP tool: troopy_list_doc_versions
• Scopes: brain:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "version": 2,
      "title": "Acme Ltd",
      "kind": "company",
      "by": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "editedAt": "2026-09-01T09:00:00.000Z",
      "name": null,
      "restoredFrom": null,
      "current": false
    }
  ],
  "more": false
}

One version of a doc

GET /api/v1/docs/{slug}/versions/{version}

One version of a doc with its text and properties, and the version before it, to see what it changed.

• CLI: troopy docs version. MCP tool: troopy_get_doc_version
• Scopes: brain:read
• At most 60 calls per 60 seconds per key

{
  "data": {
    "version": 2,
    "title": "Acme Ltd",
    "kind": "company",
    "by": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "editedAt": "2026-09-01T09:00:00.000Z",
    "name": null,
    "restoredFrom": null,
    "current": false,
    "body": "Our biggest wholesale customer.",
    "properties": [],
    "before": null
  }
}

Name a version of a doc

PATCH /api/v1/docs/{slug}/versions/{version}

Gives a version of a doc a name, or takes it away with an empty name. A named version stays in the history for good. To name the doc as it is now keeps it as a version at once.

• CLI: troopy docs name-version. MCP tool: troopy_name_doc_version
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "version": 2,
    "title": "Acme Ltd",
    "kind": "company",
    "by": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "editedAt": "2026-09-01T09:00:00.000Z",
    "name": "Sent to legal",
    "restoredFrom": null,
    "current": false
  }
}

Revert a doc

POST /api/v1/docs/{slug}/revert

Puts an earlier version's title, kind and text back, as a new version that names the version it restored. The text that it replaces stays in the history, so the revert can itself be undone. The timeline is untouched.

• CLI: troopy docs revert. MCP tool: troopy_revert_doc
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "slug": "acme-ltd",
    "kind": "company",
    "title": "Acme Ltd",
    "version": 4,
    "folder": "Customers",
    "pinned": false,
    "archived": false,
    "support": false,
    "properties": [],
    "cover": null,
    "research": null,
    "createdBy": {
      "type": "agent",
      "id": "6650c0ffee0000000000000b",
      "name": "Chief of Staff"
    },
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-08-20T09:00:00.000Z",
    "updatedAt": "2026-09-01T09:00:00.000Z",
    "length": 74,
    "nextOffset": null,
    "body": "Our biggest wholesale customer. Orders every Monday; pays on 30-day terms.",
    "timeline": [
      {
        "at": "2026-09-01T09:00:00.000Z",
        "text": "Moved from 14-day to 30-day payment terms.",
        "sourceId": null,
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        }
      }
    ],
    "source": null,
    "shared": false,
    "sources": []
  }
}

Delete a doc

DELETE /api/v1/docs/{slug}

Deletes a doc, its history and its search entries. Cannot be undone. Needs an owner or admin, or the person who made the doc. To keep a doc out of sight and out of search, archive it instead (PATCH /docs/{slug}/place).

• CLI: troopy docs delete
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "deleted": true
  }
}

List a doc's comments

GET /api/v1/docs/{slug}/comments

The comments at the foot of a doc, the oldest first: those of people, and the answers of the teammates they asked.

• CLI: troopy docs comments. MCP tool: troopy_list_doc_comments
• Scopes: brain:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee0000000000003d",
      "by": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "text": "@chief can you add the new terms?",
      "quote": "pays on 30-day terms",
      "asked": [
        {
          "handle": "chief",
          "name": "Athena",
          "threadId": "6650c0ffee00000000000011",
          "error": null
        }
      ],
      "replyTo": null,
      "threadId": null,
      "createdAt": "2026-09-01T09:30:00.000Z"
    }
  ]
}

Comment on a doc

POST /api/v1/docs/{slug}/comments

Adds a comment at the foot of a doc. quote names the words of the doc that it is about. A comment that @mentions a teammate (3 at most) asks it: a conversation starts with the doc attached, and the reply of its run comes back as the teammate's comment. Asking a teammate needs agents:write, and the scopes that its tools use.

• CLI: troopy docs comment. MCP tool: troopy_comment_on_doc
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000003d",
    "by": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "text": "@chief can you add the new terms?",
    "quote": "pays on 30-day terms",
    "asked": [
      {
        "handle": "chief",
        "name": "Athena",
        "threadId": "6650c0ffee00000000000011",
        "error": null
      }
    ],
    "replyTo": null,
    "threadId": null,
    "createdAt": "2026-09-01T09:30:00.000Z"
  }
}

Delete a comment of a doc

DELETE /api/v1/docs/{slug}/comments/{id}

Deletes a comment, and the answers of the teammates that it asked. Its author, owners and admins. A teammate's answer: owners, admins and whoever asked for it.

• CLI: troopy docs uncomment
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "deleted": true
  }
}

Change one passage of a doc

POST /api/v1/docs/{slug}/edits

Changes one passage of a doc, as a new version that keeps the history: the exact words of find become replace. find must name one place of the text, or all changes each place. version is the one you read: a doc that changed since refuses it. For a long doc, send the passage, not the whole text.

• CLI: troopy docs replace. MCP tool: troopy_replace_in_doc
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "slug": "acme-ltd",
    "kind": "company",
    "title": "Acme Ltd",
    "version": 4,
    "folder": "Customers",
    "pinned": false,
    "archived": false,
    "support": false,
    "properties": [],
    "cover": null,
    "research": null,
    "createdBy": {
      "type": "agent",
      "id": "6650c0ffee0000000000000b",
      "name": "Chief of Staff"
    },
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-08-20T09:00:00.000Z",
    "updatedAt": "2026-09-01T09:00:00.000Z",
    "length": 74,
    "nextOffset": null,
    "body": "Our biggest wholesale customer. Orders every Monday; pays on 45-day terms.",
    "timeline": [
      {
        "at": "2026-09-01T09:00:00.000Z",
        "text": "Moved from 14-day to 30-day payment terms.",
        "sourceId": null,
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        }
      }
    ],
    "source": null,
    "shared": false,
    "sources": [],
    "replaced": 1
  }
}

Share a doc with a link

PATCH /api/v1/docs/{slug}/share

Gives a doc a read-only guest link that people without an account can open: the title, the text and the dated notes, with no names. on false takes the link away, and reset gives a new one, so the old one stops working. Whoever made the doc, owners and admins.

• CLI: troopy docs share
• Scopes: brain:write
• At most 30 calls per 60 seconds per key

{
  "data": {
    "share": "https://troopy.ai/share/docs/6650c0ffee0000000000003b/k3yZ...Q"
  }
}

Show a doc to the support bot

PATCH /api/v1/docs/{slug}/support

Lets the public support bot tell visitors what a doc says (on true), or stops that (on false). The bot reads nothing else of the brain except the pages of the business's own website, so a doc is off until a person turns it on. Whoever made the doc, owners and admins decide. A record of a person or of a company never goes to the bot.

• CLI: troopy docs support
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "support": true
  }
}

List Notion pages to import as docs

GET /api/v1/doc-imports/notion

The pages the workspace gave Troopy when it connected Notion, most recently edited first, each with the slug of the doc it became if it was imported. Connecting Notion (owners and admins, in Settings > Apps) is where people pick which pages.

• CLI: troopy docs notion-pages. MCP tool: troopy_list_doc_notion_pages
• Scopes: brain:write
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
      "title": "Refund policy",
      "url": "https://www.notion.so/Refund-policy-1f2e3d4c5b6a47988a7b6c5d4e3f2a1b",
      "editedAt": "2026-09-20T10:00:00.000Z",
      "imported": null
    }
  ]
}

Import a doc

POST /api/v1/doc-imports

Imports a Notion page (by its id, from the workspace's Notion connection) or a Google Doc (by its file id, with the access token Google's Picker gave for it, used once and never kept) as a new doc, its images copied into Troopy. As an interview, the columns of a Notion database row become its properties. Each document imports once: a second time says which doc it already is.

• CLI: troopy docs import. MCP tool: troopy_import_doc
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "slug": "acme-ltd",
    "kind": "doc",
    "title": "Acme Ltd",
    "version": 3,
    "folder": "Customers",
    "pinned": false,
    "archived": false,
    "support": false,
    "properties": [],
    "cover": null,
    "research": null,
    "createdBy": {
      "type": "agent",
      "id": "6650c0ffee0000000000000b",
      "name": "Chief of Staff"
    },
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-08-20T09:00:00.000Z",
    "updatedAt": "2026-09-01T09:00:00.000Z",
    "length": 74,
    "nextOffset": null,
    "body": "Our biggest wholesale customer. Orders every Monday; pays on 30-day terms.",
    "timeline": [
      {
        "at": "2026-09-01T09:00:00.000Z",
        "text": "Moved from 14-day to 30-day payment terms.",
        "sourceId": null,
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        }
      }
    ],
    "source": {
      "kind": "notion",
      "id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
      "url": "https://www.notion.so/Refund-policy-1f2e3d4c5b6a47988a7b6c5d4e3f2a1b"
    },
    "shared": false,
    "sources": []
  }
}

File, pin or archive a doc

PATCH /api/v1/docs/{slug}/place

Puts a doc in a folder (by its name, made when it is new) or unfiles it (null), pins it to the top of Docs, or archives it. An archived doc is out of Docs and out of search until it is restored (archived: false). None of these changes its text or its version.

• CLI: troopy docs place. MCP tool: troopy_place_doc
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "slug": "acme-ltd",
    "kind": "company",
    "title": "Acme Ltd",
    "version": 3,
    "folder": "Customers",
    "pinned": true,
    "archived": false,
    "support": false,
    "properties": [],
    "cover": null,
    "research": null,
    "createdBy": {
      "type": "agent",
      "id": "6650c0ffee0000000000000b",
      "name": "Chief of Staff"
    },
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-08-20T09:00:00.000Z",
    "updatedAt": "2026-09-01T09:00:00.000Z",
    "preview": "Our biggest wholesale customer. Orders every Monday; pays on 30-day terms."
  }
}

List the folders of docs

GET /api/v1/doc-folders

The folders of the workspace's docs, by name, each with how many of its docs are not archived. Folders are one level deep.

• CLI: troopy docs folders. MCP tool: troopy_list_doc_folders
• Scopes: brain:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee0000000000003c",
      "name": "Customers",
      "docs": 4
    }
  ]
}

Add a folder of docs

POST /api/v1/doc-folders

Adds a folder for docs. A folder of the same name, whatever its case, is the one you get. A workspace keeps 50 folders at most.

• CLI: troopy docs add-folder
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000003c",
    "name": "Customers",
    "docs": 0
  }
}

Rename a folder of docs

PATCH /api/v1/doc-folders/{id}

Gives a folder of docs a new name. Its docs stay in it.

• CLI: troopy docs rename-folder
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000003c",
    "name": "Clients",
    "docs": 4
  }
}

Remove a folder of docs

DELETE /api/v1/doc-folders/{id}

Removes a folder of docs. Its docs stay, unfiled.

• CLI: troopy docs remove-folder
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "deleted": true
  }
}

List the properties of docs

GET /api/v1/doc-fields

The properties that the docs of one collection can have, in order, with the choices of each select. A doc keeps its values by the id of each property.

• CLI: troopy docs fields. MCP tool: troopy_list_doc_fields
• Scopes: brain:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee00000000000065",
      "collection": "docs",
      "name": "Stage",
      "type": "select",
      "options": [
        {
          "id": "6650c0ffee00000000000075",
          "name": "Customer",
          "color": "mint"
        },
        {
          "id": "6650c0ffee00000000000076",
          "name": "Lead",
          "color": "sky"
        }
      ],
      "position": 0
    }
  ]
}

Add a property to docs

POST /api/v1/doc-fields

Adds a property that every doc of one collection can have, at the end. A select or multi_select takes its choices. Names are unique in a collection. A collection has 30 properties at most.

• CLI: troopy docs add-field. MCP tool: troopy_create_doc_field
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000065",
    "collection": "docs",
    "name": "Stage",
    "type": "select",
    "options": [
      {
        "id": "6650c0ffee00000000000075",
        "name": "Customer",
        "color": "mint"
      },
      {
        "id": "6650c0ffee00000000000076",
        "name": "Lead",
        "color": "sky"
      }
    ],
    "position": 0
  }
}

Change a property of docs

PATCH /api/v1/doc-fields/{id}

Renames a property, moves it, or changes a select's choices: send all of them, in order. An id keeps a choice. A choice left out goes from every doc. Its type and its collection never change: add a new property instead.

• CLI: troopy docs update-field. MCP tool: troopy_update_doc_field
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000065",
    "collection": "docs",
    "name": "Status",
    "type": "select",
    "options": [
      {
        "id": "6650c0ffee00000000000075",
        "name": "Customer",
        "color": "mint"
      },
      {
        "id": "6650c0ffee00000000000076",
        "name": "Lead",
        "color": "sky"
      }
    ],
    "position": 0
  }
}

Delete a property of docs

DELETE /api/v1/doc-fields/{id}

Removes a property and its value from every doc of its collection, for good. The history of a doc keeps the values that it had.

• CLI: troopy docs delete-field
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "deleted": true
  }
}

Get the memory files

GET /api/v1/memory

What every teammate reads before it works, besides its own files: the workspace's shared files (company, contacts, glossary, troop, voice, email) and your own About you (about), which only you see and which is read whenever you ask a teammate for something.

• CLI: troopy memory get. MCP tool: troopy_get_memory
• Scopes: brain:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "file": "company",
      "name": "Company",
      "about": "The business in one place.",
      "text": "# Lovelace Bakery\n\n- Sourdough, wholesale to cafes in Leeds.",
      "max": 10000,
      "updatedBy": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "updatedAt": "2026-09-01T09:00:00.000Z"
    }
  ]
}

Rewrite a memory file

PATCH /api/v1/memory/{file}

Replaces a memory file's whole text, in markdown, at most 10,000 characters. Shared files change what every teammate reads, so keep the most important lines first. about writes your own About you. When a teammate calls this, it waits for a person's approval.

• CLI: troopy memory update. MCP tool: troopy_update_memory_file
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "file": "voice",
    "name": "Voice",
    "about": "How the business sounds.",
    "text": "# Voice\n\n- Warm, plain, no exclamation marks.",
    "max": 10000,
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "updatedAt": "2026-09-01T09:00:00.000Z"
  }
}

Get the brand

GET /api/v1/brand

The brand of the business, as Brain > Brand keeps it: its logos, colours, fonts, tagline, call to action and picture style, and who set each part. The cards of teammates are in its colours and fonts, with its logo, and art takes its picture style.

• CLI: troopy brand get. MCP tool: troopy_get_brand
• Scopes: brain:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "name": "Analytical Engines",
    "website": "https://example.com",
    "logo": "https://cdn.example.com/workspaces/6650c0ffee00000000000002/logo.png",
    "logoDark": null,
    "colors": {
      "background": "#0e0e10",
      "text": "#f4f4f5",
      "accent": "#ad5cff"
    },
    "fonts": {
      "heading": "inter",
      "body": "inter"
    },
    "grain": false,
    "tagline": "Engines that think in numbers.",
    "why": "It works out a table of numbers in an hour, with no mistakes, where clerks take a week.",
    "audience": "Banks, insurers and observatories that print tables of numbers.",
    "notFor": "Someone who adds a few numbers once a month.",
    "cta": {
      "label": "Book a demo",
      "url": "https://example.com/demo"
    },
    "pictures": "Near-black rooms, brass and violet light, machines up close. No faces, no logos.",
    "read": {
      "status": "done",
      "url": "https://example.com/",
      "at": "2026-10-16T08:58:00.000Z",
      "error": null,
      "colors": [
        "#0e0e10",
        "#f4f4f5",
        "#ad5cff"
      ],
      "fonts": {
        "heading": "Inter, sans-serif",
        "body": "Inter, sans-serif"
      }
    },
    "set": {
      "colors": {
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        },
        "at": "2026-10-16T09:00:00.000Z",
        "from": "person"
      }
    },
    "competitors": [
      {
        "id": "6650c0ffee00000000000071",
        "name": "Difference Engines",
        "site": "difference.example",
        "note": "They sell machines. We sell the answers.",
        "watch": true,
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        },
        "at": "2026-10-16T09:05:00.000Z"
      }
    ],
    "suggested": [],
    "finding": null
  }
}

Read the brand from the website

POST /api/v1/brand/read

Troopy opens the business's website in the lead's browser on the computer, and reads its colours, fonts and icon. They fill each part of the brand that no person set, and the icon becomes the logo when there is none. Then the lead drafts the empty lines: the tagline, the call to action and the picture style. It answers at once with the read under way: GET /brand shows how it goes. A workspace reads its site 3 times an hour.

• CLI: troopy brand read. MCP tool: troopy_read_brand
• Scopes: brain:write
• At most 3 calls per 3600 seconds per key

{
  "data": {
    "name": "Analytical Engines",
    "website": "https://example.com",
    "logo": "https://cdn.example.com/workspaces/6650c0ffee00000000000002/logo.png",
    "logoDark": null,
    "colors": {
      "background": "#0e0e10",
      "text": "#f4f4f5",
      "accent": "#ad5cff"
    },
    "fonts": {
      "heading": "inter",
      "body": "inter"
    },
    "grain": false,
    "tagline": "Engines that think in numbers.",
    "why": "It works out a table of numbers in an hour, with no mistakes, where clerks take a week.",
    "audience": "Banks, insurers and observatories that print tables of numbers.",
    "notFor": "Someone who adds a few numbers once a month.",
    "cta": {
      "label": "Book a demo",
      "url": "https://example.com/demo"
    },
    "pictures": "Near-black rooms, brass and violet light, machines up close. No faces, no logos.",
    "read": {
      "status": "done",
      "url": "https://example.com/",
      "at": "2026-10-16T08:58:00.000Z",
      "error": null,
      "colors": [
        "#0e0e10",
        "#f4f4f5",
        "#ad5cff"
      ],
      "fonts": {
        "heading": "Inter, sans-serif",
        "body": "Inter, sans-serif"
      }
    },
    "set": {
      "colors": {
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        },
        "at": "2026-10-16T09:00:00.000Z",
        "from": "person"
      }
    },
    "competitors": [
      {
        "id": "6650c0ffee00000000000071",
        "name": "Difference Engines",
        "site": "difference.example",
        "note": "They sell machines. We sell the answers.",
        "watch": true,
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        },
        "at": "2026-10-16T09:05:00.000Z"
      }
    ],
    "suggested": [],
    "finding": null
  }
}

Add a competitor

POST /api/v1/brand/competitors

Adds a competitor of the business. Teammates may read the pages of its site, and never type on them. The Competitor watcher checks it each week while watch is on. Its own site, a site that it has already, and a site that many businesses share (such as facebook.com) are refused. A workspace keeps 30 competitors. A suggestion with the same site goes from the suggestions.

• CLI: troopy brand competitor-add. MCP tool: troopy_add_competitor
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000071",
    "name": "Difference Engines",
    "site": "difference.example",
    "note": "They sell machines. We sell the answers.",
    "watch": true,
    "by": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "at": "2026-10-16T09:05:00.000Z"
  }
}

Change a competitor

PATCH /api/v1/brand/competitors/{id}

Changes the name of a competitor, how the business differs from it, or whether the Competitor watcher checks it. Send only what changes.

• CLI: troopy brand competitor-set. MCP tool: troopy_update_competitor
• Scopes: brain:write
• At most 60 calls per 60 seconds per key

{
  "data": {
    "id": "6650c0ffee00000000000071",
    "name": "Difference Engines",
    "site": "difference.example",
    "note": "They sell machines. We sell the answers.",
    "watch": false,
    "by": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "at": "2026-10-16T09:05:00.000Z"
  }
}

Remove a competitor

DELETE /api/v1/brand/competitors/{id}

Removes a competitor. Teammates no longer read its site, unless a person names it. Its docs stay.

• CLI: troopy brand competitor-delete
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "deleted": true
  }
}

Suggest a competitor

POST /api/v1/brand/competitors/suggestions

Suggests a competitor for a person to add. It waits under Suggested in Brain > Brand > Competitors, and counts only after a person adds it. The site of the business, a site that it has as a competitor, a site that a person dismissed, and a site that many businesses share are refused. 20 suggestions wait at most.

• CLI: troopy brand competitor-suggest. MCP tool: troopy_suggest_competitor
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000072",
    "name": "Babbage & Co",
    "site": "babbage.example",
    "why": "Sells calculating engines to the same insurers.",
    "by": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "at": "2026-10-16T09:10:00.000Z"
  }
}

Dismiss a suggested competitor

DELETE /api/v1/brand/competitors/suggestions/{id}

Takes a suggestion away. Its site is not suggested again.

• CLI: troopy brand suggestion-dismiss
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "deleted": true
  }
}

List the pictures of the brand

GET /api/v1/brand/assets

The pictures of the business that teammates may put in its articles and posts: logos, screenshots, photos and graphics, the newest first.

• CLI: troopy brand assets. MCP tool: troopy_list_brand_assets
• Scopes: brain:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee00000000000081",
      "title": "The engine on a desk",
      "kind": "photo",
      "url": "/api/brand/assets/2f0c5a8e-6b1d-4c33-9a57-0e4f6b2d9c11.jpg",
      "contentType": "image/jpeg",
      "size": 182044,
      "width": 1600,
      "height": 900,
      "from": "person",
      "by": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "at": "2026-10-16T09:20:00.000Z"
    }
  ]
}

Add a picture to the brand

POST /api/v1/brand/assets

Adds a picture of the business, for teammates to put in its articles and posts: a PNG, JPEG or WebP image of at most 8 MB, base64-encoded. A workspace keeps 200 pictures. From the CLI, pass --content @./logo.png to read a file.

• CLI: troopy brand asset-add
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000081",
    "title": "The engine on a desk",
    "kind": "photo",
    "url": "/api/brand/assets/2f0c5a8e-6b1d-4c33-9a57-0e4f6b2d9c11.jpg",
    "contentType": "image/jpeg",
    "size": 182044,
    "width": 1600,
    "height": 900,
    "from": "person",
    "by": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "at": "2026-10-16T09:20:00.000Z"
  }
}

Change a picture of the brand

PATCH /api/v1/brand/assets/{id}

Changes what a picture shows, in words, or its kind. Send only what changes.

• CLI: troopy brand asset-set
• Scopes: brain:write
• At most 60 calls per 60 seconds per key

{
  "data": {
    "id": "6650c0ffee00000000000081",
    "title": "The engine on a desk",
    "kind": "graphic",
    "url": "/api/brand/assets/2f0c5a8e-6b1d-4c33-9a57-0e4f6b2d9c11.jpg",
    "contentType": "image/jpeg",
    "size": 182044,
    "width": 1600,
    "height": 900,
    "from": "person",
    "by": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "at": "2026-10-16T09:20:00.000Z"
  }
}

Delete a picture of the brand

DELETE /api/v1/brand/assets/{id}

Deletes a picture of the brand. The copies that teammates put on tasks and in docs stay.

• CLI: troopy brand asset-delete
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "deleted": true
  }
}

Put a picture of the brand on a task

POST /api/v1/tasks/{key}/assets

Copies a picture of the brand onto a task, as asset-N, or as screen-N for a screenshot. A teammate then puts it in a doc, or on the cover of an article. A screenshot shows words, so it never goes on a cover. A task holds 20 files.

• CLI: troopy tasks asset. MCP tool: troopy_use_brand_asset
• Scopes: tasks:write brain:read
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "file": {
      "id": "6650c0ffee00000000000042",
      "name": "asset-1.jpg",
      "contentType": "image/jpeg",
      "size": 182044,
      "by": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "createdAt": "2026-10-16T09:25:00.000Z",
      "url": "https://troopy.ai/api/files/6650c0ffee00000000000042"
    },
    "title": "The engine on a desk"
  }
}

Find competitors

POST /api/v1/brand/competitors/find

Gives the Competitor watcher, or else the Researcher, a task: find the competitors of the business on the web. It suggests each one that it finds, for a person to add. While a search goes on, it answers with the task of that search. 5 an hour.

• CLI: troopy brand competitors-find. MCP tool: troopy_find_competitors
• Scopes: brain:write tasks:write
• At most 5 calls per 3600 seconds per key

{
  "data": {
    "task": "VIR-42"
  }
}

Change the brand

PATCH /api/v1/brand

Changes parts of the brand. Send at least one part. Null takes a part back to the default. The colours and the fonts go together: send all three colours, and both fonts. The logo for a dark background is for owners and admins.

• CLI: troopy brand update. MCP tool: troopy_update_brand
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "name": "Analytical Engines",
    "website": "https://example.com",
    "logo": "https://cdn.example.com/workspaces/6650c0ffee00000000000002/logo.png",
    "logoDark": null,
    "colors": {
      "background": "#0e0e10",
      "text": "#f4f4f5",
      "accent": "#ad5cff"
    },
    "fonts": {
      "heading": "inter",
      "body": "inter"
    },
    "grain": false,
    "tagline": "Engines that think in numbers.",
    "why": "It works out a table of numbers in an hour, with no mistakes, where clerks take a week.",
    "audience": "Banks, insurers and observatories that print tables of numbers.",
    "notFor": "Someone who adds a few numbers once a month.",
    "cta": {
      "label": "Book a demo",
      "url": "https://example.com/demo"
    },
    "pictures": "Near-black rooms, brass and violet light, machines up close. No faces, no logos.",
    "read": {
      "status": "done",
      "url": "https://example.com/",
      "at": "2026-10-16T08:58:00.000Z",
      "error": null,
      "colors": [
        "#0e0e10",
        "#f4f4f5",
        "#ad5cff"
      ],
      "fonts": {
        "heading": "Inter, sans-serif",
        "body": "Inter, sans-serif"
      }
    },
    "set": {
      "colors": {
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        },
        "at": "2026-10-16T09:00:00.000Z",
        "from": "person"
      }
    },
    "competitors": [
      {
        "id": "6650c0ffee00000000000071",
        "name": "Difference Engines",
        "site": "difference.example",
        "note": "They sell machines. We sell the answers.",
        "watch": true,
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        },
        "at": "2026-10-16T09:05:00.000Z"
      }
    ],
    "suggested": [],
    "finding": null
  }
}

Add to the brain

POST /api/v1/brain/sources

Gives the brain text to learn from: a web page, a file's text, a note, or what a teammate did. It becomes searchable at once. Sending the same text again returns the existing source.

• CLI: troopy brain add. MCP tool: troopy_add_brain_source
• Scopes: brain:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000000e",
    "kind": "web",
    "title": "Pricing",
    "uri": "https://example.com/pricing",
    "createdAt": "2026-09-01T09:00:00.000Z",
    "by": {
      "type": "api",
      "id": "6650c0ffee0000000000000f",
      "name": "Ada Lovelace"
    },
    "private": false,
    "saidBy": null,
    "confirmations": 0,
    "supersededBy": null,
    "wrong": null,
    "duplicate": false
  }
}

Add a file to the brain

POST /api/v1/brain/files

Gives the brain a file to learn from: its bytes in content as base64, up to 10 MB. A text file is read as it is, a PDF by its text (not a scan's images) and a Word document (.docx) by its paragraphs; its first 500,000 characters become an upload source, and the file itself isn't kept. Sending the same text again returns the existing source. From the CLI, pass --content @./brief.pdf to read a file.

• CLI: troopy brain add-file
• Scopes: brain:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000000e",
    "kind": "upload",
    "title": "pricing.md",
    "uri": null,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "by": {
      "type": "api",
      "id": "6650c0ffee0000000000000f",
      "name": "Ada Lovelace"
    },
    "private": false,
    "saidBy": null,
    "confirmations": 0,
    "supersededBy": null,
    "wrong": null,
    "duplicate": false
  }
}

List brain sources

GET /api/v1/brain/sources

What the brain has learned from, newest first, optionally of one kind. Read one to get its text.

• CLI: troopy brain sources. MCP tool: troopy_list_brain_sources
• Scopes: brain:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee0000000000000e",
      "kind": "web",
      "title": "Pricing",
      "uri": "https://example.com/pricing",
      "createdAt": "2026-09-01T09:00:00.000Z",
      "by": {
        "type": "api",
        "id": "6650c0ffee0000000000000f",
        "name": "Ada Lovelace"
      },
      "private": false,
      "saidBy": null,
      "confirmations": 0,
      "supersededBy": null,
      "wrong": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Read a brain source

GET /api/v1/brain/sources/{id}

One source with its full text.

• CLI: troopy brain source. MCP tool: troopy_get_brain_source
• Scopes: brain:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "id": "6650c0ffee0000000000000e",
    "kind": "web",
    "title": "Pricing",
    "uri": "https://example.com/pricing",
    "createdAt": "2026-09-01T09:00:00.000Z",
    "by": {
      "type": "api",
      "id": "6650c0ffee0000000000000f",
      "name": "Ada Lovelace"
    },
    "private": false,
    "saidBy": null,
    "confirmations": 0,
    "supersededBy": null,
    "wrong": null,
    "text": "Plans start at $29 a month."
  }
}

Learn a website

POST /api/v1/brain/imports

Reads up to 25 pages of a website, starting at url and staying on its domain, and adds each to the brain as a source. The workspace's computer does the reading, so it must be launched. Answers 202 at once; poll statusUrl until status is done.

• CLI: troopy brain learn. MCP tool: troopy_learn_website
• Scopes: brain:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000010",
    "url": "https://example.com/",
    "status": "running",
    "pages": 0,
    "error": null,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "finishedAt": null,
    "statusUrl": "https://troopy.ai/api/v1/brain/imports/6650c0ffee00000000000010"
  }
}

Check a website import

GET /api/v1/brain/imports/{id}

Where a website import stands, and how many pages the brain learned from it.

• CLI: troopy brain import. MCP tool: troopy_get_brain_import
• Scopes: brain:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "id": "6650c0ffee00000000000010",
    "url": "https://example.com/",
    "status": "done",
    "pages": 12,
    "error": null,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "finishedAt": "2026-09-01T09:01:30.000Z",
    "statusUrl": "https://troopy.ai/api/v1/brain/imports/6650c0ffee00000000000010"
  }
}

Delete a brain source

DELETE /api/v1/brain/sources/{id}

Deletes a source and its search entries. Timeline entries that cite it keep their text. Cannot be undone. Needs an owner or admin, except for your own private notes.

• CLI: troopy brain forget
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "deleted": true
  }
}

Say a note is wrong

POST /api/v1/brain/sources/{id}/wrong

Says a note is wrong, usually one a teammate's answer relied on (cites): it goes out of search, so no teammate finds it again (read by id, it shows the mark), and stays in Memories marked, until someone restores it. Only notes. A note already marked keeps its first mark.

• CLI: troopy brain wrong
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000000e",
    "kind": "note",
    "title": "Ada uses Crisp for support.",
    "uri": null,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "by": {
      "type": "api",
      "id": "6650c0ffee0000000000000f",
      "name": "Ada Lovelace"
    },
    "private": false,
    "saidBy": null,
    "confirmations": 0,
    "supersededBy": null,
    "wrong": {
      "by": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "at": "2026-09-02T10:00:00.000Z",
      "userId": "6650c0ffee0000000000000a"
    },
    "text": "Ada uses Crisp for support."
  }
}

Take back saying a note is wrong

DELETE /api/v1/brain/sources/{id}/wrong

Takes back your own mark on a note you said was wrong: it is back in search unless a newer note replaced it. Someone else's mark is refused with 403; restore the note to clear it.

• CLI: troopy brain unwrong
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000000e",
    "kind": "note",
    "title": "Ada uses Crisp for support.",
    "uri": null,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "by": {
      "type": "api",
      "id": "6650c0ffee0000000000000f",
      "name": "Ada Lovelace"
    },
    "private": false,
    "saidBy": null,
    "confirmations": 0,
    "supersededBy": null,
    "wrong": null,
    "text": "Ada uses Crisp for support."
  }
}

Say whether a note is still true

POST /api/v1/brain/sources/{id}/check

Answers "Still true?" about a note (GET /inbox lists the ones that need you): still_true confirms it (and puts it back in search if it was out), wrong says it is wrong (as POST /brain/sources/{id}/wrong), later asks again after a month if teammates still rely on it. Only notes. From anyone else than the person who said it, still_true confirms it and later does nothing.

• CLI: troopy brain check
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000000e",
    "kind": "note",
    "title": "Ada uses Crisp for support.",
    "uri": null,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "by": {
      "type": "api",
      "id": "6650c0ffee0000000000000f",
      "name": "Ada Lovelace"
    },
    "private": false,
    "saidBy": null,
    "confirmations": 1,
    "supersededBy": null,
    "wrong": null,
    "text": "Ada uses Crisp for support."
  }
}

Restore a replaced note

POST /api/v1/brain/sources/{id}/restore

Puts a note a newer one replaced (supersededBy), or one a person said was wrong, back in search: it was true after all. The newer note stays; delete it if it is wrong. A note that wasn't out of search is returned as it is.

• CLI: troopy brain restore
• Scopes: brain:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000000e",
    "kind": "note",
    "title": "Ada uses Crisp for support.",
    "uri": null,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "by": {
      "type": "api",
      "id": "6650c0ffee0000000000000f",
      "name": "Ada Lovelace"
    },
    "private": false,
    "saidBy": null,
    "confirmations": 0,
    "supersededBy": null,
    "wrong": null,
    "text": "Ada uses Crisp for support."
  }
}

List teammates

GET /api/v1/agents

The workspace's troop, its lead first, with what each is doing now. Every workspace starts with a Chief of Staff (handle chief).

• CLI: troopy agents list. MCP tool: troopy_list_agents
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "handle": "chief",
      "name": "Chief of Staff",
      "role": "chief",
      "title": "Chief of Staff",
      "tagline": "Lead Agent: Runs the troop, plans, delegates",
      "area": "lead",
      "lead": true,
      "avatar": {
        "shape": "mech",
        "color": "#C9B8F0",
        "face": "mouth"
      },
      "status": "idle",
      "needsYou": false,
      "lastActiveAt": "2026-09-01T09:05:00.000Z",
      "doing": null,
      "plan": null,
      "model": null,
      "effort": null
    }
  ]
}

Get a teammate

GET /api/v1/agents/{handle}

One teammate: its role (job, tools, which calls wait for approval, skills, schedule presets, limits), its memory files, and how its runs have gone.

• CLI: troopy agents get. MCP tool: troopy_get_agent
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "handle": "chief",
    "name": "Chief of Staff",
    "role": "chief",
    "title": "Chief of Staff",
    "tagline": "Lead Agent: Runs the troop, plans, delegates",
    "area": "lead",
    "lead": true,
    "avatar": {
      "shape": "mech",
      "color": "#C9B8F0",
      "face": "mouth"
    },
    "status": "idle",
    "needsYou": false,
    "lastActiveAt": "2026-09-01T09:05:00.000Z",
    "doing": null,
    "plan": null,
    "model": null,
    "effort": null,
    "summary": "Your first teammate. Answers from the brain, plans the work and hands it to the right teammate.",
    "job": {
      "goal": "Take work off the owner's plate.",
      "responsibilities": [
        "Answer questions about the business"
      ],
      "done": [
        "The person has an answer"
      ],
      "never": [
        "Invent facts"
      ]
    },
    "tools": [
      {
        "id": "search_brain",
        "label": "Search the brain",
        "approval": false,
        "off": false
      },
      {
        "id": "handoff",
        "label": "Hand work to a teammate",
        "approval": false,
        "off": false
      }
    ],
    "skills": [
      {
        "name": "weekly-brief",
        "title": "Weekly brief",
        "when": "Writing the weekly brief",
        "about": "Writes a short brief each week: what is new, what changed, and what is worth doing."
      }
    ],
    "routinePresets": [
      {
        "name": "Weekly brief",
        "task": "Write this week's brief.",
        "days": [
          1
        ],
        "hour": 8,
        "minute": 0
      }
    ],
    "limits": {
      "rounds": 12,
      "runsPerDay": 200,
      "usdPerRun": 3
    },
    "roleLimits": {
      "rounds": 12,
      "runsPerDay": 200,
      "usdPerRun": 3
    },
    "roleVersion": 2,
    "voice": "cedar",
    "sites": [],
    "needs": [],
    "identity": "# IDENTITY.md\n\n- **Name:** Chief of Staff",
    "personality": "# SOUL.md\n\n## How I work\n\n- I lead with the answer.",
    "notes": "# MEMORY.md\n\n- Wholesale orders close at 4pm.",
    "expertise": [
      "planning",
      "delegation"
    ],
    "starters": [
      "What do you know about our business so far?"
    ],
    "stats": {
      "runs": 8,
      "done": 7,
      "failed": 1,
      "inFlight": 0,
      "waiting": 0,
      "drafts": 1,
      "conversations": 3,
      "successRate": 88
    },
    "createdAt": "2026-09-01T09:00:00.000Z"
  }
}

List a teammate's email

GET /api/v1/agents/{handle}/inbox

The emails that a teammate's own address received and sent, newest first, kept 30 days. Codes and links are masked: a teammate types and opens them by reference, and only owners and admins reveal them, in the app.

• CLI: troopy agents inbox. MCP tool: troopy_list_teammate_email
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee00000000000031",
      "from": "no-reply@canva.com",
      "fromName": "Canva",
      "subject": "[code 1] is your Canva code",
      "receivedAt": "2026-10-01T09:12:00.000Z",
      "checked": true,
      "spam": false,
      "codes": 1,
      "links": [
        {
          "n": 1,
          "site": "canva.com",
          "label": "Verify email"
        }
      ],
      "direction": "in",
      "to": [],
      "status": null,
      "error": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Get a teammate's email settings

GET /api/v1/agents/{handle}/inbox/settings

A teammate's own address, its signature, its daily cap, whether it is paused, and how many emails it sent in the last 24 hours.

• CLI: troopy agents email-settings. MCP tool: troopy_get_teammate_email_settings
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "handle": "social",
    "name": "Social media manager",
    "box": "t-6650c0ffee00000000000021",
    "address": "social-acme@inbox.troopy.ai",
    "fromName": "",
    "signature": "Social media manager at Acme",
    "dailyCap": 25,
    "paused": false,
    "wake": "people",
    "instructions": "Answer suppliers within a day. Pass invoices to the Chief of Staff.",
    "rules": [
      {
        "id": "6650c0ffee00000000000041",
        "kind": "block",
        "value": "spam.example",
        "direction": "in"
      }
    ],
    "deleted": false,
    "sentToday": 3
  }
}

Change a teammate's email settings

PATCH /api/v1/agents/{handle}/inbox

Changes a teammate's own address, its sender name, its signature, its daily cap, which new mail starts it, its handling notes, or pauses it. The address is the part before the @, 3 to 40 letters, digits, dots or hyphens. An address is taken when any teammate has it or had it. The old address still takes mail, so the accounts that the teammate opened with it still reach it. A teammate changes its address at most 5 times. A paused inbox still takes mail, but the teammate neither reads it nor sends from it. Owners and admins only.

• CLI: troopy agents address. MCP tool: troopy_update_teammate_address
• Scopes: agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "handle": "social",
    "name": "Social media manager",
    "box": "t-6650c0ffee00000000000021",
    "address": "social-acme@inbox.troopy.ai",
    "fromName": "",
    "signature": "Social media manager at Acme",
    "dailyCap": 25,
    "paused": false,
    "wake": "people",
    "instructions": "Answer suppliers within a day. Pass invoices to the Chief of Staff.",
    "rules": [
      {
        "id": "6650c0ffee00000000000041",
        "kind": "block",
        "value": "spam.example",
        "direction": "in"
      }
    ],
    "deleted": false,
    "sentToday": 3
  }
}

Get the email domain

GET /api/v1/email/domain

The workspace's own domain for its teammates' addresses, with the DNS records to add and what the latest check found. null on the built-in domain.

• CLI: troopy email-domain show. MCP tool: troopy_get_email_domain
• Scopes: agents:read
• At most 60 calls per 60 seconds per key

{
  "data": {
    "domain": "agents.acme.com",
    "status": "pending",
    "error": "Waiting for the DKIM records and the MX record.",
    "records": [
      {
        "type": "MX",
        "name": "agents.acme.com",
        "value": "inbound-smtp.us-east-2.amazonaws.com",
        "priority": 10,
        "purpose": "inbound",
        "ok": false,
        "optional": false
      }
    ],
    "zone": "acme.com",
    "dnsHost": "Namecheap",
    "zoneMail": [
      {
        "priority": 1,
        "host": "smtp.google.com"
      }
    ],
    "checkedAt": null,
    "verifiedAt": null,
    "createdAt": "2026-10-06T09:00:00.000Z"
  }
}

Connect an email domain

POST /api/v1/email/domain

Connects the workspace's own domain for its teammates' addresses. The answer has the DNS records to add. When the DKIM records and the MX record check out, each teammate moves to handle@domain, and its old address still takes mail. Use a domain or a subdomain that gets no other mail, like agents.acme.com: Troopy refuses a domain whose MX points elsewhere. One domain a workspace. Owners and admins only.

• CLI: troopy email-domain connect. MCP tool: troopy_connect_email_domain
• Scopes: agents:write
• At most 5 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "domain": "agents.acme.com",
    "status": "pending",
    "error": "Waiting for the DKIM records and the MX record.",
    "records": [
      {
        "type": "MX",
        "name": "agents.acme.com",
        "value": "inbound-smtp.us-east-2.amazonaws.com",
        "priority": 10,
        "purpose": "inbound",
        "ok": false,
        "optional": false
      }
    ],
    "zone": "acme.com",
    "dnsHost": "Namecheap",
    "zoneMail": [
      {
        "priority": 1,
        "host": "smtp.google.com"
      }
    ],
    "checkedAt": null,
    "verifiedAt": null,
    "createdAt": "2026-10-06T09:00:00.000Z"
  }
}

Verify the email domain

POST /api/v1/email/domain/verify

Checks the DNS records of the workspace's email domain now. Troopy also checks a domain that waits every 5 minutes, for 3 days. Owners and admins only.

• CLI: troopy email-domain verify. MCP tool: troopy_verify_email_domain
• Scopes: agents:write
• At most 10 calls per 60 seconds per key

{
  "data": {
    "domain": "agents.acme.com",
    "status": "verified",
    "error": null,
    "records": [
      {
        "type": "MX",
        "name": "agents.acme.com",
        "value": "inbound-smtp.us-east-2.amazonaws.com",
        "priority": 10,
        "purpose": "inbound",
        "ok": false,
        "optional": false
      }
    ],
    "zone": "acme.com",
    "dnsHost": "Namecheap",
    "zoneMail": [
      {
        "priority": 1,
        "host": "smtp.google.com"
      }
    ],
    "checkedAt": null,
    "verifiedAt": null,
    "createdAt": "2026-10-06T09:00:00.000Z"
  }
}

Remove the email domain

DELETE /api/v1/email/domain

Removes the workspace's email domain. Each teammate goes back to its address on the built-in domain, and mail to the removed domain stops. Owners and admins only.

• CLI: troopy email-domain remove. MCP tool: troopy_remove_email_domain
• Scopes: agents:write
• At most 5 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "removed": true
  }
}

Add an inbox rule

POST /api/v1/agents/{handle}/inbox/rules

Allows or blocks an email address or a domain, with its subdomains, for the mail that a teammate's address gets (in), sends (out), or both. A block wins. With an allow rule for a direction, only what an allow rule names goes through in that direction. Mail that the rules keep out is not kept. The same rule again changes nothing. Owners and admins only.

• CLI: troopy agents inbox-rule-add. MCP tool: troopy_add_inbox_rule
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "handle": "social",
    "name": "Social media manager",
    "box": "t-6650c0ffee00000000000021",
    "address": "social-acme@inbox.troopy.ai",
    "fromName": "",
    "signature": "Social media manager at Acme",
    "dailyCap": 25,
    "paused": false,
    "wake": "people",
    "instructions": "Answer suppliers within a day. Pass invoices to the Chief of Staff.",
    "rules": [
      {
        "id": "6650c0ffee00000000000041",
        "kind": "block",
        "value": "spam.example",
        "direction": "in"
      }
    ],
    "deleted": false,
    "sentToday": 3
  }
}

Remove an inbox rule

DELETE /api/v1/agents/{handle}/inbox/rules/{id}

Removes one allow or block rule of a teammate's address. Owners and admins only.

• CLI: troopy agents inbox-rule-remove. MCP tool: troopy_remove_inbox_rule
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "handle": "social",
    "name": "Social media manager",
    "box": "t-6650c0ffee00000000000021",
    "address": "social-acme@inbox.troopy.ai",
    "fromName": "",
    "signature": "Social media manager at Acme",
    "dailyCap": 25,
    "paused": false,
    "wake": "people",
    "instructions": "Answer suppliers within a day. Pass invoices to the Chief of Staff.",
    "rules": [],
    "deleted": false,
    "sentToday": 3
  }
}

List the email rules of the workspace

GET /api/v1/email/rules

The allow and block rules of every teammate's inbox in the workspace. They apply beside the rules of each inbox (GET /agents/{handle}/inbox): a block of either wins, and with an allow rule of either for a direction, only what an allow rule names goes through that way.

• CLI: troopy email-rules list. MCP tool: troopy_list_email_rules
• Scopes: agents:read
• At most 60 calls per 60 seconds per key

{
  "data": {
    "rules": [
      {
        "id": "6650c0ffee00000000000042",
        "kind": "allow",
        "value": "acme.com",
        "direction": "in"
      }
    ]
  }
}

Add an email rule for every inbox

POST /api/v1/email/rules

Allows or blocks an email address or a domain, with its subdomains, for every teammate's inbox: the mail that it gets (in), sends (out), or both. With an allow rule for a direction, only what an allow rule names goes through that way, for every teammate. Mail that the rules keep out is not kept. The same rule again changes nothing. Owners and admins only.

• CLI: troopy email-rules add. MCP tool: troopy_add_email_rule
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "rules": [
      {
        "id": "6650c0ffee00000000000042",
        "kind": "allow",
        "value": "acme.com",
        "direction": "in"
      }
    ]
  }
}

Remove an email rule

DELETE /api/v1/email/rules/{id}

Removes one allow or block rule of every teammate's inbox. Owners and admins only.

• CLI: troopy email-rules remove. MCP tool: troopy_remove_email_rule
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "rules": []
  }
}

Delete a teammate's inbox

DELETE /api/v1/agents/{handle}/inbox

Deletes a teammate's inbox and its mail. Mail to its address no longer arrives, and nobody gets the address again. The teammate stays with no address until POST /agents/{handle}/inbox gives it a new one. Owners and admins only.

• CLI: troopy agents inbox-delete
• Scopes: agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "handle": "social",
    "name": "Social media manager",
    "box": "t-6650c0ffee00000000000021",
    "address": "social-acme@inbox.troopy.ai",
    "fromName": "",
    "signature": "Social media manager at Acme",
    "dailyCap": 25,
    "paused": false,
    "wake": "people",
    "instructions": "Answer suppliers within a day. Pass invoices to the Chief of Staff.",
    "rules": [
      {
        "id": "6650c0ffee00000000000041",
        "kind": "block",
        "value": "spam.example",
        "direction": "in"
      }
    ],
    "deleted": true,
    "sentToday": 0
  }
}

Give a teammate a new address

POST /api/v1/agents/{handle}/inbox

Gives a teammate whose inbox a person deleted a new address: its handle on the workspace's own domain, or a new address on the built-in domain. Its old addresses take no mail. Its settings and rules stay. Owners and admins only.

• CLI: troopy agents inbox-restore. MCP tool: troopy_restore_teammate_inbox
• Scopes: agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "handle": "social",
    "name": "Social media manager",
    "box": "t-6650c0ffee00000000000021",
    "address": "social-acme@inbox.troopy.ai",
    "fromName": "",
    "signature": "Social media manager at Acme",
    "dailyCap": 25,
    "paused": false,
    "wake": "people",
    "instructions": "Answer suppliers within a day. Pass invoices to the Chief of Staff.",
    "rules": [
      {
        "id": "6650c0ffee00000000000041",
        "kind": "block",
        "value": "spam.example",
        "direction": "in"
      }
    ],
    "deleted": false,
    "sentToday": 3
  }
}

Send an email from a teammate

POST /api/v1/agents/{handle}/inbox/send

Sends one email now from a teammate's own address, with its signature, to one address or to up to 10 addresses. A teammate sends only from its own address, after an owner or admin says yes. A person who sends must be an owner or admin. Troopy refuses a paused inbox, an address on do-not-contact, and an email for more addresses than the daily cap has left for 24 hours. The answer is the kept email: sent, failed with the reason, or unknown when it possibly went. Troopy does not send an unknown email again.

• CLI: troopy agents send-email
• Scopes: agents:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000032",
    "from": "social-acme@inbox.troopy.ai",
    "fromName": "Social media manager",
    "subject": "Our call",
    "receivedAt": "2026-10-01T09:12:00.000Z",
    "checked": true,
    "spam": false,
    "codes": 0,
    "links": [],
    "direction": "out",
    "to": [
      "jane@brightsmile.example"
    ],
    "status": "sent",
    "error": null
  }
}

Get a teammate's email

GET /api/v1/agents/{handle}/inbox/{id}

One email a teammate received, with its words: every code and link masked, like [code 1] and [link 2: canva.com "Verify email"].

• CLI: troopy agents email. MCP tool: troopy_get_teammate_email
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "id": "6650c0ffee00000000000031",
    "from": "no-reply@canva.com",
    "fromName": "Canva",
    "subject": "[code 1] is your Canva code",
    "receivedAt": "2026-10-01T09:12:00.000Z",
    "checked": true,
    "spam": false,
    "codes": 1,
    "links": [
      {
        "n": 1,
        "site": "canva.com",
        "label": "Verify email"
      }
    ],
    "direction": "in",
    "to": [],
    "status": null,
    "error": null,
    "text": "Hi,\n\nYour code is [code 1]. Or [link 1: canva.com \"Verify email\"]."
  }
}

Nudge a teammate

POST /api/v1/agents/{handle}/nudge

Has the teammate pick up its next task in To do now, rather than at the next minute's pickup, even one waiting to retry after a failure. outcome is picked (with the task it started), working (it already is, with its task if it has one) or idle (nothing waits for it in To do). A paused teammate answers not_ready, and so does one that can't run now (its daily limit, its AI plan, an app it needs), with why.

• CLI: troopy agents nudge. MCP tool: troopy_nudge_agent
• Scopes: agents:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "outcome": "picked",
    "task": {
      "key": "VIR-12",
      "title": "Draft the October newsletter"
    }
  }
}

Get a teaching session

GET /api/v1/agents/{handle}/teach

The teammate's teaching session that is going, or null: a task a person is showing it on its computer (recording, with how many steps so far), the recording it is studying (studying), or the skill it drafted, waiting for review (ready). Poll it while recording or studying. Needs an owner or admin.

• CLI: troopy teach get
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "id": "6650f1a2b3c4d5e6f7a8b9c0",
    "agent": "chief",
    "goal": "Refund an order in Stripe",
    "status": "ready",
    "steps": 14,
    "draft": {
      "name": "refund-an-order-in-stripe",
      "description": "When asked to refund a customer's order",
      "text": "1. Open dashboard.stripe.com/payments.\n2. Search the customer's email."
    },
    "threadId": "6650f1a2b3c4d5e6f7a8b9c1",
    "error": null,
    "createdAt": "2026-09-29T09:00:00.000Z"
  }
}

Teach a teammate a task

POST /api/v1/agents/{handle}/teach

Starts recording a task a person is about to do once in the teammate's own browser on the workspace's computer: its browser comes to the front, then page visits, clicks, typing and Enter are recorded, never passwords, one-time codes or card numbers. Take over the computer's screen (POST /computer/desktop) to do it. Starting while one records returns that one. Needs an owner or admin.

• CLI: troopy teach start
• Scopes: agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650f1a2b3c4d5e6f7a8b9c0",
    "agent": "chief",
    "goal": "Refund an order in Stripe",
    "status": "recording",
    "steps": 14,
    "draft": null,
    "threadId": null,
    "error": null,
    "createdAt": "2026-09-29T09:00:00.000Z"
  }
}

Finish teaching a task

PATCH /api/v1/agents/{handle}/teach

study sends the recording to the teammate: a conversation opens with it and it drafts a skill (then GET shows it ready). approve saves the reviewed skill, with your edits, as a skill of the workspace that every teammate can use (GET /skills); its name can't be one a skill has already. discard drops the recording or the draft. Needs an owner or admin.

• CLI: troopy teach update
• Scopes: agents:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650f1a2b3c4d5e6f7a8b9c0",
    "agent": "chief",
    "goal": "Refund an order in Stripe",
    "status": "studying",
    "steps": 14,
    "draft": null,
    "threadId": "6650f1a2b3c4d5e6f7a8b9c1",
    "error": null,
    "createdAt": "2026-09-29T09:00:00.000Z"
  }
}

List the skills

GET /api/v1/skills

The skills of the workspace, by name: the steps for one kind of job, which every teammate can open besides the skills of its role. A message to a teammate that starts with /name asks it to use that skill.

• CLI: troopy skills list. MCP tool: troopy_list_skills
• Scopes: agents:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "name": "refund-policy",
      "description": "When a customer asks for their money back",
      "enabled": true,
      "source": "person",
      "author": {
        "type": "person",
        "id": "6650c0ffee00000000000001",
        "name": "Ada Lovelace"
      },
      "teammate": null,
      "uses": 6,
      "lastUsedAt": "2026-10-11T14:30:00.000Z",
      "createdAt": "2026-10-09T09:00:00.000Z",
      "updatedAt": "2026-10-09T09:00:00.000Z"
    }
  ]
}

Read a skill

GET /api/v1/skills/{name}

One skill of the workspace, with its steps.

• CLI: troopy skills get. MCP tool: troopy_get_skill
• Scopes: agents:read
• At most 60 calls per 60 seconds per key

{
  "data": {
    "name": "refund-policy",
    "description": "When a customer asks for their money back",
    "enabled": true,
    "source": "person",
    "author": {
      "type": "person",
      "id": "6650c0ffee00000000000001",
      "name": "Ada Lovelace"
    },
    "teammate": null,
    "uses": 6,
    "lastUsedAt": "2026-10-11T14:30:00.000Z",
    "createdAt": "2026-10-09T09:00:00.000Z",
    "updatedAt": "2026-10-09T09:00:00.000Z",
    "text": "1. Find the order.\n2. Refund it within 30 days of purchase.",
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee00000000000001",
      "name": "Ada Lovelace"
    }
  }
}

Write a skill

POST /api/v1/skills

Writes a skill of the workspace: a new one, or new words for the one with that name. Every teammate can open it. Anyone in the workspace can write one. When a teammate calls it (save_skill), the call waits for a person's approval. A name that a role's own skill has, or a command like stop, is taken.

• CLI: troopy skills save
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "name": "refund-policy",
    "description": "When a customer asks for their money back",
    "enabled": true,
    "source": "person",
    "author": {
      "type": "person",
      "id": "6650c0ffee00000000000001",
      "name": "Ada Lovelace"
    },
    "teammate": null,
    "uses": 6,
    "lastUsedAt": "2026-10-11T14:30:00.000Z",
    "createdAt": "2026-10-09T09:00:00.000Z",
    "updatedAt": "2026-10-09T09:00:00.000Z",
    "text": "1. Find the order.\n2. Refund it within 30 days of purchase.",
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee00000000000001",
      "name": "Ada Lovelace"
    }
  }
}

Turn a skill on or off

PATCH /api/v1/skills/{name}

Off, no teammate sees the skill or opens it. Needs an owner or admin.

• CLI: troopy skills update
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "name": "refund-policy",
    "description": "When a customer asks for their money back",
    "enabled": false,
    "source": "person",
    "author": {
      "type": "person",
      "id": "6650c0ffee00000000000001",
      "name": "Ada Lovelace"
    },
    "teammate": null,
    "uses": 6,
    "lastUsedAt": "2026-10-11T14:30:00.000Z",
    "createdAt": "2026-10-09T09:00:00.000Z",
    "updatedAt": "2026-10-09T09:00:00.000Z",
    "text": "1. Find the order.\n2. Refund it within 30 days of purchase.",
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee00000000000001",
      "name": "Ada Lovelace"
    }
  }
}

Delete a skill

DELETE /api/v1/skills/{name}

Deletes a skill of the workspace. Owners, admins and the person who made it can.

• CLI: troopy skills delete
• Scopes: agents:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "name": "refund-policy"
  }
}

List the skill packs

GET /api/v1/skill-packs

The skill packs of the workspace, in order: the ones that ship with Troopy, then the ones people added from public GitHub repositories. Each lists its skills and which of them teammates see.

• CLI: troopy packs list. MCP tool: troopy_list_skill_packs
• Scopes: agents:read
• At most 30 calls per 60 seconds per key

{
  "data": [
    {
      "key": "acme__growthskills",
      "name": "growthskills",
      "repo": "acme/growthskills",
      "folder": "skills",
      "sha": "1efedbc5148b54b2f0f6c6c9fe0be62e151c7fff",
      "builtIn": false,
      "enabled": true,
      "author": "acme",
      "license": "MIT",
      "stars": 42,
      "about": "Skills for marketers",
      "skills": [
        {
          "name": "cold-email",
          "description": "When writing a first email to a stranger",
          "on": true,
          "shadowed": false
        }
      ],
      "warnings": [],
      "syncedAt": "2026-10-09T09:00:00.000Z"
    }
  ]
}

Add a skill pack

POST /api/v1/skill-packs

Adds a pack of skills from a public GitHub repository, on at once, at the commit its default branch is at. Each skill is a folder with a SKILL.md. Its skills become instructions for every teammate: add only repositories you trust. A workspace adds 20 packs at most, and adds or syncs 10 an hour. Needs an owner or admin.

• CLI: troopy packs add
• Scopes: agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "key": "acme__growthskills",
    "name": "growthskills",
    "repo": "acme/growthskills",
    "folder": "skills",
    "sha": "1efedbc5148b54b2f0f6c6c9fe0be62e151c7fff",
    "builtIn": false,
    "enabled": true,
    "author": "acme",
    "license": "MIT",
    "stars": 42,
    "about": "Skills for marketers",
    "skills": [
      {
        "name": "cold-email",
        "description": "When writing a first email to a stranger",
        "on": true,
        "shadowed": false
      }
    ],
    "warnings": [],
    "syncedAt": "2026-10-09T09:00:00.000Z"
  }
}

Turn a skill pack on or off

PATCH /api/v1/skill-packs/{key}

Off, no teammate sees its skills. Needs an owner or admin.

• CLI: troopy packs update
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "key": "acme__growthskills",
    "name": "growthskills",
    "repo": "acme/growthskills",
    "folder": "skills",
    "sha": "1efedbc5148b54b2f0f6c6c9fe0be62e151c7fff",
    "builtIn": false,
    "enabled": false,
    "author": "acme",
    "license": "MIT",
    "stars": 42,
    "about": "Skills for marketers",
    "skills": [
      {
        "name": "cold-email",
        "description": "When writing a first email to a stranger",
        "on": true,
        "shadowed": false
      }
    ],
    "warnings": [],
    "syncedAt": "2026-10-09T09:00:00.000Z"
  }
}

Sync a skill pack

POST /api/v1/skill-packs/{key}/sync

Gets the latest skills of a pack that people added: its repository's default branch now. Says which skills came, changed or went. A pack that ships with Troopy gets its new skills with Troopy's updates. Needs an owner or admin.

• CLI: troopy packs sync
• Scopes: agents:write
• At most 10 calls per 60 seconds per key

{
  "data": {
    "sha": "2b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c",
    "added": [
      "pricing"
    ],
    "changed": [
      "cold-email"
    ],
    "removed": []
  }
}

Remove a skill pack

DELETE /api/v1/skill-packs/{key}

Removes a pack that people added. A pack that ships with Troopy can only be turned off. Needs an owner or admin.

• CLI: troopy packs remove
• Scopes: agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "key": "acme__growthskills"
  }
}

Read a skill of a pack

GET /api/v1/skill-packs/{key}/skills/{name}

One skill of a pack, with its steps and the paths of its files. With file, text is that file's text.

• CLI: troopy packs skill. MCP tool: troopy_get_pack_skill
• Scopes: agents:read
• At most 60 calls per 60 seconds per key

{
  "data": {
    "name": "cold-email",
    "description": "When writing a first email to a stranger",
    "text": "1. Find one true detail.",
    "files": [
      "references/openers.md"
    ],
    "file": null
  }
}

Turn a skill of a pack on or off

PATCH /api/v1/skill-packs/{key}/skills/{name}

Off, no teammate sees that skill of the pack. Needs an owner or admin.

• CLI: troopy packs skill-update
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "key": "acme__growthskills",
    "name": "growthskills",
    "repo": "acme/growthskills",
    "folder": "skills",
    "sha": "1efedbc5148b54b2f0f6c6c9fe0be62e151c7fff",
    "builtIn": false,
    "enabled": true,
    "author": "acme",
    "license": "MIT",
    "stars": 42,
    "about": "Skills for marketers",
    "skills": [
      {
        "name": "cold-email",
        "description": "When writing a first email to a stranger",
        "on": true,
        "shadowed": false
      }
    ],
    "warnings": [],
    "syncedAt": "2026-10-09T09:00:00.000Z"
  }
}

Rewrite a teammate's own file

PATCH /api/v1/agents/{handle}/files/{file}

Replaces one of a teammate's own memory files, whole, in markdown: identity (who it is), personality (how it works and sounds) or notes (facts it always keeps). It reads them at the start of every run. A teammate calling this may rewrite only its own files, and the lead any teammate's; either way it waits for a person's approval.

• CLI: troopy agents file. MCP tool: troopy_update_teammate_file
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "handle": "chief",
    "name": "Chief of Staff",
    "role": "chief",
    "title": "Chief of Staff",
    "tagline": "Lead Agent: Runs the troop, plans, delegates",
    "area": "lead",
    "lead": true,
    "avatar": {
      "shape": "mech",
      "color": "#C9B8F0",
      "face": "mouth"
    },
    "status": "idle",
    "needsYou": false,
    "lastActiveAt": "2026-09-01T09:05:00.000Z",
    "doing": null,
    "plan": null,
    "model": null,
    "effort": null,
    "summary": "Your first teammate. Answers from the brain, plans the work and hands it to the right teammate.",
    "job": {
      "goal": "Take work off the owner's plate.",
      "responsibilities": [
        "Answer questions about the business"
      ],
      "done": [
        "The person has an answer"
      ],
      "never": [
        "Invent facts"
      ]
    },
    "tools": [
      {
        "id": "search_brain",
        "label": "Search the brain",
        "approval": false,
        "off": false
      },
      {
        "id": "handoff",
        "label": "Hand work to a teammate",
        "approval": false,
        "off": false
      }
    ],
    "skills": [
      {
        "name": "weekly-brief",
        "title": "Weekly brief",
        "when": "Writing the weekly brief",
        "about": "Writes a short brief each week: what is new, what changed, and what is worth doing."
      }
    ],
    "routinePresets": [
      {
        "name": "Weekly brief",
        "task": "Write this week's brief.",
        "days": [
          1
        ],
        "hour": 8,
        "minute": 0
      }
    ],
    "limits": {
      "rounds": 12,
      "runsPerDay": 200,
      "usdPerRun": 3
    },
    "roleLimits": {
      "rounds": 12,
      "runsPerDay": 200,
      "usdPerRun": 3
    },
    "roleVersion": 2,
    "voice": "cedar",
    "sites": [],
    "needs": [],
    "identity": "# IDENTITY.md\n\n- **Name:** Chief of Staff",
    "personality": "# SOUL.md\n\n## How I work\n\n- I lead with the answer.",
    "notes": "# MEMORY.md\n\n- Wholesale orders close at 4pm.",
    "expertise": [
      "planning",
      "delegation"
    ],
    "starters": [
      "What do you know about our business so far?"
    ],
    "stats": {
      "runs": 8,
      "done": 7,
      "failed": 1,
      "inFlight": 0,
      "waiting": 0,
      "drafts": 1,
      "conversations": 3,
      "successRate": 88
    },
    "createdAt": "2026-09-01T09:00:00.000Z"
  }
}

Update a teammate

PATCH /api/v1/agents/{handle}

Renames a teammate, changes its face or its voice, rewrites one of its memory files, sets the sites it may read, assigns it an AI plan, changes its limits, or pauses or resumes it; send any of them. A paused teammate starts no runs. Pausing, resuming, sites and limits need an owner or admin. Its role, and so its tools, can't be changed.

• CLI: troopy agents update. MCP tool: troopy_update_agent
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "handle": "chief",
    "name": "Chief of Staff",
    "role": "chief",
    "title": "Chief of Staff",
    "tagline": "Lead Agent: Runs the troop, plans, delegates",
    "area": "lead",
    "lead": true,
    "avatar": {
      "shape": "mech",
      "color": "#C9B8F0",
      "face": "mouth"
    },
    "status": "idle",
    "needsYou": false,
    "lastActiveAt": "2026-09-01T09:05:00.000Z",
    "doing": null,
    "plan": null,
    "model": null,
    "effort": null,
    "summary": "Your first teammate. Answers from the brain, plans the work and hands it to the right teammate.",
    "job": {
      "goal": "Take work off the owner's plate.",
      "responsibilities": [
        "Answer questions about the business"
      ],
      "done": [
        "The person has an answer"
      ],
      "never": [
        "Invent facts"
      ]
    },
    "tools": [
      {
        "id": "search_brain",
        "label": "Search the brain",
        "approval": false,
        "off": false
      },
      {
        "id": "handoff",
        "label": "Hand work to a teammate",
        "approval": false,
        "off": false
      }
    ],
    "skills": [
      {
        "name": "weekly-brief",
        "title": "Weekly brief",
        "when": "Writing the weekly brief",
        "about": "Writes a short brief each week: what is new, what changed, and what is worth doing."
      }
    ],
    "routinePresets": [
      {
        "name": "Weekly brief",
        "task": "Write this week's brief.",
        "days": [
          1
        ],
        "hour": 8,
        "minute": 0
      }
    ],
    "limits": {
      "rounds": 12,
      "runsPerDay": 200,
      "usdPerRun": 3
    },
    "roleLimits": {
      "rounds": 12,
      "runsPerDay": 200,
      "usdPerRun": 3
    },
    "roleVersion": 2,
    "voice": "cedar",
    "sites": [],
    "needs": [],
    "identity": "# IDENTITY.md\n\n- **Name:** Chief of Staff",
    "personality": "# SOUL.md\n\n## How I work\n\n- I lead with the answer.",
    "notes": "# MEMORY.md\n\n- Wholesale orders close at 4pm.",
    "expertise": [
      "planning",
      "delegation"
    ],
    "starters": [
      "What do you know about our business so far?"
    ],
    "stats": {
      "runs": 8,
      "done": 7,
      "failed": 1,
      "inFlight": 0,
      "waiting": 0,
      "drafts": 1,
      "conversations": 3,
      "successRate": 88
    },
    "createdAt": "2026-09-01T09:00:00.000Z"
  }
}

Hire a teammate

POST /api/v1/agents

Hires a teammate into a role from GET /roles, or into the custom role a finished draft run proposed (POST /roles/drafts). It starts with its role's memory files. A lead can't be hired twice. Needs an owner or admin.

• CLI: troopy agents hire. MCP tool: troopy_hire_agent
• Scopes: agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "handle": "writer",
    "name": "Content writer",
    "role": "writer",
    "title": "Content writer",
    "tagline": "Writes emails, articles and web copy in your voice",
    "area": "marketing",
    "lead": false,
    "avatar": {
      "shape": "mech",
      "color": "#C9B8F0",
      "face": "mouth"
    },
    "status": "idle",
    "needsYou": false,
    "lastActiveAt": "2026-09-01T09:05:00.000Z",
    "doing": null,
    "plan": null,
    "model": null,
    "effort": null,
    "summary": "Your first teammate. Answers from the brain, plans the work and hands it to the right teammate.",
    "job": {
      "goal": "Take work off the owner's plate.",
      "responsibilities": [
        "Answer questions about the business"
      ],
      "done": [
        "The person has an answer"
      ],
      "never": [
        "Invent facts"
      ]
    },
    "tools": [
      {
        "id": "search_brain",
        "label": "Search the brain",
        "approval": false,
        "off": false
      },
      {
        "id": "handoff",
        "label": "Hand work to a teammate",
        "approval": false,
        "off": false
      }
    ],
    "skills": [
      {
        "name": "weekly-brief",
        "title": "Weekly brief",
        "when": "Writing the weekly brief",
        "about": "Writes a short brief each week: what is new, what changed, and what is worth doing."
      }
    ],
    "routinePresets": [
      {
        "name": "Weekly brief",
        "task": "Write this week's brief.",
        "days": [
          1
        ],
        "hour": 8,
        "minute": 0
      }
    ],
    "limits": {
      "rounds": 12,
      "runsPerDay": 200,
      "usdPerRun": 3
    },
    "roleLimits": {
      "rounds": 12,
      "runsPerDay": 200,
      "usdPerRun": 3
    },
    "roleVersion": 2,
    "voice": "cedar",
    "sites": [],
    "needs": [],
    "identity": "# IDENTITY.md\n\n- **Name:** Chief of Staff",
    "personality": "# SOUL.md\n\n## How I work\n\n- I lead with the answer.",
    "notes": "# MEMORY.md\n\n- Wholesale orders close at 4pm.",
    "expertise": [
      "planning",
      "delegation"
    ],
    "starters": [
      "What do you know about our business so far?"
    ],
    "stats": {
      "runs": 8,
      "done": 7,
      "failed": 1,
      "inFlight": 0,
      "waiting": 0,
      "drafts": 1,
      "conversations": 3,
      "successRate": 88
    },
    "createdAt": "2026-09-01T09:00:00.000Z"
  }
}

Let a teammate go

DELETE /api/v1/agents/{handle}

Removes a teammate with its conversations, runs and schedules, and denies what it was waiting on. The troop's lead stays. Cannot be undone. Needs an owner or admin.

• CLI: troopy agents fire
• Scopes: agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "deleted": true
  }
}

List roles

GET /api/v1/roles

The roles a teammate can be hired into: what each does, its tools, which calls wait for approval, and who already holds it here.

• CLI: troopy roles list. MCP tool: troopy_list_roles
• Scopes: agents:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "id": "writer",
      "name": "Content writer",
      "title": "Content writer",
      "summary": "Writes what the business needs said: emails, articles, landing copy and headlines, in your voice, as drafts for you.",
      "area": "marketing",
      "lead": false,
      "recommended": true,
      "avatar": {
        "shape": "flower",
        "color": "#B5D6B2",
        "face": "mouth"
      },
      "tools": [
        {
          "id": "search_brain",
          "label": "Search the brain",
          "approval": false
        },
        {
          "id": "save_draft",
          "label": "Save a draft for you",
          "approval": false
        }
      ],
      "routines": [
        {
          "name": "Weekly article",
          "task": "Draft one article.",
          "days": [
            2
          ],
          "hour": 9,
          "minute": 0
        }
      ],
      "expertise": [
        "copywriting",
        "newsletters"
      ],
      "hired": [],
      "needs": []
    }
  ]
}

Draft a custom role

POST /api/v1/roles/drafts

Asks the troop's lead to draft a role from a description: its job, tools (only ones Troopy has), which calls wait for approval, personality and skills. Answers 202 with the run; poll statusUrl until it is done, then hire its draft with POST /agents. Needs an owner or admin.

• CLI: troopy roles draft. MCP tool: troopy_draft_role
• Scopes: agents:write
• At most 5 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000013",
    "agent": "chief",
    "kind": "draft_role",
    "trigger": {
      "type": "hire",
      "threadId": null,
      "routineId": null,
      "fromRunId": null,
      "troopThreadId": null
    },
    "taskId": null,
    "task": "Someone who keeps track of our competitors and what they change.",
    "status": "queued",
    "roleVersion": 1,
    "summary": "",
    "error": null,
    "doing": null,
    "toolCalls": 0,
    "skills": [],
    "requestedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-09-01T09:04:00.000Z",
    "finishedAt": null,
    "statusUrl": "https://troopy.ai/api/v1/runs/6650c0ffee00000000000013",
    "reply": null,
    "cites": [
      {
        "type": "source",
        "id": "6650c0ffee0000000000000e",
        "title": "Wholesale terms",
        "kind": "note",
        "wrong": null
      }
    ],
    "draft": null,
    "rounds": []
  }
}

List conversations

GET /api/v1/threads

Conversations with the workspace's teammates, most recently active first. Each is a thread: the message that started it, its latest message and how many replies followed. Name a teammate to see only theirs.

• CLI: troopy chat list. MCP tool: troopy_list_conversations
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee00000000000011",
      "agent": "chief",
      "title": "What are our payment terms for wholesale?",
      "status": "idle",
      "error": null,
      "runId": null,
      "doing": null,
      "telegram": false,
      "call": false,
      "createdAt": "2026-09-01T09:04:00.000Z",
      "updatedAt": "2026-09-01T09:04:20.000Z",
      "firstMessage": {
        "from": "person",
        "text": "What are our payment terms for wholesale?",
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        },
        "at": "2026-09-01T09:04:00.000Z",
        "runId": null,
        "approvalIds": [],
        "cites": []
      },
      "lastMessage": {
        "from": "agent",
        "text": "Wholesale customers pay on 30-day terms, $6 a loaf.",
        "by": {
          "type": "agent",
          "id": "6650c0ffee00000000000012",
          "name": "Chief of Staff"
        },
        "at": "2026-09-01T09:04:20.000Z",
        "runId": "6650c0ffee00000000000013",
        "approvalIds": [],
        "cites": [
          {
            "type": "source",
            "id": "6650c0ffee0000000000000e",
            "title": "Wholesale terms",
            "kind": "note",
            "wrong": null
          }
        ]
      },
      "replies": 1
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Start a conversation

POST /api/v1/threads

Sends a first message to a teammate, the troop's lead unless agent names another. It works on it in a run, with its role's tools and what the brain knows, on the organization's own AI plan and the workspace's computer, which must be connected. Answers 202 at once; poll statusUrl until status is no longer replying.

• CLI: troopy chat start. MCP tool: troopy_start_conversation
• Scopes: agents:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000011",
    "agent": "chief",
    "title": "What are our payment terms for wholesale?",
    "status": "replying",
    "error": null,
    "runId": "6650c0ffee00000000000013",
    "doing": null,
    "telegram": false,
    "call": false,
    "messages": [
      {
        "from": "person",
        "text": "What are our payment terms for wholesale?",
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        },
        "at": "2026-09-01T09:04:00.000Z",
        "runId": null,
        "approvalIds": [],
        "cites": []
      }
    ],
    "createdAt": "2026-09-01T09:04:00.000Z",
    "updatedAt": "2026-09-01T09:04:20.000Z",
    "statusUrl": "https://troopy.ai/api/v1/threads/6650c0ffee00000000000011"
  }
}

Read a conversation

GET /api/v1/threads/{id}

A conversation with every message, oldest first, and whether the teammate is still working on an answer.

• CLI: troopy chat get. MCP tool: troopy_get_conversation
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "id": "6650c0ffee00000000000011",
    "agent": "chief",
    "title": "What are our payment terms for wholesale?",
    "status": "idle",
    "error": null,
    "runId": null,
    "doing": null,
    "telegram": false,
    "call": false,
    "messages": [
      {
        "from": "person",
        "text": "What are our payment terms for wholesale?",
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        },
        "at": "2026-09-01T09:04:00.000Z",
        "runId": null,
        "approvalIds": [],
        "cites": []
      },
      {
        "from": "agent",
        "text": "Wholesale customers pay on 30-day terms, $6 a loaf.",
        "by": {
          "type": "agent",
          "id": "6650c0ffee00000000000012",
          "name": "Chief of Staff"
        },
        "at": "2026-09-01T09:04:20.000Z",
        "runId": "6650c0ffee00000000000013",
        "approvalIds": [],
        "cites": [
          {
            "type": "source",
            "id": "6650c0ffee0000000000000e",
            "title": "Wholesale terms",
            "kind": "note",
            "wrong": null
          }
        ]
      }
    ],
    "createdAt": "2026-09-01T09:04:00.000Z",
    "updatedAt": "2026-09-01T09:04:20.000Z",
    "statusUrl": "https://troopy.ai/api/v1/threads/6650c0ffee00000000000011"
  }
}

Reply in a conversation

POST /api/v1/threads/{id}/messages

Sends another message in a conversation. If the teammate is still replying, the message is handed to that reply: it takes it in, or answers it in a follow-up reply right after. A message that only says stop (stop, cancel, never mind), from the person who asked or an owner or admin, stops the answer under way instead; with nothing under way it is a message like any other. Answers 202 at once; poll statusUrl until status is no longer replying.

• CLI: troopy chat send. MCP tool: troopy_send_message
• Scopes: agents:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000011",
    "agent": "chief",
    "title": "What are our payment terms for wholesale?",
    "status": "replying",
    "error": null,
    "runId": "6650c0ffee00000000000017",
    "doing": null,
    "telegram": false,
    "call": false,
    "messages": [
      {
        "from": "person",
        "text": "What are our payment terms for wholesale?",
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        },
        "at": "2026-09-01T09:04:00.000Z",
        "runId": null,
        "approvalIds": [],
        "cites": []
      },
      {
        "from": "agent",
        "text": "Wholesale customers pay on 30-day terms, $6 a loaf.",
        "by": {
          "type": "agent",
          "id": "6650c0ffee00000000000012",
          "name": "Chief of Staff"
        },
        "at": "2026-09-01T09:04:20.000Z",
        "runId": "6650c0ffee00000000000013",
        "approvalIds": [],
        "cites": [
          {
            "type": "source",
            "id": "6650c0ffee0000000000000e",
            "title": "Wholesale terms",
            "kind": "note",
            "wrong": null
          }
        ]
      },
      {
        "from": "person",
        "text": "And for retail?",
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        },
        "at": "2026-09-01T09:06:00.000Z",
        "runId": null,
        "approvalIds": [],
        "cites": []
      }
    ],
    "createdAt": "2026-09-01T09:04:00.000Z",
    "updatedAt": "2026-09-01T09:04:20.000Z",
    "statusUrl": "https://troopy.ai/api/v1/threads/6650c0ffee00000000000011"
  }
}

Read the troop chat

GET /api/v1/troop/messages

The troop chat: the workspace's group chat, where people and every teammate talk. Its latest messages in the room, oldest first, each with its thread (how many replies, who replied lately, who is answering in it now), and every teammate answering anywhere in it. Pass the oldest id you have as before to read further back; GET /troop/messages/{id} reads a thread.

• CLI: troopy troop list. MCP tool: troopy_read_troop_chat
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee000000000000a0",
      "threadId": null,
      "from": "person",
      "by": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "agent": null,
      "avatar": null,
      "text": "What are our payment terms for wholesale?",
      "to": [
        "chief"
      ],
      "runId": null,
      "failed": false,
      "task": null,
      "approvalIds": [],
      "reactions": [],
      "cites": [],
      "at": "2026-09-01T09:04:00.000Z",
      "replies": 1,
      "lastReplyAt": "2026-09-01T09:04:20.000Z",
      "repliedBy": [
        {
          "name": "Chief of Staff",
          "agent": "chief",
          "avatar": {
            "shape": "pill",
            "color": "#A9CFF2",
            "face": "eyes"
          }
        }
      ],
      "answering": []
    }
  ],
  "replying": []
}

Post in the troop chat

POST /api/v1/troop/messages

Posts a message to the troop chat's room, which starts its thread. Each teammate it @mentions (like @writer; @all for every one) answers it in that thread, in a run of its own, on the organization's AI plan and computer. With no teammate named, the lead answers, unless a person wrote it (not an API key), the workspace's troopRoom is troop and it has more than one person: then a quick read decides whether a teammate answers, looks into it quietly (and speaks only if it finds something), reacts, or leaves it to the people (triaging is true while it does). Answers 202 at once; read the thread until answering is empty.

• CLI: troopy troop send. MCP tool: troopy_post_to_troop_chat
• Scopes: agents:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee000000000000a0",
    "threadId": null,
    "from": "person",
    "by": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "agent": null,
    "avatar": null,
    "text": "What are our payment terms for wholesale?",
    "to": [
      "chief"
    ],
    "runId": null,
    "failed": false,
    "task": null,
    "approvalIds": [],
    "reactions": [],
    "cites": [],
    "at": "2026-09-01T09:04:00.000Z",
    "started": [
      "chief"
    ],
    "handed": [],
    "stopped": [],
    "skipped": [],
    "triaging": false
  }
}

Read a thread in the troop chat

GET /api/v1/troop/messages/{id}

A thread in the troop chat: the message that started it (a reply's id opens its thread too) and its latest replies, oldest first, who is answering in it now, and who a reply that names no one goes to.

• CLI: troopy troop thread. MCP tool: troopy_read_troop_thread
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "message": {
      "id": "6650c0ffee000000000000a0",
      "threadId": null,
      "from": "person",
      "by": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "agent": null,
      "avatar": null,
      "text": "What are our payment terms for wholesale?",
      "to": [
        "chief"
      ],
      "runId": null,
      "failed": false,
      "task": null,
      "approvalIds": [],
      "reactions": [],
      "cites": [],
      "at": "2026-09-01T09:04:00.000Z"
    },
    "replies": [
      {
        "id": "6650c0ffee000000000000a1",
        "threadId": "6650c0ffee000000000000a0",
        "from": "agent",
        "by": {
          "type": "agent",
          "id": "6650c0ffee00000000000012",
          "name": "Chief of Staff"
        },
        "agent": "chief",
        "avatar": {
          "shape": "pill",
          "color": "#A9CFF2",
          "face": "eyes"
        },
        "text": "Wholesale customers pay on 30-day terms.",
        "to": [],
        "runId": "6650c0ffee00000000000013",
        "failed": false,
        "task": null,
        "approvalIds": [],
        "reactions": [],
        "cites": [],
        "at": "2026-09-01T09:04:20.000Z"
      }
    ],
    "total": 1,
    "answering": [],
    "with": [
      "chief"
    ]
  }
}

Reply in a troop chat thread

POST /api/v1/troop/messages/{id}/replies

Replies in a thread in the troop chat. The teammates it @mentions answer in the thread (@all: every one); naming no one, it goes to whoever the thread's latest message from a person went to (see with in GET /troop/messages/{id}), unless, as in the room, a quick read applies: with nobody answering in the thread and a person's word last (not the sender's own to a teammate), a person's reply is read first. A teammate already answering in the thread takes it in, and answers it right after if it finished without seeing it. A reply that only says stop (stop, cancel, never mind; naming no one, or @all) stops every answer in the thread its sender may stop: the asker's own, or any for an owner or admin; with none to stop it is a reply like any other, and @all means the lead. Answers 202 at once; read the thread until answering is empty.

• CLI: troopy troop reply. MCP tool: troopy_reply_in_troop_thread
• Scopes: agents:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee000000000000a2",
    "threadId": "6650c0ffee000000000000a0",
    "from": "person",
    "by": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "agent": null,
    "avatar": null,
    "text": "And for retail?",
    "to": [
      "chief"
    ],
    "runId": null,
    "failed": false,
    "task": null,
    "approvalIds": [],
    "reactions": [],
    "cites": [],
    "at": "2026-09-01T09:04:00.000Z",
    "started": [
      "chief"
    ],
    "handed": [],
    "stopped": [],
    "skipped": [],
    "triaging": false
  }
}

React to a troop chat message

POST /api/v1/troop/messages/{id}/reactions

Adds your reaction to a message in the troop chat, in the room or a thread. Reacting the same way twice keeps one. A message keeps at most 50 reactions.

• CLI: troopy troop react. MCP tool: troopy_react_in_troop_chat
• Scopes: agents:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee000000000000a0",
    "threadId": null,
    "from": "person",
    "by": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "agent": null,
    "avatar": null,
    "text": "What are our payment terms for wholesale?",
    "to": [
      "chief"
    ],
    "runId": null,
    "failed": false,
    "task": null,
    "approvalIds": [],
    "reactions": [
      {
        "emoji": "thumbs_up",
        "by": [
          {
            "type": "person",
            "id": "6650c0ffee0000000000000a",
            "name": "Ada Lovelace"
          }
        ]
      }
    ],
    "cites": [],
    "at": "2026-09-01T09:04:00.000Z"
  }
}

Take back a troop chat reaction

DELETE /api/v1/troop/messages/{id}/reactions/{emoji}

Removes your reaction from a message in the troop chat. Others' reactions stay.

• CLI: troopy troop unreact
• Scopes: agents:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee000000000000a0",
    "threadId": null,
    "from": "person",
    "by": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "agent": null,
    "avatar": null,
    "text": "What are our payment terms for wholesale?",
    "to": [
      "chief"
    ],
    "runId": null,
    "failed": false,
    "task": null,
    "approvalIds": [],
    "reactions": [],
    "cites": [],
    "at": "2026-09-01T09:04:00.000Z"
  }
}

List runs

GET /api/v1/runs

Teammates' runs in the workspace, newest first: what started each, how it went and a one-line summary. Filter by teammate, status, what started it, the schedule that started it, or when.

• CLI: troopy runs list. MCP tool: troopy_list_runs
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee00000000000013",
      "agent": "chief",
      "kind": "work",
      "trigger": {
        "type": "chat",
        "threadId": "6650c0ffee00000000000011",
        "routineId": null,
        "fromRunId": null,
        "troopThreadId": null
      },
      "taskId": null,
      "task": "What are our payment terms for wholesale?",
      "status": "done",
      "roleVersion": 1,
      "summary": "Answered from the Wholesale terms note",
      "error": null,
      "doing": null,
      "toolCalls": 1,
      "skills": [],
      "requestedBy": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "createdAt": "2026-09-01T09:04:00.000Z",
      "finishedAt": "2026-09-01T09:04:20.000Z",
      "statusUrl": "https://troopy.ai/api/v1/runs/6650c0ffee00000000000013"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Read a run

GET /api/v1/runs/{id}

One run in full: every round with what it did, each tool call with its input, why the teammate made it, what it returned and whether it waits for approval, the call that runs now, and the answer.

• CLI: troopy runs get. MCP tool: troopy_get_run
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "id": "6650c0ffee00000000000013",
    "agent": "chief",
    "kind": "work",
    "trigger": {
      "type": "chat",
      "threadId": "6650c0ffee00000000000011",
      "routineId": null,
      "fromRunId": null,
      "troopThreadId": null
    },
    "taskId": null,
    "task": "What are our payment terms for wholesale?",
    "status": "done",
    "roleVersion": 1,
    "summary": "Answered from the Wholesale terms note",
    "error": null,
    "doing": null,
    "toolCalls": 1,
    "skills": [],
    "requestedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-09-01T09:04:00.000Z",
    "finishedAt": "2026-09-01T09:04:20.000Z",
    "statusUrl": "https://troopy.ai/api/v1/runs/6650c0ffee00000000000013",
    "reply": "Wholesale customers pay on 30-day terms, $6 a loaf.",
    "cites": [
      {
        "type": "source",
        "id": "6650c0ffee0000000000000e",
        "title": "Wholesale terms",
        "kind": "note",
        "wrong": null
      }
    ],
    "draft": null,
    "rounds": [
      {
        "startedAt": "2026-09-01T09:04:01.000Z",
        "endedAt": "2026-09-01T09:04:09.000Z",
        "action": "tools",
        "doing": "Reading the wholesale terms",
        "calls": [
          {
            "tool": "read_source",
            "label": "Read a source",
            "input": {
              "id": "6650c0ffee0000000000000e"
            },
            "why": "The note on wholesale terms answers the question.",
            "status": "done",
            "result": "{\"title\":\"Wholesale terms\",\"text\":\"...\"}",
            "approvalId": null
          }
        ]
      },
      {
        "startedAt": "2026-09-01T09:04:10.000Z",
        "endedAt": "2026-09-01T09:04:20.000Z",
        "action": "finish",
        "doing": null,
        "calls": []
      }
    ]
  }
}

List approvals

GET /api/v1/approvals

Calls teammates made that wait for a person's yes, newest first: pending ones unless status says otherwise.

• CLI: troopy approvals list. MCP tool: troopy_list_approvals
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee00000000000014",
      "agent": "chief",
      "tool": "rewrite_doc",
      "label": "Rewrite a doc",
      "input": {
        "slug": "acme-ltd",
        "version": 3,
        "body": "Our biggest wholesale customer. Pays on 30-day terms."
      },
      "reason": "Their terms changed from 14 to 30 days in last week's email.",
      "status": "pending",
      "result": null,
      "error": null,
      "runId": "6650c0ffee00000000000015",
      "threadId": null,
      "taskId": null,
      "lesson": null,
      "decidedBy": null,
      "ruleId": null,
      "decidedAt": null,
      "createdAt": "2026-09-01T07:02:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Approve or deny a call

POST /api/v1/approvals/{id}

Approving runs the call once, as the teammate that asked; denying drops it. Deciding again returns what happened the first time. You need the scopes the call itself needs.

• CLI: troopy approvals decide. MCP tool: troopy_decide_approval
• Scopes: agents:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000014",
    "agent": "chief",
    "tool": "rewrite_doc",
    "label": "Rewrite a doc",
    "input": {
      "slug": "acme-ltd",
      "version": 3,
      "body": "Our biggest wholesale customer. Pays on 30-day terms."
    },
    "reason": "Their terms changed from 14 to 30 days in last week's email.",
    "status": "approved",
    "result": "{\"slug\":\"acme-ltd\",\"version\":4}",
    "error": null,
    "runId": "6650c0ffee00000000000015",
    "threadId": null,
    "taskId": null,
    "lesson": null,
    "decidedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "ruleId": null,
    "decidedAt": "2026-09-01T08:10:00.000Z",
    "createdAt": "2026-09-01T07:02:00.000Z"
  }
}

List standing rules

GET /api/v1/rules

Standing rules that approve or deny a teammate's calls to one tool without asking, newest first: proposed and active ones unless status says otherwise. Troopy proposes one when people give the same answer to the same teammate's calls to the same tool three times in a row within 30 days.

• CLI: troopy rules list. MCP tool: troopy_list_rules
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee00000000000019",
      "agent": "chief",
      "tool": "rewrite_doc",
      "label": "Rewrite a doc",
      "effect": "approve",
      "status": "proposed",
      "basedOn": [
        "6650c0ffee00000000000014",
        "6650c0ffee0000000000001a",
        "6650c0ffee0000000000001b"
      ],
      "decidedBy": null,
      "decidedAt": null,
      "uses": 0,
      "lastUsedAt": null,
      "createdAt": "2026-09-01T08:10:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Accept, dismiss or stop a standing rule

POST /api/v1/rules/{id}

accept makes a proposed rule active: that teammate's calls to that tool are then decided at once, each still recorded as an approval naming the rule. dismiss keeps asking; stop ends an active rule. Owners and admins only, holding the scopes the calls themselves need. Deciding again returns the rule as it is.

• CLI: troopy rules decide. MCP tool: troopy_decide_rule
• Scopes: agents:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000019",
    "agent": "chief",
    "tool": "rewrite_doc",
    "label": "Rewrite a doc",
    "effect": "approve",
    "status": "active",
    "basedOn": [
      "6650c0ffee00000000000014",
      "6650c0ffee0000000000001a",
      "6650c0ffee0000000000001b"
    ],
    "decidedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "decidedAt": "2026-09-01T08:12:00.000Z",
    "uses": 0,
    "lastUsedAt": null,
    "createdAt": "2026-09-01T08:10:00.000Z"
  }
}

List drafts

GET /api/v1/drafts

What teammates wrote for people to use (posts, emails, copy, briefs), newest first: ready ones unless status says otherwise.

• CLI: troopy drafts list. MCP tool: troopy_list_drafts
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee00000000000019",
      "agent": "writer",
      "kind": "email",
      "title": "Fresh sourdough, every Friday",
      "body": "From this Friday, wholesale orders placed by 4pm arrive the next morning.",
      "flags": [],
      "channel": "newsletter",
      "status": "ready",
      "runId": "6650c0ffee00000000000013",
      "threadId": "6650c0ffee00000000000011",
      "taskId": null,
      "doc": null,
      "decidedBy": null,
      "decidedAt": null,
      "createdAt": "2026-09-01T09:04:20.000Z",
      "updatedAt": "2026-09-01T09:04:20.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Get a draft

GET /api/v1/drafts/{id}

One draft, whole.

• CLI: troopy drafts get. MCP tool: troopy_get_draft
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "id": "6650c0ffee00000000000019",
    "agent": "writer",
    "kind": "email",
    "title": "Fresh sourdough, every Friday",
    "body": "From this Friday, wholesale orders placed by 4pm arrive the next morning.",
    "flags": [],
    "channel": "newsletter",
    "status": "ready",
    "runId": "6650c0ffee00000000000013",
    "threadId": "6650c0ffee00000000000011",
    "taskId": null,
    "doc": null,
    "decidedBy": null,
    "decidedAt": null,
    "createdAt": "2026-09-01T09:04:20.000Z",
    "updatedAt": "2026-09-01T09:04:20.000Z"
  }
}

Update a draft

PATCH /api/v1/drafts/{id}

Edits a draft's title or body, or marks it used (you sent or published it yourself), discarded, or ready again. The words of a draft in Docs change in its doc, with PATCH /docs/{slug}. Troopy never sends or publishes a draft.

• CLI: troopy drafts update. MCP tool: troopy_update_draft
• Scopes: agents:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000019",
    "agent": "writer",
    "kind": "email",
    "title": "Fresh sourdough, every Friday",
    "body": "From this Friday, wholesale orders placed by 4pm arrive the next morning.",
    "flags": [],
    "channel": "newsletter",
    "status": "used",
    "runId": "6650c0ffee00000000000013",
    "threadId": "6650c0ffee00000000000011",
    "taskId": null,
    "doc": null,
    "decidedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "decidedAt": "2026-09-01T10:00:00.000Z",
    "createdAt": "2026-09-01T09:04:20.000Z",
    "updatedAt": "2026-09-01T09:04:20.000Z"
  }
}

List routines

GET /api/v1/routines

The routines that teammates do by themselves on a schedule, with when each runs next and how the last run went. A routine that starts when something happens is a trigger: GET /triggers.

• CLI: troopy routines list. MCP tool: troopy_list_routines
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee00000000000016",
      "agent": "chief",
      "name": "Brain tidy-up",
      "task": "Tidy the brain: turn the sources added in the last 24 hours into docs.",
      "days": [
        1,
        2,
        3,
        4,
        5
      ],
      "hour": 7,
      "minute": 0,
      "every": null,
      "cron": null,
      "timezone": "Europe/Berlin",
      "notify": true,
      "paused": false,
      "nextRunAt": "2026-09-02T05:00:00.000Z",
      "lastRunAt": null,
      "lastRunId": null,
      "lastError": null,
      "threadId": null,
      "createdAt": "2026-09-01T09:00:00.000Z"
    }
  ]
}

Make a routine

POST /api/v1/routines

Gives a teammate a routine to do by itself on some days of the week: once at a time, or every so many minutes from a time (every). With cron in the place of days, the routine runs on that cron expression. Each run's answer is posted to the routine's own conversation, unless notify is false. Every run uses the organization's AI plan, so this needs an owner or admin, and a routine may not run more often than the teammate's daily run limit allows.

• CLI: troopy routines create. MCP tool: troopy_create_routine
• Scopes: agents:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000016",
    "agent": "chief",
    "name": "Brain tidy-up",
    "task": "Tidy the brain: turn the sources added in the last 24 hours into docs.",
    "days": [
      1,
      2,
      3,
      4,
      5
    ],
    "hour": 7,
    "minute": 0,
    "every": null,
    "cron": null,
    "timezone": "Europe/Berlin",
    "notify": true,
    "paused": false,
    "nextRunAt": "2026-09-02T05:00:00.000Z",
    "lastRunAt": null,
    "lastRunId": null,
    "lastError": null,
    "threadId": null,
    "createdAt": "2026-09-01T09:00:00.000Z"
  }
}

Change a routine

PATCH /api/v1/routines/{id}

Changes a routine's instructions or times, pauses or resumes it, or gives it to another teammate (agent). Send any of them. A cron takes the place of the days and the time, and days take the place of a cron. A routine that goes to another teammate starts a new conversation there. When it runs next is worked out again. Needs an owner or admin.

• CLI: troopy routines update. MCP tool: troopy_update_routine
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000016",
    "agent": "chief",
    "name": "Brain tidy-up",
    "task": "Tidy the brain: turn the sources added in the last 24 hours into docs.",
    "days": [
      1,
      2,
      3,
      4,
      5
    ],
    "hour": 7,
    "minute": 0,
    "every": null,
    "cron": null,
    "timezone": "Europe/Berlin",
    "notify": true,
    "paused": true,
    "nextRunAt": null,
    "lastRunAt": null,
    "lastRunId": null,
    "lastError": null,
    "threadId": null,
    "createdAt": "2026-09-01T09:00:00.000Z"
  }
}

Delete a routine

DELETE /api/v1/routines/{id}

Stops a routine for good. Its conversation and past runs stay. Needs an owner or admin.

• CLI: troopy routines delete
• Scopes: agents:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "deleted": true
  }
}

Run a routine now

POST /api/v1/routines/{id}/run

Starts a routine now, without changing when it runs next. Answers 202 with the run. Poll statusUrl. Needs an owner or admin.

• CLI: troopy routines run. MCP tool: troopy_run_routine
• Scopes: agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000013",
    "agent": "chief",
    "kind": "work",
    "trigger": {
      "type": "routine",
      "threadId": "6650c0ffee00000000000018",
      "routineId": "6650c0ffee00000000000016",
      "fromRunId": null,
      "troopThreadId": null
    },
    "taskId": null,
    "task": "Tidy the brain: turn the sources added in the last 24 hours into docs.",
    "status": "queued",
    "roleVersion": 1,
    "summary": "",
    "error": null,
    "doing": null,
    "toolCalls": 0,
    "skills": [],
    "requestedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-09-01T09:04:00.000Z",
    "finishedAt": null,
    "statusUrl": "https://troopy.ai/api/v1/runs/6650c0ffee00000000000013",
    "reply": null,
    "cites": [
      {
        "type": "source",
        "id": "6650c0ffee0000000000000e",
        "title": "Wholesale terms",
        "kind": "note",
        "wrong": null
      }
    ],
    "draft": null,
    "rounds": []
  }
}

List triggers

GET /api/v1/triggers

The triggers of the workspace: each starts a teammate when an event comes, with a task for the work. A webhook trigger takes requests at its own URL. An event trigger starts on something in a product of Troopy. The URL and the secret of a trigger show in the app only.

• CLI: troopy triggers list. MCP tool: troopy_list_triggers
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee0000000000001a",
      "agent": "chief",
      "name": "New GitHub issue",
      "task": "Read the new issue. Say in one line what it asks for, and make a task for it.",
      "source": "webhook",
      "event": null,
      "option": null,
      "sender": "github",
      "needsSecret": false,
      "fields": [
        "action",
        "issue.title",
        "issue.body"
      ],
      "maxPerDay": 20,
      "paused": false,
      "pausedWhy": null,
      "lastEventAt": "2026-10-13T09:12:00.000Z",
      "today": {
        "events": 3,
        "tasks": 2
      },
      "createdAt": "2026-10-12T08:00:00.000Z"
    }
  ]
}

Make a trigger

POST /api/v1/triggers

Makes a trigger. Without event, it is a webhook: each request to its URL is an event, and the teammate gets a task with its instructions and the event. With event, something in a product of Troopy starts it, and each event names the record to read: send no sender, secret or fields then. An event is material for the teammate, never instructions. Events that come before the teammate starts go on one task. Every run uses the organization's AI plan, so this needs an owner or admin. Get the URL of a webhook trigger in the app, on the page of its routine (Routines).

• CLI: troopy triggers create. MCP tool: troopy_create_trigger
• Scopes: agents:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000001a",
    "agent": "chief",
    "name": "New GitHub issue",
    "task": "Read the new issue. Say in one line what it asks for, and make a task for it.",
    "source": "webhook",
    "event": null,
    "option": null,
    "sender": "github",
    "needsSecret": false,
    "fields": [
      "action",
      "issue.title",
      "issue.body"
    ],
    "maxPerDay": 20,
    "paused": false,
    "pausedWhy": null,
    "lastEventAt": null,
    "today": {
      "events": 0,
      "tasks": 0
    },
    "createdAt": "2026-10-12T08:00:00.000Z"
  }
}

Read a trigger

GET /api/v1/triggers/{id}

One trigger with its newest events: where each stands, and the task that holds it. Only owners and admins get what an event said.

• CLI: troopy triggers get. MCP tool: troopy_get_trigger
• Scopes: agents:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "id": "6650c0ffee0000000000001a",
    "agent": "chief",
    "name": "New GitHub issue",
    "task": "Read the new issue. Say in one line what it asks for, and make a task for it.",
    "source": "webhook",
    "event": null,
    "option": null,
    "sender": "github",
    "needsSecret": false,
    "fields": [
      "action",
      "issue.title",
      "issue.body"
    ],
    "maxPerDay": 20,
    "paused": false,
    "pausedWhy": null,
    "lastEventAt": "2026-10-13T09:12:00.000Z",
    "today": {
      "events": 3,
      "tasks": 2
    },
    "createdAt": "2026-10-12T08:00:00.000Z",
    "events": [
      {
        "id": "6650c0ffee0000000000001b",
        "at": "2026-10-13T09:12:00.000Z",
        "summary": "issues.opened",
        "test": false,
        "state": "task",
        "why": null,
        "task": {
          "key": "VIR-31",
          "status": "in_review"
        },
        "text": "{\n \"action\": \"opened\",\n \"issue\": {\n  \"title\": \"Export fails on Safari\"\n }\n}"
      }
    ]
  }
}

Change a trigger

PATCH /api/v1/triggers/{id}

Changes a trigger, pauses or resumes it, or gives it to another teammate (agent); send any of them. A paused trigger keeps its events and starts nothing. A new sender needs its own secret. What starts a trigger never changes: make a new trigger for another event. Needs an owner or admin.

• CLI: troopy triggers update. MCP tool: troopy_update_trigger
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000001a",
    "agent": "chief",
    "name": "New GitHub issue",
    "task": "Read the new issue. Say in one line what it asks for, and make a task for it.",
    "source": "webhook",
    "event": null,
    "option": null,
    "sender": "github",
    "needsSecret": false,
    "fields": [
      "action",
      "issue.title",
      "issue.body"
    ],
    "maxPerDay": 20,
    "paused": true,
    "pausedWhy": null,
    "lastEventAt": "2026-10-13T09:12:00.000Z",
    "today": {
      "events": 3,
      "tasks": 2
    },
    "createdAt": "2026-10-12T08:00:00.000Z"
  }
}

Delete a trigger

DELETE /api/v1/triggers/{id}

Stops a trigger for good, and deletes its events. Its URL stops at once. Its tasks stay, and a task that no teammate started is canceled. Needs an owner or admin.

• CLI: troopy triggers delete
• Scopes: agents:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "deleted": true
  }
}

Send a test event

POST /api/v1/triggers/{id}/test

Sends an example event to a trigger that is on. It starts the teammate for real, and the task says that it is a test. The limit of the day does not hold it back. Needs an owner or admin.

• CLI: troopy triggers test. MCP tool: troopy_test_trigger
• Scopes: agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000001b",
    "at": "2026-10-13T09:12:00.000Z",
    "summary": "test",
    "test": true,
    "state": "task",
    "why": null,
    "task": {
      "key": "VIR-31",
      "status": "in_review"
    },
    "text": "{\n \"action\": \"opened\",\n \"issue\": {\n  \"title\": \"Export fails on Safari\"\n }\n}"
  }
}

Run a held event

POST /api/v1/triggers/{id}/events/{event}/run

Starts the teammate on an event that started nothing: its trigger was paused, or it was past the limit of the day. The trigger must be on. The limit of the day does not hold it back. Needs an owner or admin.

• CLI: troopy triggers run-event. MCP tool: troopy_run_trigger_event
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000001b",
    "at": "2026-10-13T09:12:00.000Z",
    "summary": "issues.opened",
    "test": false,
    "state": "task",
    "why": null,
    "task": {
      "key": "VIR-31",
      "status": "in_review"
    },
    "text": "{\n \"action\": \"opened\",\n \"issue\": {\n  \"title\": \"Export fails on Safari\"\n }\n}"
  }
}

List templates

GET /api/v1/templates

The templates of the work that the troop can take on. A routine template is a routine on a schedule: switch it on with POST /templates/{id}/on. A trigger template starts a teammate when something happens in Troopy: switch it on with POST /templates/{id}/trigger. A ready skill is a skill that a teammate writes for the troop when you ask it: GET /templates/{id} gives the message to send. A built-in template is work that Troopy does itself: disputes prepares the answers to disputes, and PATCH /dispute-settings turns it on.

• CLI: troopy templates list. MCP tool: troopy_list_templates
• Scopes: agents:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "id": "overdue-invoices",
      "kind": "routine",
      "title": "Overdue invoices",
      "about": "Drafts a polite reminder for each customer with an overdue invoice in Stripe.",
      "role": "churn",
      "roleTitle": "Churn watcher",
      "avatar": {
        "shape": "ghost",
        "color": "#A7E3E0",
        "face": "eyes"
      },
      "agent": "churn",
      "agentName": "Churn watcher",
      "skill": "overdue-invoices",
      "when": "Weekdays at 09:00",
      "needs": [
        {
          "id": "stripe",
          "name": "Stripe",
          "connected": true
        }
      ],
      "uses": [
        {
          "id": "stripe",
          "name": "Stripe",
          "ready": true
        },
        {
          "id": "inbox",
          "name": "Its own inbox",
          "ready": null
        }
      ],
      "on": false,
      "paused": false,
      "routineId": null,
      "page": null
    }
  ]
}

Get a template

GET /api/v1/templates/{id}

One template, with how it works in numbered steps. A ready skill also gives the teammate to ask and the message that asks it to write the skill.

• CLI: troopy templates get. MCP tool: troopy_get_template
• Scopes: agents:read
• At most 60 calls per 60 seconds per key

{
  "data": {
    "id": "overdue-invoices",
    "kind": "routine",
    "title": "Overdue invoices",
    "about": "Drafts a polite reminder for each customer with an overdue invoice in Stripe.",
    "role": "churn",
    "roleTitle": "Churn watcher",
    "avatar": {
      "shape": "ghost",
      "color": "#A7E3E0",
      "face": "eyes"
    },
    "agent": "churn",
    "agentName": "Churn watcher",
    "skill": "overdue-invoices",
    "when": "Weekdays at 09:00",
    "needs": [
      {
        "id": "stripe",
        "name": "Stripe",
        "connected": true
      }
    ],
    "uses": [
      {
        "id": "stripe",
        "name": "Stripe",
        "ready": true
      },
      {
        "id": "inbox",
        "name": "Its own inbox",
        "ready": null
      }
    ],
    "on": false,
    "paused": false,
    "routineId": null,
    "page": null,
    "steps": "1. Checks what is due: Finds the overdue invoices in Stripe, the reminders that it sent, and the answers that came back.\n2. Follows your rules: Writes the next reminder at 1, 3 and 10 days overdue, or as its notes say.\n3. Waits for a yes: Sends each reminder from its own address after an owner or admin says yes.\n4. Pauses for a promise: A reply that promises to pay pauses the chase for 7 days. A dispute goes to you.\n5. Hands over the rest: After three reminders, lists the invoice for you to call or write off.",
    "outcomes": [
      "Every overdue invoice chased on time",
      "No reminder goes without your yes",
      "Promises and disputes handled as a person would"
    ],
    "sample": {
      "kind": "email",
      "label": "Subject: Invoice 1042: reminder 2",
      "lines": [
        "Hi Sam,",
        "Invoice 1042 for $480 is now 3 days overdue.",
        "You can pay it here: [the link to pay]",
        "If you paid it already, thank you."
      ]
    },
    "ask": null
  }
}

Switch on a routine template

POST /api/v1/templates/{id}/on

Gives the teammate of the role of a routine template its routine, at the days and time of the template in timezone. It hires the role first when nobody holds it. A template that is on already gives its routine as it is. Needs an owner or admin, and the services of the role connected. A ready skill, a built-in template and a trigger template give 400: POST /templates/{id}/trigger switches a trigger template on.

• CLI: troopy templates on. MCP tool: troopy_switch_on_template
• Scopes: agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000016",
    "agent": "churn",
    "name": "Overdue invoices",
    "task": "Draft reminders for overdue invoices, following your overdue-invoices skill.",
    "days": [
      1,
      2,
      3,
      4,
      5
    ],
    "hour": 9,
    "minute": 0,
    "every": null,
    "cron": null,
    "timezone": "Europe/Berlin",
    "notify": true,
    "paused": false,
    "nextRunAt": "2026-09-02T05:00:00.000Z",
    "lastRunAt": null,
    "lastRunId": null,
    "lastError": null,
    "threadId": null,
    "createdAt": "2026-09-01T09:00:00.000Z"
  }
}

Switch on a trigger template

POST /api/v1/templates/{id}/trigger

Makes the trigger of a trigger template for the teammate of its role: each time its event comes in Troopy, the teammate gets a task with the instructions of the template. It hires the role first when nobody holds it. A trigger template that is on already gives its trigger as it is. Change the instructions with PATCH /triggers/{id}. Needs an owner or admin, and the services of the role connected. A routine template, a ready skill and a built-in template give 404.

• CLI: troopy templates trigger. MCP tool: troopy_switch_on_trigger_template
• Scopes: agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee0000000000001a",
    "agent": "churn",
    "name": "Cancel check-in",
    "task": "Read the customer of each event, following your customer-lookup skill. Draft a short check-in email that asks why the customer leaves.",
    "source": "event",
    "event": "customer.cancel_requested",
    "option": null,
    "sender": "url",
    "needsSecret": false,
    "fields": [],
    "maxPerDay": 20,
    "paused": false,
    "pausedWhy": null,
    "lastEventAt": null,
    "today": {
      "events": 0,
      "tasks": 0
    },
    "createdAt": "2026-10-12T08:00:00.000Z"
  }
}

List the tools of teammates

GET /api/v1/teammate-tools

Every tool that teammates use, in families: what it gives, which teammates hold it, whether it is on, and its calls in the last 30 days. An owner or admin switches a family or a tool off with PATCH /teammate-tools.

• CLI: troopy tools list. MCP tool: troopy_list_teammate_tools
• Scopes: agents:read
• At most 60 calls per 60 seconds per key

{
  "data": {
    "days": 30,
    "switchable": 70,
    "on": 70,
    "teammates": [
      {
        "handle": "researcher",
        "name": "Researcher",
        "avatar": {
          "shape": "flower",
          "color": "#C9D8F2",
          "face": "eyes"
        },
        "paused": false,
        "uses": 42
      }
    ],
    "families": [
      {
        "key": "web",
        "section": "web",
        "name": "Web pages and search",
        "about": "Search the web and the news, read the pages that a teammate may read, and take pictures of them.",
        "always": false,
        "whole": false,
        "stops": "Research needs web search.",
        "needs": [],
        "tools": [
          {
            "id": "search_web",
            "label": "Search the web",
            "about": "Searches Google, Bing or DuckDuckGo in its own browser",
            "on": true,
            "asks": false,
            "holders": [
              "researcher"
            ],
            "uses": 30,
            "usedBy": [
              {
                "handle": "researcher",
                "uses": 30
              }
            ]
          },
          {
            "id": "read_web_page",
            "label": "Read a web page",
            "about": "Reads a page of a site that it may read",
            "on": true,
            "asks": false,
            "holders": [
              "researcher"
            ],
            "uses": 12,
            "usedBy": [
              {
                "handle": "researcher",
                "uses": 12
              }
            ]
          }
        ]
      }
    ],
    "tasks": [
      {
        "key": "VIR-12",
        "title": "Who sells flour in Berlin?",
        "uses": 34,
        "usedBy": [
          {
            "handle": "researcher",
            "uses": 34
          }
        ]
      }
    ],
    "noTask": {
      "uses": 8,
      "usedBy": [
        {
          "handle": "researcher",
          "uses": 8
        }
      ]
    }
  }
}

Switch teammate tools on or off

PATCH /api/v1/teammate-tools

Switches families or single tools on or off for the whole troop. A run leaves out the tools that are off. The families that the troop needs stay on. A family that switches as one takes its key in families, not one of its tools. Needs an owner or admin.

• CLI: troopy tools switch
• Scopes: agents:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "days": 30,
    "switchable": 70,
    "on": 65,
    "teammates": [
      {
        "handle": "researcher",
        "name": "Researcher",
        "avatar": {
          "shape": "flower",
          "color": "#C9D8F2",
          "face": "eyes"
        },
        "paused": false,
        "uses": 42
      }
    ],
    "families": [
      {
        "key": "web",
        "section": "web",
        "name": "Web pages and search",
        "about": "Search the web and the news, read the pages that a teammate may read, and take pictures of them.",
        "always": false,
        "whole": false,
        "stops": "Research needs web search.",
        "needs": [],
        "tools": [
          {
            "id": "search_web",
            "label": "Search the web",
            "about": "Searches Google, Bing or DuckDuckGo in its own browser",
            "on": false,
            "asks": false,
            "holders": [
              "researcher"
            ],
            "uses": 30,
            "usedBy": [
              {
                "handle": "researcher",
                "uses": 30
              }
            ]
          },
          {
            "id": "read_web_page",
            "label": "Read a web page",
            "about": "Reads a page of a site that it may read",
            "on": false,
            "asks": false,
            "holders": [
              "researcher"
            ],
            "uses": 12,
            "usedBy": [
              {
                "handle": "researcher",
                "uses": 12
              }
            ]
          }
        ]
      }
    ],
    "tasks": [
      {
        "key": "VIR-12",
        "title": "Who sells flour in Berlin?",
        "uses": 34,
        "usedBy": [
          {
            "handle": "researcher",
            "uses": 34
          }
        ]
      }
    ],
    "noTask": {
      "uses": 8,
      "usedBy": [
        {
          "handle": "researcher",
          "uses": 8
        }
      ]
    }
  }
}

List apps

GET /api/v1/apps

The services this workspace can connect, and which are connected. Keys never leave Troopy: only their last four characters show.

• CLI: troopy apps list. MCP tool: troopy_list_apps
• Scopes: workspace:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "provider": "stripe",
      "name": "Stripe",
      "status": "connected",
      "mode": "live",
      "account": null,
      "pictures": false,
      "hint": "x9Qa",
      "connectedBy": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "connectedAt": "2026-09-01T09:00:00.000Z",
      "lastUsedAt": "2026-09-07T08:31:00.000Z",
      "choices": null
    }
  ]
}

Connect an app

POST /api/v1/apps/{provider}

Connects a service to this workspace with its API key, which Troopy checks with the service and stores sealed. Troopy only reads. GitHub connects from Settings instead: it installs Troopy's GitHub App on the repos you pick. For Stripe, use a restricted key (rk_live_ or rk_test_) with Read access to Customers, Subscriptions, Invoices and Charges. To have Troopy answer disputes, add Read and Write access to Disputes and Write access to Files: the evidence of a dispute is the one thing that Troopy writes in Stripe. For PostHog (US or EU cloud), use a personal API key (phx_) with Query read and Project read; send project when the key reaches more than one project. Connecting again replaces the key. Needs an owner or admin.

• CLI: troopy apps connect
• Scopes: apps:write
• At most 10 calls per 60 seconds per key

{
  "data": {
    "provider": "stripe",
    "name": "Stripe",
    "status": "connected",
    "mode": "live",
    "account": null,
    "pictures": false,
    "hint": "x9Qa",
    "connectedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "connectedAt": "2026-09-01T09:00:00.000Z",
    "lastUsedAt": "2026-09-07T08:31:00.000Z",
    "choices": null
  }
}

List the GitHub repos

GET /api/v1/apps/github/repos

The repos Troopy's GitHub App reaches in this workspace (the ones picked when it was installed), each with the commands the Engineer uses: setup installs what the code needs, test says whether a change works. Troopy guesses both the first time; an empty test means changes to that repo can't be checked, so no pull request opens.

• CLI: troopy github repos. MCP tool: troopy_list_repos
• Scopes: apps:read
• At most 30 calls per 60 seconds per key

{
  "data": [
    {
      "fullName": "viraloop/app",
      "defaultBranch": "main",
      "private": true,
      "setup": "npm ci",
      "test": "npm test"
    }
  ]
}

Set a repo's commands

PATCH /api/v1/apps/github/repos

Sets how the Engineer installs a repo's dependencies (setup, run with network to package registries only) and checks a change (test, run with no network). They run on the workspace's computer, in a sandbox that sees only the repo. Needs an owner or admin.

• CLI: troopy github set-repo
• Scopes: apps:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "fullName": "viraloop/app",
    "defaultBranch": "main",
    "private": true,
    "setup": "npm ci",
    "test": "npm test"
  }
}

Choose what an app reads

PATCH /api/v1/apps/{provider}

Chooses what a connection reads. For Search Console, choose one property. For Meta Ads, choose the ad accounts, and the campaigns that Analytics tracks (null tracks all of them). The ids come from choices, and from the campaigns of getAnalyticsAds. For an image provider, choose the model that makes its pictures. Needs an owner or admin.

• CLI: troopy apps choose
• Scopes: apps:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "provider": "searchconsole",
    "name": "Google Search Console",
    "status": "connected",
    "mode": null,
    "account": "sc-domain:acme.com",
    "pictures": false,
    "hint": "Google",
    "connectedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "connectedAt": "2026-09-01T09:00:00.000Z",
    "lastUsedAt": "2026-09-07T08:31:00.000Z",
    "choices": [
      {
        "id": "sc-domain:acme.com",
        "label": "sc-domain:acme.com",
        "chosen": true
      }
    ]
  }
}

Disconnect an app

DELETE /api/v1/apps/{provider}

Forgets the service's key. Teammates that need it stop until it is connected again. Needs an owner or admin.

• CLI: troopy apps disconnect. MCP tool: troopy_disconnect_app
• Scopes: apps:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "provider": "stripe",
    "name": "Stripe",
    "status": "not_connected",
    "mode": null,
    "account": null,
    "pictures": false,
    "hint": null,
    "connectedBy": null,
    "connectedAt": null,
    "lastUsedAt": "2026-09-07T08:31:00.000Z",
    "choices": null
  }
}

List the custom apps

GET /api/v1/custom-apps

The apps that this workspace added itself: remote MCP servers, each with its tools and the mode of each tool. Teammates call a tool with call_app_tool. A tool in the mode ask waits for the yes of an owner or admin. No key or token ever comes out.

• CLI: troopy custom-apps list. MCP tool: troopy_list_custom_apps
• Scopes: apps:read
• At most 30 calls per 60 seconds per key

{
  "data": [
    {
      "slug": "acme_crm",
      "name": "Acme CRM",
      "url": "https://mcp.acme.example/mcp",
      "auth": "key",
      "status": "connected",
      "error": null,
      "tools": [
        {
          "name": "search_contacts",
          "description": "Finds contacts by name or email.",
          "mode": "free"
        },
        {
          "name": "create_contact",
          "description": "Adds a contact.",
          "mode": "ask"
        }
      ],
      "listedAt": "2026-10-17T09:00:00.000Z",
      "connectedBy": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "connectedAt": "2026-10-17T09:00:00.000Z",
      "signIn": null
    }
  ]
}

Add a custom app

POST /api/v1/custom-apps

Adds a remote MCP server, by the https address of its Streamable HTTP endpoint (SSE servers are refused), and lists its tools at once, 40 at most. With key, Troopy sends it in Authorization as a Bearer token, or in header. A server that asks for a sign-in waits for one: its status is needs_sign_in, and a person opens signIn in a browser. A tool that the server marks read-only runs when a teammate calls it. Each other tool waits for the yes of an owner or admin. A workspace adds 10 apps. Needs an owner or admin.

• CLI: troopy custom-apps add
• Scopes: apps:write
• At most 10 calls per 60 seconds per key

{
  "data": {
    "slug": "acme_crm",
    "name": "Acme CRM",
    "url": "https://mcp.acme.example/mcp",
    "auth": "key",
    "status": "connected",
    "error": null,
    "tools": [
      {
        "name": "search_contacts",
        "description": "Finds contacts by name or email.",
        "mode": "free"
      },
      {
        "name": "create_contact",
        "description": "Adds a contact.",
        "mode": "ask"
      }
    ],
    "listedAt": "2026-10-17T09:00:00.000Z",
    "connectedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "connectedAt": "2026-10-17T09:00:00.000Z",
    "signIn": null
  }
}

Change a custom app

PATCH /api/v1/custom-apps/{slug}

Changes the name of an app, its key, or the mode of its tools: free runs, ask waits for the yes of an owner or admin, off is never called. A new key lists the tools again. Needs an owner or admin.

• CLI: troopy custom-apps update
• Scopes: apps:write
• At most 20 calls per 60 seconds per key

{
  "data": {
    "slug": "acme_crm",
    "name": "Acme CRM",
    "url": "https://mcp.acme.example/mcp",
    "auth": "key",
    "status": "connected",
    "error": null,
    "tools": [
      {
        "name": "search_contacts",
        "description": "Finds contacts by name or email.",
        "mode": "free"
      },
      {
        "name": "create_contact",
        "description": "Adds a contact.",
        "mode": "ask"
      }
    ],
    "listedAt": "2026-10-17T09:00:00.000Z",
    "connectedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "connectedAt": "2026-10-17T09:00:00.000Z",
    "signIn": null
  }
}

List the tools of a custom app again

POST /api/v1/custom-apps/{slug}/tools

Reads the tools of the server again. A tool that the app had keeps its mode. A new tool runs if the server marks it read-only, and waits for a yes if not. Needs an owner or admin: only a person brings new words of a server in.

• CLI: troopy custom-apps tools
• Scopes: apps:write
• At most 10 calls per 60 seconds per key

{
  "data": {
    "slug": "acme_crm",
    "name": "Acme CRM",
    "url": "https://mcp.acme.example/mcp",
    "auth": "key",
    "status": "connected",
    "error": null,
    "tools": [
      {
        "name": "search_contacts",
        "description": "Finds contacts by name or email.",
        "mode": "free"
      },
      {
        "name": "create_contact",
        "description": "Adds a contact.",
        "mode": "ask"
      }
    ],
    "listedAt": "2026-10-17T09:00:00.000Z",
    "connectedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "connectedAt": "2026-10-17T09:00:00.000Z",
    "signIn": null
  }
}

Remove a custom app

DELETE /api/v1/custom-apps/{slug}

Removes an app and forgets its key or its sign-in. Its calls that wait for a yes fail when someone says yes. Needs an owner or admin.

• CLI: troopy custom-apps remove. MCP tool: troopy_remove_custom_app
• Scopes: apps:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "slug": "acme_crm",
    "name": "Acme CRM",
    "url": "https://mcp.acme.example/mcp",
    "auth": "key",
    "status": "connected",
    "error": null,
    "tools": [
      {
        "name": "search_contacts",
        "description": "Finds contacts by name or email.",
        "mode": "free"
      },
      {
        "name": "create_contact",
        "description": "Adds a contact.",
        "mode": "ask"
      }
    ],
    "listedAt": "2026-10-17T09:00:00.000Z",
    "connectedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "connectedAt": "2026-10-17T09:00:00.000Z",
    "signIn": null
  }
}

List vault collections

GET /api/v1/vault/collections

The workspace's vault collections you can reach, each with who may use it and what you may do in it. Every item lives in one. Collections and who reaches them are set in the app.

• CLI: troopy vault collections. MCP tool: troopy_list_vault_collections
• Scopes: vault:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "id": "66f7a1c2e4b0a1b2c3d4e5f0",
      "name": "Shared",
      "everyone": "use",
      "people": [],
      "teammates": [
        {
          "handle": "nova",
          "name": "Nova"
        }
      ],
      "isDefault": true,
      "receivesSignups": false,
      "madeBy": null,
      "level": "manage",
      "items": 12
    }
  ]
}

List vault items

GET /api/v1/vault/items

The vault's items you can reach, by name. Concealed values (passwords, keys, card numbers, notes) are never returned: people reveal them in the app after unlocking, and teammates use logins without ever seeing them.

• CLI: troopy vault list. MCP tool: troopy_list_vault_items
• Scopes: vault:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "id": "66f7a1c2e4b0a1b2c3d4e5f6",
      "collection": {
        "id": "66f7a1c2e4b0a1b2c3d4e5f0",
        "name": "Shared"
      },
      "kind": "login",
      "name": "Canva",
      "tags": [
        "design"
      ],
      "urls": [
        "https://www.canva.com/login"
      ],
      "sites": [
        "canva.com"
      ],
      "environment": null,
      "expiresAt": null,
      "fields": [
        {
          "key": "username",
          "label": "Username",
          "type": "text",
          "concealed": false,
          "value": "ops@acme.com",
          "hint": null,
          "set": true
        },
        {
          "key": "password",
          "label": "Password",
          "type": "password",
          "concealed": true,
          "value": null,
          "hint": null,
          "set": true
        },
        {
          "key": "totp",
          "label": "One-time code",
          "type": "totp",
          "concealed": true,
          "value": null,
          "hint": null,
          "set": false
        },
        {
          "key": "notes",
          "label": "Notes",
          "type": "multiline",
          "concealed": true,
          "value": null,
          "hint": null,
          "set": false
        }
      ],
      "status": "active",
      "importedFrom": null,
      "createdBy": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "updatedBy": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "level": "manage",
      "createdAt": "2026-09-30T09:00:00.000Z",
      "updatedAt": "2026-09-30T09:00:00.000Z",
      "lastUsedAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Get a vault item

GET /api/v1/vault/items/{id}

One vault item: its fields (concealed values never included), sites, tags and who added it.

• CLI: troopy vault get. MCP tool: troopy_get_vault_item
• Scopes: vault:read
• At most 60 calls per 60 seconds per key

{
  "data": {
    "id": "66f7a1c2e4b0a1b2c3d4e5f6",
    "collection": {
      "id": "66f7a1c2e4b0a1b2c3d4e5f0",
      "name": "Shared"
    },
    "kind": "login",
    "name": "Canva",
    "tags": [
      "design"
    ],
    "urls": [
      "https://www.canva.com/login"
    ],
    "sites": [
      "canva.com"
    ],
    "environment": null,
    "expiresAt": null,
    "fields": [
      {
        "key": "username",
        "label": "Username",
        "type": "text",
        "concealed": false,
        "value": "ops@acme.com",
        "hint": null,
        "set": true
      },
      {
        "key": "password",
        "label": "Password",
        "type": "password",
        "concealed": true,
        "value": null,
        "hint": null,
        "set": true
      },
      {
        "key": "totp",
        "label": "One-time code",
        "type": "totp",
        "concealed": true,
        "value": null,
        "hint": null,
        "set": false
      },
      {
        "key": "notes",
        "label": "Notes",
        "type": "multiline",
        "concealed": true,
        "value": null,
        "hint": null,
        "set": false
      }
    ],
    "status": "active",
    "importedFrom": null,
    "createdBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "level": "manage",
    "createdAt": "2026-09-30T09:00:00.000Z",
    "updatedAt": "2026-09-30T09:00:00.000Z",
    "lastUsedAt": null
  }
}

Add a vault item

POST /api/v1/vault/items

Adds a login, API key, secret or note to a collection you may use (the default one unless you name another). Values go in sealed and never come out through the API. Cards are added in the app only. A login's urls say where it may be used; they can't be changed through the API later.

• CLI: troopy vault add
• Scopes: vault:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "66f7a1c2e4b0a1b2c3d4e5f6",
    "collection": {
      "id": "66f7a1c2e4b0a1b2c3d4e5f0",
      "name": "Shared"
    },
    "kind": "login",
    "name": "Canva",
    "tags": [
      "design"
    ],
    "urls": [
      "https://www.canva.com/login"
    ],
    "sites": [
      "canva.com"
    ],
    "environment": null,
    "expiresAt": null,
    "fields": [
      {
        "key": "username",
        "label": "Username",
        "type": "text",
        "concealed": false,
        "value": "ops@acme.com",
        "hint": null,
        "set": true
      },
      {
        "key": "password",
        "label": "Password",
        "type": "password",
        "concealed": true,
        "value": null,
        "hint": null,
        "set": true
      },
      {
        "key": "totp",
        "label": "One-time code",
        "type": "totp",
        "concealed": true,
        "value": null,
        "hint": null,
        "set": false
      },
      {
        "key": "notes",
        "label": "Notes",
        "type": "multiline",
        "concealed": true,
        "value": null,
        "hint": null,
        "set": false
      }
    ],
    "status": "active",
    "importedFrom": null,
    "createdBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "level": "manage",
    "createdAt": "2026-09-30T09:00:00.000Z",
    "updatedAt": "2026-09-30T09:00:00.000Z",
    "lastUsedAt": null
  }
}

Change a vault item

PATCH /api/v1/vault/items/{id}

Changes an item's name, tags, expiry or values: send only what changes; a value set to null is cleared (a custom field's is removed). The old value of a concealed field is kept in its history. Its collection and urls change in the app only.

• CLI: troopy vault update
• Scopes: vault:write
• At most 30 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "66f7a1c2e4b0a1b2c3d4e5f6",
    "collection": {
      "id": "66f7a1c2e4b0a1b2c3d4e5f0",
      "name": "Shared"
    },
    "kind": "login",
    "name": "Canva",
    "tags": [
      "design"
    ],
    "urls": [
      "https://www.canva.com/login"
    ],
    "sites": [
      "canva.com"
    ],
    "environment": null,
    "expiresAt": null,
    "fields": [
      {
        "key": "username",
        "label": "Username",
        "type": "text",
        "concealed": false,
        "value": "ops@acme.com",
        "hint": null,
        "set": true
      },
      {
        "key": "password",
        "label": "Password",
        "type": "password",
        "concealed": true,
        "value": null,
        "hint": null,
        "set": true
      },
      {
        "key": "totp",
        "label": "One-time code",
        "type": "totp",
        "concealed": true,
        "value": null,
        "hint": null,
        "set": false
      },
      {
        "key": "notes",
        "label": "Notes",
        "type": "multiline",
        "concealed": true,
        "value": null,
        "hint": null,
        "set": false
      }
    ],
    "status": "active",
    "importedFrom": null,
    "createdBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "level": "manage",
    "createdAt": "2026-09-30T09:00:00.000Z",
    "updatedAt": "2026-09-30T09:00:00.000Z",
    "lastUsedAt": null
  }
}

Delete a vault item

DELETE /api/v1/vault/items/{id}

Deletes an item and its history, for good. Whoever added it, and people who manage its collection.

• CLI: troopy vault delete
• Scopes: vault:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "deleted": true
  }
}

List vault activity

GET /api/v1/vault/events

What happened in the vault, newest first: items added, changed, revealed, used by teammates or deleted. Never a value. One item's activity for anyone who sees it; everything for owners and admins.

• CLI: troopy vault activity. MCP tool: troopy_list_vault_events
• Scopes: vault:read
• At most 30 calls per 60 seconds per key

{
  "data": [
    {
      "id": "66f7a1c2e4b0a1b2c3d4e5f9",
      "type": "filled",
      "item": {
        "id": "66f7a1c2e4b0a1b2c3d4e5f6",
        "name": "Canva"
      },
      "by": {
        "type": "agent",
        "id": "66f7a1c2e4b0a1b2c3d4e5f1",
        "name": "Nova"
      },
      "field": "password",
      "site": "canva.com",
      "detail": null,
      "at": "2026-09-30T10:12:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

List calendar events

GET /api/v1/apps/googlecalendar/events

The events of the Google Calendar that the workspace connected, the soonest first: from now (or from), until 2 days later (or to), 50 at most. A private event shows only as busy time: its title, people and notes stay out. connected is false until an owner or admin connects Google Calendar in Settings > Apps. Read only.

• CLI: troopy calendar events. MCP tool: troopy_calendar_events
• Scopes: apps:read
• At most 60 calls per 60 seconds per key

{
  "data": {
    "connected": true,
    "account": "sam@acme.example",
    "events": [
      {
        "id": "7k2m9qa1b3c4d5",
        "title": "Intro call with Bright Smile",
        "start": "2026-10-12T15:00:00+02:00",
        "end": "2026-10-12T15:30:00+02:00",
        "allDay": false,
        "location": null,
        "organizer": "sam@acme.example",
        "attendees": [
          {
            "email": "jane@brightsmile.example",
            "name": "Jane Doe",
            "response": "accepted"
          }
        ],
        "notes": "Talk about the booking page.",
        "private": false
      }
    ],
    "more": false
  }
}

List Stripe customers

GET /api/v1/apps/stripe/customers

Customers in the workspace's Stripe, newest first: one by exact email, those whose name contains query, or those created since a date. Read only. Needs Stripe connected.

• CLI: troopy stripe customers. MCP tool: troopy_stripe_customers
• Scopes: apps:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "id": "cus_Q1a2b3",
      "email": "grace@example.com",
      "name": "Grace Hopper",
      "created": "2025-03-02T10:00:00.000Z",
      "delinquent": false,
      "balance": 0,
      "currency": "usd"
    }
  ],
  "hasMore": false,
  "next": null
}

List Stripe subscriptions

GET /api/v1/apps/stripe/subscriptions

Subscriptions in the workspace's Stripe, newest first, with their customer, price and how they end. Filter by status, by customer, to those set to end at the period's end (endingSoon), or to those canceled since a date. Read only. Needs Stripe connected.

• CLI: troopy stripe subscriptions. MCP tool: troopy_stripe_subscriptions
• Scopes: apps:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "id": "sub_1Pz",
      "customer": {
        "id": "cus_Q1a2b3",
        "email": "grace@example.com",
        "name": "Grace Hopper"
      },
      "status": "past_due",
      "items": [
        {
          "product": "prod_9",
          "price": "price_7",
          "nickname": "Pro monthly",
          "amount": 49,
          "currency": "usd",
          "interval": "month",
          "quantity": 1
        }
      ],
      "cancelAtPeriodEnd": false,
      "currentPeriodEnd": "2026-09-30T00:00:00.000Z",
      "canceledAt": null,
      "endedAt": null,
      "cancellation": {
        "reason": null,
        "feedback": null,
        "comment": null
      },
      "trialEnd": null,
      "created": "2025-03-02T10:00:00.000Z"
    }
  ],
  "hasMore": false,
  "next": null
}

List failed Stripe payments

GET /api/v1/apps/stripe/failed-payments

Card payments that failed in the workspace's Stripe since a date (the last 7 days by default), newest first, with why they failed. Read only. Needs Stripe connected.

• CLI: troopy stripe failed-payments. MCP tool: troopy_stripe_failed_payments
• Scopes: apps:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "id": "ch_3Q",
      "customer": "cus_Q1a2b3",
      "email": "grace@example.com",
      "amount": 49,
      "currency": "usd",
      "failureCode": "card_declined",
      "failureMessage": "Your card was declined.",
      "invoice": "in_1Q",
      "created": "2026-09-05T03:00:00.000Z"
    }
  ],
  "hasMore": false,
  "next": null
}

List Stripe invoices

GET /api/v1/apps/stripe/invoices

Invoices in the workspace's Stripe, newest first: open ones by default, only those past their due date with overdue, or one customer's. Each has its payment page. Read only. Needs Stripe connected.

• CLI: troopy stripe invoices. MCP tool: troopy_stripe_invoices
• Scopes: apps:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "id": "in_1Q",
      "number": "LL-0042",
      "customer": {
        "id": "cus_Q1a2b3",
        "email": "grace@example.com",
        "name": "Grace Hopper"
      },
      "status": "open",
      "amount": 49,
      "currency": "usd",
      "amountRemaining": 49,
      "dueDate": "2026-09-01T00:00:00.000Z",
      "attempts": 2,
      "nextAttempt": "2026-09-08T03:00:00.000Z",
      "url": "https://invoice.stripe.com/i/acct_1/test_x",
      "created": "2026-08-25T00:00:00.000Z"
    }
  ],
  "hasMore": false,
  "next": null
}

List PostHog events

GET /api/v1/apps/posthog/events

The events the workspace's PostHog project recorded in the last days, busiest first (at most 50), with how often and by how many people. Start here to learn the event names. Read only. Needs PostHog connected.

• CLI: troopy posthog events. MCP tool: troopy_posthog_events
• Scopes: apps:read
• At most 30 calls per 60 seconds per key

{
  "data": [
    {
      "event": "$pageview",
      "total": 18234,
      "users": 2210,
      "lastSeen": "2026-09-07T08:12:00Z"
    }
  ]
}

Get a PostHog trend

GET /api/v1/apps/posthog/trend

How one event moved over time in the workspace's PostHog: its count, or the people doing it, per day, week or month, optionally broken down by a property (the five biggest values). Read only. Needs PostHog connected.

• CLI: troopy posthog trend. MCP tool: troopy_posthog_trend
• Scopes: apps:read
• At most 30 calls per 60 seconds per key

{
  "data": {
    "event": "signed_up",
    "measure": "total",
    "interval": "week",
    "series": [
      {
        "label": "signed_up",
        "breakdown": null,
        "total": 412,
        "points": [
          {
            "date": "2026-08-31",
            "value": 97
          }
        ]
      }
    ],
    "moreSeries": 0
  }
}

Get a PostHog funnel

GET /api/v1/apps/posthog/funnel

How many people went through a series of events in order, within a window, in the workspace's PostHog: each step's count, its share of the step before and of the first, and the median time it took. Read only. Needs PostHog connected.

• CLI: troopy posthog funnel. MCP tool: troopy_posthog_funnel
• Scopes: apps:read
• At most 30 calls per 60 seconds per key

{
  "data": {
    "windowDays": 14,
    "steps": [
      {
        "event": "signed_up",
        "count": 412,
        "fromPrevious": null,
        "fromStart": null,
        "medianSeconds": null
      },
      {
        "event": "created_project",
        "count": 250,
        "fromPrevious": 0.607,
        "fromStart": 0.607,
        "medianSeconds": 540
      },
      {
        "event": "paid",
        "count": 31,
        "fromPrevious": 0.124,
        "fromStart": 0.075,
        "medianSeconds": 259200
      }
    ]
  }
}

Query PostHog with HogQL

GET /api/v1/apps/posthog/query

Runs one HogQL SELECT (PostHog's SQL, over tables like events and persons) in the workspace's PostHog and returns at most 100 rows. HogQL can only read. Prefer aggregates (count, uniq, group by) over raw rows. Needs PostHog connected.

• CLI: troopy posthog query. MCP tool: troopy_posthog_query
• Scopes: apps:read
• At most 30 calls per 60 seconds per key

{
  "data": {
    "columns": [
      "count()"
    ],
    "rows": [
      [
        97
      ]
    ],
    "truncated": false
  }
}

List tasks

GET /api/v1/tasks

The workspace's tasks, most recently changed first (or in board order). Filters take several values, comma-separated, and match any of them: status (like `todo,in_progress`), assignee (handles, user ids, `me` or `none`), priority, project (ids, names or `none`), milestone (ids or `none`), area (engineering, marketing, operations), stage (the engineering flow's steps, or `none`), label. Also parent (a task, or `none` for top-level tasks), words in the title, mine (yours: for you, made by you or on your plate) and updatedSince. A teammate looking for work lists `status=todo&assignee=me`.

• CLI: troopy tasks list. MCP tool: troopy_list_tasks
• Scopes: tasks:read
• At most 120 calls per 60 seconds per key

{
  "data": [
    {
      "id": "6650c0ffee00000000000030",
      "key": "VIR-12",
      "number": 12,
      "title": "Write the October newsletter",
      "status": "in_progress",
      "priority": "high",
      "assignee": {
        "type": "agent",
        "id": "writer",
        "name": "Mira"
      },
      "project": {
        "id": "6650c0ffee00000000000031",
        "name": "Autumn launch"
      },
      "milestone": {
        "id": "6650c0ffee00000000000062",
        "name": "Launch day"
      },
      "area": "marketing",
      "parent": null,
      "labels": [
        "newsletter"
      ],
      "dueAt": "2026-10-01",
      "sortOrder": 2048,
      "subOrder": 0,
      "waitsOn": [],
      "blocked": false,
      "progress": {
        "done": 1,
        "total": 2
      },
      "comments": 3,
      "waiting": 0,
      "working": {
        "runId": "6650c0ffee00000000000011",
        "doing": "Drafting the intro"
      },
      "error": null,
      "pr": null,
      "flow": null,
      "requestedBy": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "createdBy": {
        "type": "person",
        "id": "6650c0ffee0000000000000a",
        "name": "Ada Lovelace"
      },
      "createdAt": "2026-09-27T09:00:00.000Z",
      "updatedAt": "2026-09-27T09:05:00.000Z",
      "closedAt": null,
      "version": 3
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Get a task

GET /api/v1/tasks/{key}

One task in full: its description, sub-tasks, what its teammates asked people, and its activity (comments and changes).

• CLI: troopy tasks get. MCP tool: troopy_get_task
• Scopes: tasks:read
• At most 120 calls per 60 seconds per key

{
  "data": {
    "id": "6650c0ffee00000000000030",
    "key": "VIR-12",
    "number": 12,
    "title": "Write the October newsletter",
    "status": "in_progress",
    "priority": "high",
    "assignee": {
      "type": "agent",
      "id": "writer",
      "name": "Mira"
    },
    "project": {
      "id": "6650c0ffee00000000000031",
      "name": "Autumn launch"
    },
    "milestone": {
      "id": "6650c0ffee00000000000062",
      "name": "Launch day"
    },
    "area": "marketing",
    "parent": null,
    "labels": [
      "newsletter"
    ],
    "dueAt": "2026-10-01",
    "sortOrder": 2048,
    "subOrder": 0,
    "waitsOn": [],
    "blocked": false,
    "progress": {
      "done": 1,
      "total": 2
    },
    "comments": 3,
    "waiting": 0,
    "working": {
      "runId": "6650c0ffee00000000000011",
      "doing": "Drafting the intro"
    },
    "error": null,
    "pr": null,
    "flow": null,
    "requestedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-09-27T09:00:00.000Z",
    "updatedAt": "2026-09-27T09:05:00.000Z",
    "closedAt": null,
    "version": 3,
    "description": "Three sections, under 400 words.",
    "subtasks": [],
    "asks": [],
    "activity": [
      {
        "id": "6650c0ffee00000000000032",
        "kind": "comment",
        "by": {
          "type": "person",
          "id": "6650c0ffee0000000000000a",
          "name": "Ada Lovelace"
        },
        "text": "Lead with the new loyalty card, please.",
        "change": null,
        "runId": null,
        "at": "2026-09-27T09:02:00.000Z"
      }
    ],
    "watchers": [],
    "watching": false,
    "reactions": [],
    "attachments": [],
    "code": null
  }
}

Edit an engineering ticket's analysis or plan

PATCH /api/v1/tasks/{key}/docs/{doc}

Rewrites the analysis or the plan of an engineering ticket (flow in GET /tasks/{key}), in markdown. Send the version you read; if it changed since, this answers 409 stale_version. The old text stays in its history. An approved plan and its analysis are locked: move the ticket back to plan to change them. While the Engineer works on the ticket, wait until it finishes.

• CLI: troopy tasks doc. MCP tool: troopy_update_task_doc
• Scopes: tasks:write
• At most 120 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "kind": "plan",
    "version": 3,
    "body": "## In short\nAccept a + in the email check of the signup form.",
    "criteria": [],
    "approved": null,
    "locked": false,
    "updatedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "updatedAt": "2026-09-27T09:10:00.000Z"
  }
}

Create a task

POST /api/v1/tasks

Adds a task. Leave assignee out and it goes to the one teammate of its area, when the area has exactly one, or else to the Chief of Staff, who passes it to the right teammate; set it to null to leave it in the backlog. A new task for a teammate is queued (todo) and the teammate starts it. A new task for a person starts in the backlog. Send status to choose: a task that starts in progress, in review, done or canceled moves there as a move on the board does, so a teammate's task in progress waits at the top of To do. Give parent to make it a sub-task (one level only), and waitsOn to have it wait until sibling sub-tasks are done (research, then write).

• CLI: troopy tasks create. MCP tool: troopy_create_task
• Scopes: tasks:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000030",
    "key": "VIR-12",
    "number": 12,
    "title": "Write the October newsletter",
    "status": "todo",
    "priority": "high",
    "assignee": {
      "type": "agent",
      "id": "writer",
      "name": "Mira"
    },
    "project": {
      "id": "6650c0ffee00000000000031",
      "name": "Autumn launch"
    },
    "milestone": {
      "id": "6650c0ffee00000000000062",
      "name": "Launch day"
    },
    "area": "marketing",
    "parent": null,
    "labels": [
      "newsletter"
    ],
    "dueAt": "2026-10-01",
    "sortOrder": 2048,
    "subOrder": 0,
    "waitsOn": [],
    "blocked": false,
    "progress": {
      "done": 1,
      "total": 2
    },
    "comments": 3,
    "waiting": 0,
    "working": null,
    "error": null,
    "pr": null,
    "flow": null,
    "requestedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-09-27T09:00:00.000Z",
    "updatedAt": "2026-09-27T09:05:00.000Z",
    "closedAt": null,
    "version": 1
  }
}

Change a task

PATCH /api/v1/tasks/{key}

Changes any of a task's fields; send only those to change. A new assignee never changes the status: a teammate starts on a task of the backlog only when its status becomes todo. Moving it out of needs_you withdraws what its teammates asked. A teammate's task set to in_progress while nothing works on it goes to the top of todo instead, and its teammate starts it at once if it is free. Canceling it cancels its open sub-tasks; done with closeSubtasks marks them done too. `before` puts it just above that task in its column (null: at the bottom); `beforeSibling` does the same for a sub-task among its parent's sub-tasks. Send the version you read to refuse the change if someone edited it since (409 stale_version).

• CLI: troopy tasks update. MCP tool: troopy_update_task
• Scopes: tasks:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000030",
    "key": "VIR-12",
    "number": 12,
    "title": "Write the October newsletter",
    "status": "in_review",
    "priority": "high",
    "assignee": {
      "type": "agent",
      "id": "writer",
      "name": "Mira"
    },
    "project": {
      "id": "6650c0ffee00000000000031",
      "name": "Autumn launch"
    },
    "milestone": {
      "id": "6650c0ffee00000000000062",
      "name": "Launch day"
    },
    "area": "marketing",
    "parent": null,
    "labels": [
      "newsletter"
    ],
    "dueAt": "2026-10-01",
    "sortOrder": 2048,
    "subOrder": 0,
    "waitsOn": [],
    "blocked": false,
    "progress": {
      "done": 1,
      "total": 2
    },
    "comments": 3,
    "waiting": 0,
    "working": null,
    "error": null,
    "pr": null,
    "flow": null,
    "requestedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-09-27T09:00:00.000Z",
    "updatedAt": "2026-09-27T09:05:00.000Z",
    "closedAt": null,
    "version": 4
  }
}

Release an engineering ticket

POST /api/v1/tasks/{key}/release

Merges the ticket's pull request at the commit that passed every gate (flow.tested), with the workspace's merge method, and marks the ticket done. It works only on a ticket that is ready to release, and only for people who can release (Settings > Engineering). In a workspace that releases by a merge on GitHub, it refuses. First it reads the gates again: a newer commit sends the ticket back to Test, and failed checks or a reviewer's changes send it back to Build. GitHub's rules for the repo still apply: a required review or check refuses the merge, and the reason comes back. Teammates never release.

• CLI: troopy tasks release
• Scopes: tasks:write code:write
• At most 20 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000030",
    "key": "VIR-12",
    "number": 12,
    "title": "Signup refuses emails with a +",
    "status": "done",
    "priority": "high",
    "assignee": {
      "type": "agent",
      "id": "writer",
      "name": "Mira"
    },
    "project": {
      "id": "6650c0ffee00000000000031",
      "name": "Autumn launch"
    },
    "milestone": {
      "id": "6650c0ffee00000000000062",
      "name": "Launch day"
    },
    "area": "engineering",
    "parent": null,
    "labels": [
      "newsletter"
    ],
    "dueAt": "2026-10-01",
    "sortOrder": 2048,
    "subOrder": 0,
    "waitsOn": [],
    "blocked": false,
    "progress": {
      "done": 1,
      "total": 2
    },
    "comments": 3,
    "waiting": 0,
    "working": null,
    "error": null,
    "pr": {
      "number": 34,
      "url": "https://github.com/acme/app/pull/34",
      "state": "merged"
    },
    "flow": {
      "stage": "release",
      "kind": "bug",
      "size": "small",
      "repo": "acme/app",
      "engineer": "engineer",
      "qa": null,
      "enteredAt": "2026-10-06T11:40:00.000Z",
      "tries": {
        "used": 0,
        "max": 3
      },
      "stuck": null,
      "retry": null,
      "approve": false,
      "tested": {
        "sha": "3f2a9c1e0b7d4a6c8e1f2a3b4c5d6e7f8a9b0c1d",
        "at": "2026-10-06T11:55:00.000Z",
        "verified": true
      },
      "refused": null,
      "checks": "pass",
      "tests": "none"
    },
    "requestedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-09-27T09:00:00.000Z",
    "updatedAt": "2026-09-27T09:05:00.000Z",
    "closedAt": "2026-10-06T12:00:00.000Z",
    "version": 3
  }
}

Claim a task

POST /api/v1/tasks/{key}/claim

Takes a task in backlog or todo that nobody else has, and moves it to in_progress. Answers 409 claimed when someone else has it, so two callers can never both take one.

• CLI: troopy tasks claim. MCP tool: troopy_claim_task
• Scopes: tasks:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000030",
    "key": "VIR-12",
    "number": 12,
    "title": "Write the October newsletter",
    "status": "in_progress",
    "priority": "high",
    "assignee": {
      "type": "agent",
      "id": "writer",
      "name": "Mira"
    },
    "project": {
      "id": "6650c0ffee00000000000031",
      "name": "Autumn launch"
    },
    "milestone": {
      "id": "6650c0ffee00000000000062",
      "name": "Launch day"
    },
    "area": "marketing",
    "parent": null,
    "labels": [
      "newsletter"
    ],
    "dueAt": "2026-10-01",
    "sortOrder": 2048,
    "subOrder": 0,
    "waitsOn": [],
    "blocked": false,
    "progress": {
      "done": 1,
      "total": 2
    },
    "comments": 3,
    "waiting": 0,
    "working": null,
    "error": null,
    "pr": null,
    "flow": null,
    "requestedBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdBy": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "createdAt": "2026-09-27T09:00:00.000Z",
    "updatedAt": "2026-09-27T09:05:00.000Z",
    "closedAt": null,
    "version": 3
  }
}

Comment on a task

POST /api/v1/tasks/{key}/comments

Adds a comment to a task's activity, in markdown. A person's comment brings the task's teammate back to it, and teammates it @mentions (like @writer) reply on the task.

• CLI: troopy tasks comment. MCP tool: troopy_comment_on_task
• Scopes: tasks:write
• At most 60 calls per 60 seconds per key. Takes an Idempotency-Key header

{
  "data": {
    "id": "6650c0ffee00000000000032",
    "kind": "comment",
    "by": {
      "type": "person",
      "id": "6650c0ffee0000000000000a",
      "name": "Ada Lovelace"
    },
    "text": "Lead with the new loyalty card, please.",
    "change": null,
    "runId": null,
    "at": "2026-09-27T09:02:00.000Z",
    "started": [
      "writer"
    ]
  }
}

How much teammates needed people

GET /api/v1/needed-you

For each teammate, the last 7 days and the 7 days before them: the questions that it asked, its calls that a person turned down, and its work that went back from review. Beside them, the tasks that it finished. Calls that always wait for a person, such as a send, stay out. The lessons of teammates are there to make these numbers fall.

• CLI: troopy agents needed. MCP tool: troopy_needed_you
• Scopes: agents:read
• At most 60 calls per 60 seconds per key

{
  "data": [
    {
      "agent": "writer",
      "week": {
        "questions": 1,
        "turnedDown": 0,
        "sentBack": 1,
        "finished": 6
      },
      "before": {
        "questions": 4,
        "turnedDown": 1,
        "sentBack": 2,
        "finished": 5
      }
    }
  ]
}

Write down what a task taught

POST /api/v1/tasks/{key}/lessons

Asks the teammate of a task to write down what the task taught it, so that it needs a person less next time. The teammate reads where a person stepped in: answers to its questions, calls that a person turned down, comments, and work that a person sent back. It writes 2 lessons at most: a skill of the workspace, or one line for its own notes. Each lesson waits as an approval with `lesson` set. Answers 202 with the run; poll statusUrl. Troopy also does this by itself after a task is done, unless learnFromWork is off.

• CLI: troopy tasks learn. MCP tool: troopy_learn_from_task
• Scopes: tasks:write agents:write
• At most 10 calls per 60 seconds per key. Takes an Idempotency-Key header