Context is a team sport.
A practical guide to connecting your knowledge, your people, and your agents.
Start with one page.
Create a page for your project and write its brief in Markdown. Add pages and tasks under it for decisions, references and next steps, and turn a page into a task when it needs doing.
Use the left bar to browse, Items to see pending work in order, and Graph to follow links. Everyone in a workspace sees all of it, templates too; roles control who contributes and who administers it.
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'- Discover. Read ready tasks, node documents, relationships and comments. Poll
GET /api/v1/events?since=CURSORand persist the cursor it returns each time. Each event names who made it: actor_name, the label the app shows, and actor, the same as fields (kind, id, label, channel and, for an agent, its name with acts_for or issued_by); an item carries created_by_actor and updated_by_actor. - Claim.
POST /api/v1/nodes/ID/claimreturns a five-minute claim and token. Only one teammate, person or agent, can hold a live claim on a node at any one time. - Work. Use your own execution environment. Post progress as comments; refresh the lease with
POST /nodes/ID/heartbeatand its claim_token before the claim expires. - Reconcile. Read what changed in the requirements, update the implementation and acknowledge the exact
pending_changesmap throughPOST /nodes/ID/acknowledge. - Complete. Re-read the node, then
POST /nodes/ID/completewith claim_token and expected_version. A stale version, unmet dependency or unacknowledged requirement blocks it.
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, and never overwrite a teammate’s newer revision with your older one.
Connect any MCP client to https://api.topdo.ai/mcp with your REST API agent key as the Bearer token. Your agent acts for the member who issued the key, within that member's role and the key's scopes, and each change it makes shows as that member's agent, as “Dana's agent”; a shared workspace key shows as the agent of the member who issued it.
Everything else comes from the server itself. The server explains what TopDo is and where to start, and each tool says when to use it, what it returns and which values from your workspace it accepts. Your agent can create, edit, move and delete items and pages, link them, comment with mentions, search item titles and bodies by meaning or by words, and read the full tree, the graph and Activity. It attaches files inline up to 1 MB or by signed link up to 50 MB, each one scanned for malware before anyone can download it. It manages members within its own role: it lists each person as active, invited or disabled, invites, revokes an invitation, and disables, enables or removes someone, under the same guards as the app, each step audited for the team. For admins it also manages item types, statuses, link types, the workspace name and the default assignee. Agent keys, billing, export, workspace deletion, ownership transfer, sign-in, passwords and reading back integration secrets are not available through MCP. Each item type has its own statuses, in its own order: get_workspace lists them under each type, and a status of another type is refused with 422 invalid_status and a hint to read them again.
Your people can talk to your agent, too. Anyone on the team can @-mention it in a comment, by the name the app shows, such as “Omar's agent”. Your agent reads what is addressed to it with list_mentions (unread: true), or GET /api/v1/mentions?unread=1, each with the item, the comment's text and who wrote it, and marks them done with mark_mentions_read or POST /api/v1/mentions/read. A comment by a workspace owner or admin that mentions it carries instruction: true. It is an instruction from the person your agent works for: it overrides any question your agent was waiting on, and your agent acts on it rather than asking again. Have your agent check its mentions when it starts, between its steps, and before it asks any person a new question.
Everyone can react to items, pages, comments and files with an emoji, one of each per person, and see who reacted. Your agent does the same with add_reaction, remove_reaction and list_reactions, or POST /api/v1/reactions, DELETE /api/v1/reactions and GET /api/v1/nodes/ID/reactions.
To filter by status, give a key, which matches every type that has it, or type:key, such as task:blocked, for that type's status alone. list_items, list_queue and get_activity take both, as do the status filters of GET /items, /nodes, /queue and /activity. Lists name each item without its description; read one item with get_item or GET /items/ID for its body.
An admin-scoped key that acts for an owner or admin can bring work over from Jira, Linear or Confluence. It lists what the account can read with list_import_projects, shows what each would bring with preview_import, starts the import with start_import, and follows its progress and the issues or pages that stayed behind with list_imports. Each imported item names its source key and link in metadata.import, so your agent always knows which issue or page it came from. Over REST the same steps are POST /api/v1/imports/jira/projects, POST /api/v1/imports/jira/preview, POST /api/v1/imports/jira and GET /api/v1/imports, with linear or confluence in place of jira. The token or key your agent sends is write-only: stored encrypted, never returned, and shown only as set, the same way Settings shows it.
Creates take an idempotency_key: a retry with the same key and arguments runs once, never twice. A refused call says what went wrong and how to fix it, including when to retry. The execution environment and model billing are yours; TopDo keeps the shared context and coordination.
What your agent writes, your people read, so it learns how they read best. A bullet fits one line of the item view, about 65 characters; one that must wrap fills its second line at least 70%, about 111 to 130 characters in all; and the bullets of one list stay close in length. Every create and update answers with style_notes on any bullet that misses, so your agent can tighten it next time. The notes are advice only: the item is always saved exactly as sent, and no write is ever refused or held back for them.
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.
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.
Know what was decided, and why.
Write a decision’s options as lines starting A., B. and so on. Pick one, or write your own answer, with a line on why; the decision then opens with the answer, who decided and when. Your agents read the same record with get_item, decide with decide_item and link the decision that replaces one with supersede_item, so their work always keeps to what you settled.
Let an independent reader check the work.
On Scale, AI models read what your team saves and point out what people miss: a task that contradicts its spec, two pages that disagree, a duplicate, a broken reference, an ambiguity. Findings show those; Suggestions show risks nobody wrote down, spend you could cut and steps that add the most.
A workspace owner turns each one on once, from its page or from Settings, under Intelligence. From then on AI model providers read the text of your items and their recent comments, with who wrote them; under their API terms they do not train on it. The owner can turn either one off at any time.
A few minutes after a task, page, decision or comment changes, the models read it with its links, its parent, nearby items and similar text, and check them against each other. About once a day they look again across your recent changes and every open finding in your workspace.
Each finding cites the items involved, explains why, and shows how to settle it, with one way recommended. It resolves itself once the items no longer support it, and anyone can reopen it. Rate each one helpful or not, with a comment: your latest ratings shape what your workspace is shown next.
An agent key with the read scope lists them through GET /api/v1/findings; with the write scope it rates them through POST /api/v1/findings/ID/feedback. The MCP tools list_findings, get_finding, findings_summary, rate_finding and set_finding_status do the same. Requester and partner keys have no access to them and receive a 403 response.
Two items saying the same thing merge into one, on every plan, and a person in your team always confirms it. A duplicate finding offers Merge, keeping the oldest item unless you pick another; any item's More actions offers Merge into…. The merged item reads Merged and links the item it went into; TopDo.ai comments on both items, linking the other and naming who confirmed. Nothing moves: everything the merged item holds stays on it, one click away. Unmerge, on the merged item, brings back its earlier status and removes the link between the two items.
Your agent never merges. When create_item answers likely_duplicates that are the same work, or it finds two items that are, it proposes the merge with propose_merge (POST /api/v1/nodes/ID/propose-merge), and you confirm or decline it on the item. get_merge (GET /api/v1/nodes/ID/merge) reads where an item stands. A key calling POST /api/v1/nodes/ID/merge or POST /api/v1/nodes/ID/unmerge receives 403 human_required: only a person merges or unmerges.
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, internal relationships included, from its menu.
For a recurring task, open “Fields, dashboard & recurrence” and set its interval. Completing it schedules an occurrence that reopens after that many days, counted in UTC elapsed time, not calendar days.
A dashboard in your team’s language.
First give each task a numeric metadata field, such as value_usd, then describe the summary in a root item’s dashboard metadata. It can count, sum or average matching descendants; no scripts run.
{
"dashboard": {
"title": "Portfolio at a glance",
"metrics": [{
"id": "value", "label": "Portfolio value",
"operation": "sum", "type": "task",
"field": "value_usd", "unit": "USD",
"unit_field": "currency"
}]
}
} In this example each position is a task with a numeric value_usd and text currency field. Each position carries its own values. Add state: "open" to summarize open items only. The state is the category of an item's status: open, blocked or closed, whatever each item type names its statuses.
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 items are always excluded. Each dashboard supports up to 12 metrics over up to 10,000 descendants.
Hand your agent the settings, too.
Your agent can read each setting in this table, and change it where the app lets you, with the same checks: a settings change needs a key acting for an owner or admin, and Activity shows every change as your agent’s. Each row names the REST path under /api/v1 and the MCP tool that does the same job, so you use whichever your agent speaks.
| In the app | REST | MCP |
|---|---|---|
| Labels: counts, rename, merge, recolour, delete | GET /label-usage, PATCH /labels/NAME, DELETE /labels/NAME | list_label_usage, update_label, delete_label |
| Saved views: Items filters and a layout, by name | GET /views, POST /views, PATCH /views/ID, DELETE /views/ID | list_views, create_view, update_view, delete_view |
| Overview: status, top work, risks, pace, groups | GET /overview/report | get_overview |
| Custom fields: add, rename, options, archive, delete | GET /custom-fields, POST /custom-fields, PATCH /custom-fields/KEY, DELETE /custom-fields/KEY | list_custom_fields, create_custom_field, update_custom_field, delete_custom_field |
| Workspace icon and tint | GET /workspace-icons, PATCH /workspaces/ID | list_workspace_icons, update_workspace |
| Item types and their own statuses, with icons and colours | GET /item-types, POST /item-types, PATCH /item-types/KEY, POST /item-statuses, PATCH /item-types/TYPE/statuses/KEY | list_item_types, create_item_type, update_item_type, create_item_status, update_item_status |
| Intake forms | GET /intake-forms, POST /intake-forms, PATCH /intake-forms/ID, DELETE /intake-forms/ID | list_intake_forms, create_intake_form, update_intake_form, delete_intake_form |
| Work for someone invited, before they join | GET /invites, assignee_id iv_... on POST /nodes or PATCH /nodes/ID | list_invites, create_item, update_item |
| Members: revoke, disable, enable, remove | GET /members, GET /invites, DELETE /invites/ID, POST /members/ID/disable, POST /members/ID/enable, DELETE /members/ID?reassign_to=ID | list_members, list_invites, revoke_invite, disable_member, enable_member, remove_member |
| Default assignee for unassigned items | PATCH /workspaces/ID, POST /workspaces/ID/assignee-backfill | update_workspace, assign_unassigned_items |
| Recurrence | PUT /nodes/ID/recurrence | set_item_recurrence |
| Custom fields and the dashboard | metadata on PATCH /nodes/ID, GET /nodes/ID/dashboard | update_item, get_dashboard |
| Activity: figures and 10, 25, 50 or 100 a page | GET /activity | get_activity |
| An item’s history: 10, 25 or 50 a page | GET /activity?node=ID | get_activity with item_id |
| Every workspace change, up to 200 a call | GET /events?since=CURSOR | list_activity |
| Sign-ins, item views and changes by person or item (owners and admins) | GET /access-log | list_access_log |
| Link types, such as Relates to | GET /link-types, POST /link-types, PATCH /link-types/NAME, DELETE /link-types/NAME | list_link_types, create_link_type, update_link_type, delete_link_type |
| An item's links, and the items above it | GET /nodes/ID/links, GET /nodes/ID/ancestors | list_links, get_item_path |
| Findings and Suggestions switches and terms | GET /intelligence, POST /intelligence | get_intelligence, set_intelligence |
| Duplicates: propose a merge, read it | POST /nodes/ID/propose-merge, GET /nodes/ID/merge | propose_merge, get_merge |
| Findings: read, rate, settle | GET /findings/ID, POST /findings/ID/feedback, POST /findings/ID/status | get_finding, rate_finding, set_finding_status |
| Item connections, under Integrations | GET /nodes/ID/connections, PUT /nodes/ID/connections/PROVIDER, PATCH /nodes/ID/connections/PROVIDER, POST /nodes/ID/connections/PROVIDER/test, POST /nodes/ID/connections/PROVIDER/sync, DELETE /nodes/ID/connections/PROVIDER | list_connections, save_connection, update_connection, test_connection, sync_connection, delete_connection |
| GreatFeedback integrations | GET /integrations/greatfeedback, POST /integrations/greatfeedback, DELETE /integrations/greatfeedback/ID | list_feedback_integrations, save_feedback_integration, disable_feedback_integration |
| The terms you accepted at sign-up | GET /me, signed in | get_profile |
| Slack channels: list; link, unlink and open for operators | GET /slack/channels, POST /slack/channels, DELETE /slack/channels/ID, POST /slack/provision | list_slack_channels, link_slack_channel, unlink_slack_channel, provision_slack_channel |
Tokens and signing secrets your agent sends here, by MCP or REST, go in one way: TopDo stores them encrypted and never returns them, and a connection shows its token only as set. Turning on Findings or Suggestions accepts their own terms section, which lets workspace text go to AI model providers: a workspace owner, or a key acting for one, passes that section's version as terms_version in that call.
Your agent sets a colour by its palette key, the same squares you see in Settings: type-1 to type-18, type-deep or type-bone for item types, statuses, labels and the workspace icon tint, where null clears a label's colour or the tint; avatar-1 to avatar-16, avatar-deep or avatar-bone for a member's avatar, where null restores the default.
Custom fields give your items the structure your team works by. Your agent sets values with custom_fields on create_item or update_item, such as {"sprint":"S12","story_points":3,"reviewers":["us_..."]}; a person field holds one or more people. A key it sends replaces only that field, and null clears it. list_items filters by custom_fields, and search_items finds an item by a value, so "PLT-1101" finds the issue you imported from Jira.
Ask for the Overview to see where the work stands, for the whole workspace or one item and everything under it (root_id): how much is done, the first 100 open items in your order, what needs attention and why, how much finished over a period (1 day to 1 year, or your own dates), what reopened, and the totals of number fields. Add group, such as field:sprint, label or assignee, for the same counts per value. Each person chooses where a workspace opens for them, the Overview or Items, as home_view on update_profile; the choice follows them to every device.
To list the items behind a number, give list_items or GET /items the same scope and filter: root, then category, overdue or done, and for a period done_from with done_to, or created_from with created_to, as the Overview's own links do.
Every item with items below it totals them too: get_dashboard counts what is open and done and adds up each number field over the items that hold it, and list_items gives each row its children, how many and how many done.
Save the Items filters you use most as a view, such as a sprint's board, for yourself or shared with the workspace; a board shows the same items in a column per status, and moving a card moves the item.
A calendar places the same items on their due date or on any date field, and a timeline draws each one as a bar from when it was added, or from another date field, to that date.
Lists live in any item's text. Write - [ ] for a checklist line; a line that is only a link, - [ ] [[nd_...]], shows that item's own status, and checking it marks the item done. Put {release_notes} after a link to show that field beside it, and put ![[nd_...]] on its own line to show the whole item in place, its own list included, two levels deep. get_item returns these items as link_items, and expand: true writes the embedded text out for a document.
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 and the same secret to your GreatFeedback outbound webhook subscription, then subscribe to feedback.created and review.completed. Deliveries carry timestamped HMAC-SHA256 signatures; a retry creates one receipt, and repeated feedback becomes a comment.
Older GreatFeedback review publishers omit site_id. Use a workspace-wide subscription for their reviews, or update the publisher to send the site; a site-scoped connection rejects events without it.
Bring your Jira projects with you.
On every plan, open Integrations and choose Import from Jira. Enter your Jira site, your account email and an API token from id.atlassian.com, then pick projects and see how many issues each one holds before anything moves.
Each issue becomes an item under its project’s page, with its type, status, labels, due date, comments, files and creation date. Epics hold their stories, sub-tasks sit under their parents, and links keep their meaning, so your work reads the way it did.
Teammates who share an email with your workspace keep their work and the issues they reported. Choose to invite the people with open work who are not here yet, and their work waits for them; otherwise their names stay on the items. Every item links back to its Jira issue.
Run it again whenever you like: changed issues update in place and nothing arrives twice. Large projects import in the background, files count toward your storage, and the page lists anything that stayed behind, issue by issue.
Move your Linear teams just as easily.
Choose Import from Linear and paste a personal API key from your Linear settings. Each team you pick becomes a page, with a page inside it for every Linear project and its issues under that, so your roadmap keeps its shape.
Workflow states become your task statuses, sub-issues nest under their parents, and blocking, duplicate and related issues stay linked. Labels, due dates, comments, uploaded files and people come over as they do from Jira, and links you attached stay in the body.
Keep your Confluence knowledge in one place.
Choose Import from Confluence and sign in as you do for Jira: your Atlassian site, your account email and an API token. Already imported from Jira on that site? Use that connection and skip the form. Pick the spaces you want and see how many pages each one holds first.
Each space becomes a page, and every page you can read in it arrives as a page inside, nested as it is in Confluence, with its text, comments (inline ones quote the text they mark) and their replies, attached files, author and dates. Blog posts arrive as pages at the space's top. Run it again any time: edited pages update in place and nothing arrives twice.
Keep the conversation and the record together.
In a Slack channel linked to your workspace, mention @TopDo.ai to open any item by its number, id or link, list items by type, status, assignee, label or parent, open or closed, search them, and read an item's comments, history and links. Answers show only to you, from what you can read in TopDo.
Ask it to add a task, page, decision or any other type your workspace uses, to comment, or to change an item's title, text, status, assignee, due date, labels, parent, order or links; to decide or supersede a decision; or to delete an item. Each change shows you exactly what it will write, before and after, and waits for your Confirm click; deleting an item or removing a link asks twice. Say @TopDo.ai help to see every command. It speaks only when you mention it: say @TopDo.ai add this in a message's thread, or right after that message, to add the message to TopDo as a task.
Say @TopDo.ai link once: the link it sends only you opens TopDo, and confirming it lets the bot act for you with your own access. Nothing is written without a click, and changes appear in Activity under your workspace's TopDo.ai Slack agent, with the person who confirmed each one recorded.
For the few items everyone should hear about, turn on Post when done under Slack in the item's details. When it is marked done, @TopDo.ai posts it to each linked channel in your workspace and mentions everyone there. Over REST and MCP, the same switch is the item's slack_on_done field.
