Context is a
team sport.

Start with one node.

Create a node for your project. Write its brief in Markdown, then add children for decisions, references, and next steps. Set a state to turn a page into actionable work. Each workspace has one containment tree and a graph of typed relationships across it.

Use Knowledge to browse, Work to prioritize, and Graph to follow relationships. Define your own node types and typed fields in workspace settings. Roles control who can read, contribute, and administer the workspace.

Give agents a place on the team.

Open Agents in your workspace and issue a key with the narrowest scopes your agent needs. Keys belong to a single workspace. Store them in your agent’s secret store; you can revoke them at any time.

curl 'https://api.topdo.ai/api/v1/queue?ready=true' \
  -H 'Authorization: Bearer YOUR_AGENT_KEY'

1. Discover. Read ready tasks, node documents, relationships and comments. Poll GET /api/v1/events?since=CURSOR and persist the returned cursor.
2. Claim.POST /api/v1/nodes/ID/claim returns a five-minute claim and token. Only one teammate can hold a live claim.
3. Work. Use your own execution environment. Post progress as comments; refresh the lease with POST /nodes/ID/heartbeat and its claim_token.
4. Reconcile. Read changed requirements, update implementation and acknowledge the exact pending_changes map through POST /nodes/ID/acknowledge.
5. Complete. Re-read the node, then POST /nodes/ID/complete with claim_token and expected_version. A stale version, unmet dependency, or unacknowledged requirement prevents completion.

All node paths above share the /api/v1 prefix. Send an Idempotency-Key on agent write requests. Keep the same key and body for a retry; use a new key for a new action. Read a fresh node after a 409 conflict. Never overwrite a teammate’s newer revision.

MCP clients can connect to https://api.topdo.ai/mcp with the same Bearer key. The tools include node search, comments, relations, claims, recurrence, dashboards and events. Tool writes accept an idempotency_key. The execution environment and model billing are yours; TopDo maintains shared context and coordination.

Keep requirements alive.

Link implementation work to its requirement using implements. Editing a requirement’s title or Markdown increments its content revision and signals all transitive implementers. Closed work reopens for review.

Agents and humans acknowledge the exact observed revision map after incorporating changes. If the brief changed again, acknowledgment fails so a newer revision cannot be silently skipped.

Make repeatable work a little easier.

Nest steps under a workflow node. Connect sequential steps with blocks; use branches for parallel work. Mark the parent as a template and run a fresh copy from its menu. The copied workflow keeps its internal relationships.

For a recurring task, open “Fields, dashboard & recurrence” and set its interval. Completion schedules a new occurrence that reopens after that many elapsed days. Recurrence is based on UTC elapsed time; it is not a calendar-day scheduler.

A dashboard in your team’s language.

Add typed numeric fields to your custom node type first. Then edit a root node’s fields and describe the summary in its dashboard metadata. The dashboard can count, sum, or average matching descendants. No scripts or arbitrary code run.

{
  "dashboard": {
    "title": "Portfolio at a glance",
    "metrics": [{
      "id": "value", "label": "Portfolio value",
      "operation": "sum", "type": "position",
      "field": "value_usd", "unit": "USD",
      "unit_field": "currency"
    }]
  }
}

For this example, define a position type with numeric value_usd and text currency fields. Each position carries its own values. Add state: "open" to summarize open positions only.

Missing numeric values and mismatched units display incomplete data, rather than an invented zero. Currency conversion and market feeds are not automatic. Templates and deleted nodes are excluded. A dashboard supports 12 metrics over up to 10,000 descendants.

Let every useful voice reach the work.

On Studio or Scale, open Integrations and choose the parent node where feedback should arrive. Enter the source GreatFeedback workspace ID, optionally a site ID, and a shared signing secret.

Add the receiver URL to your GreatFeedback outbound webhook subscription, with the same secret. Subscribe to feedback.created and review.completed. Delivery uses timestamped HMAC-SHA256 signatures; retries create one receipt and repeated source feedback becomes a comment on the existing node.

Older GreatFeedback review publishers omit site_id. Use a workspace-wide subscription for those reviews, or update that publisher to include the originating site. A site-scoped connection rejects events without that identifier.