BoardMark

Say you have read a handoff (members). An open handoff becomes acknowledged; the writer is told.

When you have read a handoff addressed to you (list_docs for_me: true, or get_project docs.open_handoffs_for_me > 0), call this with the version from get_doc: an open handoff becomes acknowledged and its writer is told. Do this only after you have actually read it. It does not close the handoff (update_doc status: closed does).

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Add a comment. Attach files first via request_upload → PUT → attach_file.

Body: markdown. Optional colour (D137, use sparingly; markdown stays the main format): <mark>text</mark> highlights (yellow; or <mark data-color="green">), <span data-color="red">text</span> colours text; colours yellow, green, red, blue, purple (e.g. green = passed / expected, red = bug / actual, purple = question); any other HTML is shown as plain text; keep the open and close tag in the same paragraph. A new comment needs no version. To attach files, upload first (request_upload → PUT → attach_file) and pass the returned paths in attachments. To SHOW an image (screenshot) inline, also write ![file name](path) in the body where it belongs — BoardMark renders it as a picture and drops its chip; never paste base64 / data: URLs (they are not shown). To REPLY to a comment, pass its seq (from list_comments) as reply_to; omit it (or null) for a new top-level comment. Replying to a reply is fine: the server files it under that thread's top-level comment (returned frontmatter.reply_to) while frontmatter.in_reply_to keeps the comment you answered. A seq that does not exist on this issue → 400 validation_failed (field reply_to). The author of the comment you answer is notified by email. To mention someone (they get an email), write [@Their Name](mention:usr_…) with their user id and name from list_people (the reporter: the issue's reporter); only people who can open the project are notified. Commenting makes you (the token's user) a watcher of the issue.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Assign or unassign (assignee null).

assignee is a user id (usr_…) or null to unassign.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Confirm an upload and get its attachment path.

Step 3 of 3: after the PUT succeeded. Returns the attachment path to put in add_comment attachments or in an issue body. Show an image inline with ![file name](path) in the comment or issue body (never base64); link other files with [file name](path).

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Close one active sprint (project_admin, or members with sprint_control: members — D141); other active sprints are unaffected (D62).

Requires project_admin, or a member when the project's sprint_control is members (agent tokens may close per that role). Closes ONLY the sprint in sprint_id (it must be active); other active sprints and their issues are untouched. Its issues not in a done status move per move_open_issues_to: backlog (default), new_sprint (a new planned sprint right after this one), or an existing PLANNED sprint id — an active sprint is refused (400), so to hand work to another running sprint, close into the backlog and then move_to_sprint those issues.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Close a case of your company (any member).

Status → closed, system message " closed the case", audit support_case_closed. It can be reopened for 30 days. Closing a closed case changes nothing (200).

Only when the user says the problem is solved or no longer needed. Any member can close a case of the company; it can be reopened for 30 days.

Support cases = asking the BoardMark team for help. Use them when the user wants help from the BoardMark team or reports a problem with BoardMark itself (a bug, signing in, billing, a feature request) — never for the user's own project work (that is issues: create_issue, search_issues …). Every member of the token's company sees and can answer every case of the company. The BoardMark team's replies arrive in the case thread (get_support_case), and followers also get them by email. Text only: files are attached in the web app (Help → Contact support). Your writes show as "via AI agent".

Create a doc (members; viewers are read-only). Only for brief, notes and handoffs — the company brief is edited by company admins in the web app.

Create a project doc of kind brief, notes or handoffs (not company_brief — company admins edit that in the web app). Doc kinds: brief = why the project exists — its goals and the business and technical structure; notes = working notes — progress, status, rules and gotchas people and agents keep for the next person; handoffs = a hand-over of work to a team or to the whole project (open → acknowledged → closed); company_brief = the company's rules and how it uses BoardMark (read-only here). body is markdown; one doc is at most 1 MB (413 doc_too_large — split it into several docs). slug (brief, notes) defaults to one derived from the title; 409 doc_exists means that slug is taken — get_doc it and update it instead. Handoffs are numbered H-{n} by the server; to = team ids it is for (copy them from the to of an existing handoff — there is no tool to list teams) — omit it or pass [] to address the whole project; issues = related issue keys. Say in message what you wrote (shown in the doc history). Viewers are read-only (403). Optional colour (D137, use sparingly; markdown stays the main format): <mark>text</mark> highlights (yellow; or <mark data-color="green">), <span data-color="red">text</span> colours text; colours yellow, green, red, blue, purple (e.g. green = passed / expected, red = bug / actual, purple = question); any other HTML is shown as plain text; keep the open and close tag in the same paragraph.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Create an issue (key is assigned by the server).

The key (e.g. KJ-102) is assigned by the server. priority is highest, high, medium, low or lowest (default medium) — set it when the user or the issue makes it clear. status defaults to the first status of the project (Backlog on kanban and pipeline boards). sprint has no default (scrum only — kanban and pipeline issues have none): omit it (or null) for the backlog, or pass a sprint id. Several sprints can be active at once when the project has parallel sprints on — if the user says "the current sprint" and list_sprints (state=active) shows more than one, ask which. Custom fields (spec D129): pass values in fields keyed by the field id from get_project fields — text / select / customer / url / person = string (select: one of the field's options; person: a user id from list_people), number / money = number (money is kept with 2 decimals in template_settings.currency), date = YYYY-MM-DD. Only fields whose types include the issue's type are accepted and required ones must be present (else 400 invalid_field_value, details.expected = required); an id the project does not define → 400 unknown_field; a formula field is never written (400 formula_readonly — read it in computed). Sales & Billing (D130): a deal is a task (customer, amount, quote_no, payment_terms, sent_at, signed_at, valid_until, owner); an installment is a subtask with parent = the deal key and fields amount, bill_on, due_on (invoiced_at, invoice_no, paid_at, paid_amount come later) — its state Not yet → Invoiced → Paid is derived from invoiced_at / paid_at, not from status, so leave status out. Service desk: a request is a task — set fields.requester to the person you take it for (ask who when unclear); sla_due defaults from urgency and the project's sla_days. Budget planning: a budget line is a task with planned (and actual); remaining is a formula. Roadmap & Goals (D131): a goal is a task with start and end (required, YYYY-MM-DD), quarter, owner, reach / impact / confidence / effort; score, progress and linked are computed (formula / rollup → 400 formula_readonly if sent). A key result is a subtask of the goal. links may point at issues of other projects of the company (you must open both — 403 link_target_forbidden) and, with type delivers, at a release KEY/R-n. Body: Optional colour (D137, use sparingly; markdown stays the main format): <mark>text</mark> highlights (yellow; or <mark data-color="green">), <span data-color="red">text</span> colours text; colours yellow, green, red, blue, purple (e.g. green = passed / expected, red = bug / actual, purple = question); any other HTML is shown as plain text; keep the open and close tag in the same paragraph.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Create a sprint (project_admin; also members when the project's sprint_control is members, D141).

Requires project_admin, or any member (not a viewer) when the project's sprint_control is members (see get_project); otherwise forbidden.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Delete an attached file for good (spec D133): the uploader, or a company admin for any file.

Removes the stored object and the attachment row at once — no trash, no restore (the web asks to confirm). Who: the person who uploaded it (uploaded_by) unless they are a viewer of the project; a company admin of the attachment's company for any file of an issue they can read (even as a viewer). An AI agent (token) only for files that same token uploaded (agent_token_id), never with admin power, and not when its user is a viewer. Allowed while the company is read-only or suspended (frees storage). Everyone else → 403 forbidden. Unknown id, a pending upload, or a project the caller cannot read → 404 not_found. Links to the file in the issue body or comments are not edited: they render as "file deleted". Publishes files.object.deleted and writes the audit event files.attachment_deleted (category content_delete, target {type: attachment, id, label: filename}).

Deletes an attached file for good (no undo); get the attachment_id from list_attachments. An agent may delete only files this same token uploaded (agent_token_id), else 403 forbidden. Ask the user before deleting.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Delete a comment (requires version) — leaves a tombstone.

The author or a project_admin may delete; an imported comment whose Jira author was not matched only a project_admin. The file stays with an empty body and deleted: true, so its seq and replies remain; the old text stays in history. Returns the tombstone.

Only when the user asked. The author or a project_admin may delete (403 not_author otherwise). Pass seq and version from list_comments. Leaves a tombstone: the body is emptied and deleted: true is set, so the seq, replies and links stay; the old text stays in history. 409 comment_deleted = already deleted.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Delete a doc (members). It stays in the history and can be brought back with restore_doc_version.

Pass the version from get_doc. Only delete when the user asked for it. The doc stays in its history and restore_doc_version brings it back. Never delete a doc to "fix" a bad edit — use get_doc_history + restore_doc_version instead.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Delete an issue (requires version) — its subtasks are deleted with it (D130 (6)).

Deleting cannot be undone from MCP. Pass the version from get_issue. Only delete when the user asked for it. Deleting an issue deletes its subtasks with it (a Sales & Billing deal takes its installments) — say so before deleting a parent.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Unified diff of one path between two commits (to defaults to current).

May answer not_implemented until board-core keeps old object versions — then tell the user it is not available yet.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Follow a case: get its emails and bell items (idempotent).

The token's user gets the case's emails and bell items when the BoardMark team answers. Only when the user asks.

Support cases = asking the BoardMark team for help. Use them when the user wants help from the BoardMark team or reports a problem with BoardMark itself (a bug, signing in, billing, a feature request) — never for the user's own project work (that is issues: create_issue, search_issues …). Every member of the token's company sees and can answer every case of the company. The BoardMark team's replies arrive in the case thread (get_support_case), and followers also get them by email. Text only: files are attached in the web app (Help → Contact support). Your writes show as "via AI agent".

Daily remaining points for a sprint (scrum only).

Scrum only. One sprint per call (sprint_id); with several active sprints, call it once per sprint. May answer not_implemented while board-core builds the daily snapshot — then tell the user it is not available yet.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Read one doc (any kind, the company brief included) with its current version.

Returns the doc (frontmatter, the markdown body) and its current version — works for every kind, the company brief included. Call this before update_doc, delete_doc, restore_doc_version or acknowledge_handoff and pass the version it returns. at (a commit from get_doc_history) reads an older version.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Every saved version of a doc, newest first: who saved it (person, and the agent token when an AI agent did), when, and the message.

Every saved version, newest first: commit, version (null for a delete), who saved it (actor_user_id, and agent_token_id when an AI agent did), message, created_at, deleted. Read an older version with get_doc at = its commit; bring it back with restore_doc_version.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

A project's context as one markdown text: company and project briefs, working notes, open handoffs, what each status means, the template's fields and the default role rules (D86).

The fastest way to get a project's context: company brief, project brief, working notes and the open handoffs, then what each of the project's statuses means and the default role rules (spec D86), as ONE markdown text. The status table uses each column's own meaning when the team set one (D102) and shows its WIP limit. After it comes the project's template (scrum, kanban, pipeline, sales_billing, service_desk, budget_planning or roadmap_goals) with its custom fields — id, type, options, which issue types each applies to, required — and the flags the template computes (overdue, bill_due, sla_over, off_track …; spec D129/D130/D131): a project whose issues link to other projects also gets a "linked projects: …" line (names + keys) — those are the projects a linked[] target or a delivers release may live in. take the field ids from there for create_issue / update_issue fields and for search_issues fields / sort_field; on Sales & Billing, installments are subtasks of the deal. Useful before working on a project you do not know. docs lists what is included, in order. truncated: true means the text hit its 2 MB cap — read the missing docs with get_doc. It carries no versions: call get_doc before you change a doc.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Get a short-lived presigned GET URL (used by the md renderer for images).

Short-lived presigned GET URL (about 5 minutes) for an attachment; get the attachment_id from list_attachments (or attach_file). Fetch the URL right away; ask again when it has expired.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Commit log of the project, optionally for one path.

Commits newest first. Each commit shows actor_user_id, agent_token_id and agent {kind, client, tool, request_id} (set when an AI agent made the change, D112).

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Get an issue with its current version — call this before update_issue.

Returns the full issue and its current version. Call this before update_issue, transition_issue, assign_issue, move_to_sprint, rank_issue, link_issues, unlink_issues or delete_issue, and pass the version it returns. People in it (reporter, assignee, created_by, updated_by) are user ids — list_people gives their names. Custom fields (D129): frontmatter.fields holds the values keyed by field id (definitions in get_project fields); flags are the template flags computed now (overdue, bill_due, sla_over …, never stored); computed has the formula fields' values; children summarises its subtasks — for a Sales & Billing deal its installments: count, done (paid), amount_total, paid_total, paid_count. Installments themselves are subtasks: search_issues with parent = the deal key lists them with their own fields and flags. Links (spec D131): frontmatter.links holds what you wrote (type, id — an issue key of this or another project of the company, or a release KEY/R-n for delivers); linked[] resolves each one live, same order: kind issue | release, project_key / project_name, readable (false = you cannot open that project or the target is gone — only the key is known, never guess the rest), and for a readable issue title, status, status_name, category, progress (100 when done else 0), for a readable release title, state, progress (% of its issues past the last gate; shipped = 100). computed also carries rollup fields (e.g. a goal's progress and linked) and fn: rice scores; flags may say on_track / at_risk / off_track for a Roadmap & Goals goal.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Get project.md (board type, template, statuses with colour, WIP limit and meaning — D102 —, custom fields and saved filters — D129 —, workflow) and your role.

Returns project.md: board type, sprint_control (scrum: admins default, or members = every member runs sprints), company_access (none default, member or viewer = every enabled seat of the company opens the project with that role unless a direct/team role is set), the statuses and workflow you must use in transition_issue, and your role. board_type: scrum (sprints; parallel_sprints: true means several sprints may run at once, missing/false means one at a time), kanban (continuous flow, no sprints) or pipeline (a delivery pipeline: no sprints; environments lists the delivery environments in order, and each has a testing_<id> "Testing (name)" and a passed_<id> "Passed (name)" status). Always take status ids from here — never guess them. docs is the project's documentation at a glance: count, open_handoffs_for_me (handoffs for you that you have not acknowledged yet) and read_first (the docs the team marked to read first — open each with get_doc using its kind and slug, or call get_docs_context for everything in one text). The company brief and the project docs may describe the team's own workflow and what its statuses mean. Board columns (spec D102): a status may carry meaning (what the team says the column means), color (display only) and source (default, custom = added by the team, environment = a pipeline environment column); wip_limits {status id: max issues} may be set on any board type — a warning, never a block: prefer finishing work in a full column before pulling more in. A status with removing: true is being deleted (its issues are moving to another column): never move or create an issue into it (409 column_removing). Columns are edited in the web app only (Premium) — there is no tool for it. releases: true (any board type, D113/D116) = the project plans releases: read them with list_releases / get_release; my_release_manager says whether your user manages them. Templates and custom fields (spec D129/D130): template is the workflow template the project was created from — scrum / kanban / pipeline (Software delivery, no fields; missing = the board type) or sales_billing (deals are task, installments are subtask with parent = the deal), service_desk (requests are task), budget_planning (budget lines are task). template_settings holds its values (currency — default THB —, awaiting_sign_days, due_soon_days, sla_days, spent_warn_pct). fields lists the project's custom fields: id (the key to use in an issue's fields), name, type (text · number · money · date YYYY-MM-DD · person = user id · select = one of options · url · customer = free text · formula = read-only, its value comes back in each issue's computed), types (issue types it applies to; missing = every type), required, card (shown on the board card), help, source (template | custom). saved_filters are the project's named queries (id, name, scope issues | children, query = search_issues parameters: flag, fields, status, type, assignee …): when the user names one, run search_issues with that query (pass fields as a JSON string). hide_subtasks_on_board: true (Sales & Billing) = installments are rows inside the deal, not cards; default_view = columns | list | timeline. Fields, saved filters and template settings are edited in the web app only (fields beyond the template: Premium) — there is no tool for them. Roadmap & Goals (spec D131, template: roadmap_goals): goals are task (Idea → Planned → In progress → Done, plus Dropped = done but not a success), key results are subtask; fields quarter (Q1–Q4), start + end (required dates), owner, reach / impact / confidence / effort (numbers), score (formula {fn: rice, of: [reach, impact, confidence, effort]} = reach × impact × confidence ÷ effort, 1 decimal), progress and linked (rollup). A field of type rollup is read-only like a formula — its value comes back in each issue's computed — and its rollup says how: from links (filtered by link_types) or children (subtasks), fn progress (mean of the targets' progress: issue in a done-category status = 100 else 0, release = % of its issues past the last gate, shipped = 100) · count (readable targets) · sum / min_date / max_date over field of the targets; targets the reader cannot open are skipped, depth 1. timeline: {start, end, progress} names the date fields (and the progress field) the Timeline layout draws bars from — any template can have it (Fields settings, Premium). saved_filters with value: current on quarter mean the current Bangkok quarter.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

One release and its readiness, feature by feature, worked out from the board by the rules of D113 (never by AI).

Feature = an epic in the release; issues with no epic are grouped as other. Each feature lists the checks it passes and, when it is not Ready, the reasons. For people who do not manage releases (manage: false) the gate items, baseline and scope history are left out — frontmatter.gate is [], baseline null, scope_log [] and gate / scope are null — only gate_summary is given, and added_after_baseline is false (D113 (4)). Use the numbers as they are; do not guess.

Read this before answering anything about a release ("are we ready?", "what is blocked?", "summarise for the steering meeting"). Use status, features[] (status, checks, reasons), other, counts, gate_summary and scope exactly as returned — never guess, round or invent numbers, and name the issue keys from reasons. manage: false is the member view (no gate items, no scope history) — say so rather than guessing them. You cannot create or edit a release, tick its gate, lock its baseline or mark it shipped: that is for people in the web app — an AI agent never approves a release.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

One case of your company with its whole thread, followers and context.

The case with its whole thread, oldest first. messages[].kind: customer (someone of your company; author.via_agent = written through an AI agent), staff (the BoardMark team), system (status changes such as closed / reopened). Attachments show as file names only — people open them in the web app. following = the token's user gets the case's emails; reopen_until = until when a closed case can be reopened.

Support cases = asking the BoardMark team for help. Use them when the user wants help from the BoardMark team or reports a problem with BoardMark itself (a bug, signing in, billing, a feature request) — never for the user's own project work (that is issues: create_issue, search_issues …). Every member of the token's company sees and can answer every case of the company. The BoardMark team's replies arrive in the case thread (get_support_case), and followers also get them by email. Text only: files are attached in the web app (Help → Contact support). Your writes show as "via AI agent".

How many cases of your company wait for you and how many are open (Help menu badge).

waiting_customer = cases where the BoardMark team answered and waits for your company (read them with get_support_case); open = cases not closed.

Support cases = asking the BoardMark team for help. Use them when the user wants help from the BoardMark team or reports a problem with BoardMark itself (a bug, signing in, billing, a feature request) — never for the user's own project work (that is issues: create_issue, search_issues …). Every member of the token's company sees and can answer every case of the company. The BoardMark team's replies arrive in the case thread (get_support_case), and followers also get them by email. Text only: files are attached in the web app (Help → Contact support). Your writes show as "via AI agent".

Add a link from this issue to another.

Board-core also writes the inverse link on the target issue (blocks ↔ blocked_by, duplicates ↔ duplicated_by, clones ↔ cloned_by, relates ↔ relates) — in the target's own project when it is another one. id (spec D131) is an issue key of THIS project or of another project of the SAME company (KJ-120): you must be able to open both projects, else 403 link_target_forbidden (details.project_key) — do not retry, tell the user who can. Cross-company links do not exist. type: delivers (goals, deals) takes a release instead: id = KEY/R-n (list_releases of that project gives R-n), the release must exist (404 release_not_found) and no inverse is written — the goal or deal is delivered by that release; delivers with an issue key, or any other type with KEY/R-n, is a 400. Afterwards get_issue shows the target live in linked[] (title, status or release state and progress) and rollup fields (computed) follow.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Every file attached to one issue, newest first (anyone who can read the issue; D58).

Includes files referenced from the description and from comments. uploaded_by is the user id; agent uploads also carry agent_token_id.

Use this to see which files an issue has before reading or referring to them. Each item: attachment_id, path (the attachments/KJ-1/… path md bodies link to), filename, content_type, size_bytes, created_at (when it was attached), uploaded_by (user id) and agent_token_id (set when an AI agent uploaded it). To open or read a file, call get_download_url with its attachment_id. Only finished uploads are listed; an empty items means the issue has no files.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

List comments, oldest first.

Oldest first; paginated with cursor/next_cursor. Each comment's frontmatter.seq is its number on the issue. On replies (absent or null on top-level comments): frontmatter.reply_to is the seq of the thread's top-level comment — group comments with the same reply_to under that comment to read a thread (one level deep) — and frontmatter.in_reply_to is the seq of the exact comment answered (the top-level comment or another reply in the thread), i.e. whom the reply is talking to. frontmatter.version is what update_comment / delete_comment need; updated_at / updated_by are set once a comment was edited; deleted: true marks a deleted comment (empty body, replies stay) — skip it when reading the thread.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

List a directory of the project tree.

Lists the md tree (project.md, issues/, sprints/, views/).

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

List the project docs — brief, working notes, handoffs — and the company brief (D76).

Call this (or get_docs_context) BEFORE you start working on a project. Doc kinds: brief = why the project exists — its goals and the business and technical structure; notes = working notes — progress, status, rules and gotchas people and agents keep for the next person; handoffs = a hand-over of work to a team or to the whole project (open → acknowledged → closed); company_brief = the company's rules and how it uses BoardMark (read-only here). Each item: kind, slug (pass both to get_doc), title, version, size_bytes, updated_at, updated_by, updated_by_agent; handoffs also status (open / acknowledged / closed), to (team ids; [] = the whole project) and for_me (true = a handoff for you that you have not acknowledged yet — read it, then call acknowledge_handoff). read_first = the docs to read first. include_deleted: true also lists deleted docs, which restore_doc_version can bring back.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Open issues assigned to you in every project you can access, most recently updated first (D66 "My work"); on Sales & Billing projects also the unpaid installments of deals whose owner field is you (D130 (7)).

"What's on my plate?" — the issues assigned to you (the token's user) in EVERY project you can access, in one call, most recently updated first. Open issues only (not in a done-category status) unless include_done: true. Each item is an issue summary (key, title, type, priority, status, assignee, points, sprint, version, updated_at, …) plus project_key and project_name. Paginated with cursor/next_cursor. Use this instead of calling search_issues with assignee=me project by project; use search_issues when the user means one project or needs other filters. Call get_issue before changing any of these issues. Sales & Billing projects (D130): the installments (type: subtask, parent = the deal) of deals you own (fields.owner) are listed too, so an installment that is due or overdue on your deal shows here — read its flags (bill_due, due_soon, overdue).

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

People who can open the project, with their names (spec D119) — whom to @mention or assign.

Everyone who can open the project: its members (directly or through a team), the company's company admins, who open every project, and — when the project has company-wide access (D142) — every active seat of the company (via: company). Read-only, any member and AI agents. Use it to turn the user ids in an issue (reporter, assignee, created_by, …) into names, and to find the id of a person to @mention ([@Name](mention:usr_…)) or assign. People whose account was deleted or whose seat was deactivated are left out. Sorted by name. Adding or removing members is web only.

One call per project is enough: keep the list for the rest of the task. Use it to name the reporter or assignee of an issue (match user_id), and to @mention someone in add_comment / update_comment as [@Name](mention:usr_…) with the exact user_id and name from here — never invent an id. When several people share a name, ask the user which one. An item with via: "company" is in only through company-wide access (get_project company_access). Someone missing from the list cannot open the project and would not be notified.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

List projects you are a member of.

Paginated: pass next_cursor from the previous page as cursor. Project keys (e.g. KJ) are used by every other tool. Pass stats: true for an overview of every project in ONE call (use it for "how are my projects doing?" instead of searching each project): each item then carries stats — open_issues / done_issues (done = the project's done-category statuses), assigned_to_me (open issues assigned to you), active_sprints (scrum only; every running sprint — there can be several — with id, name, start, end, issues, done_issues, total_points, done_points; empty on kanban/pipeline or when none runs) and updated_at (last change to the project, or null). Leave it off when you only need the keys. Before you start working on one of these projects, read its docs: get_project returns docs.read_first (read those with get_doc) and docs.open_handoffs_for_me, or call get_docs_context for all of it as one text.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Releases of the project with their readiness (D113); planned ones by default.

Releases (D113): what ships to production when, with status (not_ready, at_risk, ready, released) and counts worked out from the board by fixed rules. Releases off for the project → 403 feature_disabled: tell the user a project admin can switch Releases on in the project settings (any board type, paid plans).

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

List sprints.

Each sprint carries its version (needed by update_sprint, start_sprint and close_sprint). state=active may return SEVERAL sprints (parallel sprints, or sprints left running when the switch was turned off) — never assume there is only one.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Support cases of your company, newest activity first (any member).

scope=mine = cases the caller opened. state=open (default) = every status but closed; state=closed = closed cases. Internal notes are never counted or shown.

Check here before opening a case — the same problem may already be open (then reply there instead). Each item: id (case_…, what the other support tools take), number (e.g. CASE-1042, what people say), subject, category, severity, status, opened_by, last_activity_at, last_actor_kind. status: new (no answer from the team yet), waiting_staff (the team's turn), waiting_customer (the team answered and waits for your company), resolved (the team marked it fixed — it closes itself after 7 days without a reply), closed. state=closed lists closed cases; scope=mine only the token's user's. Paginated with cursor/next_cursor.

Support cases = asking the BoardMark team for help. Use them when the user wants help from the BoardMark team or reports a problem with BoardMark itself (a bug, signing in, billing, a feature request) — never for the user's own project work (that is issues: create_issue, search_issues …). Every member of the token's company sees and can answer every case of the company. The BoardMark team's replies arrive in the case thread (get_support_case), and followers also get them by email. Text only: files are attached in the web app (Help → Contact support). Your writes show as "via AI agent".

Who watches the issue (spec D92).

Watchers get the status-change, comment and (if they turned it on) issue-update emails of the issue, besides its assignee and reporter. Only people who can still open the project are listed. Watching is personal state: it is not part of the md file, has no version and is not in the history.

Who gets this issue's status-change and comment emails besides its assignee and reporter; watching says whether you (the token's user) do.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Put an issue (or an epic with its children) into a release, or take it out (release null). Releases on only (D113).

Same as update_issue with release, plus an optional reason: after the release's baseline is locked, the change is written to the scope history of both releases with the reason (D113). An epic's children follow it unless they name another release. The target must exist and not be released yet (400). Members, release managers and project admins; viewers 403.

Put an issue — or an epic with all its children — into a planned release (release: null takes it out). Call get_issue first and pass its version. Add a short reason when the user gave one: after the release's baseline is locked it is kept in the scope history the release managers read.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Move an issue into a sprint, or to the backlog (sprint null). Scrum only.

Scrum projects only. sprint is a sprint id (S-3) or null for the backlog. Any planned or active sprint works (not a closed one); with several active sprints, use the one the user means.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Open a support case for your company (any member, people and AI agents).

Status starts new; the opener follows the case automatically. attachments (web only) come from board-files request_support_upload + confirm_support_attachment; board-tenant stores the list as sent and board-files checks the company on download — an agent sends none. context only when the person ticked the consent box. Limit: 20 cases per user per day, agents included → 429 rate_limited (details.retry_after, Retry-After). Publishes ops.support.case_opened and audit.tenant.support_case_opened.

Only when the user asks for help from the BoardMark team or agrees to report a problem with BoardMark — look at list_support_cases first and reply in an open case about the same thing instead. It notifies the BoardMark team, so confirm the text with the user before sending. category: usage, account (signing in, the account), billing, feature (a feature request), other. severity: normal, degraded (BoardMark partly works), down (not usable at all) — do not overstate it. subject ≤ 200 characters; body ≤ 10,000 characters of plain text: what happened, steps, expected vs actual, project / issue keys, when, the error text. Never put passwords, tokens or other secrets in a case. Returns the case — tell the user its number. At most 20 cases per person per day (429 rate_limited).

Support cases = asking the BoardMark team for help. Use them when the user wants help from the BoardMark team or reports a problem with BoardMark itself (a bug, signing in, billing, a feature request) — never for the user's own project work (that is issues: create_issue, search_issues …). Every member of the token's company sees and can answer every case of the company. The BoardMark team's replies arrive in the case thread (get_support_case), and followers also get them by email. Text only: files are attached in the web app (Help → Contact support). Your writes show as "via AI agent".

Move an issue before or after another one in board/backlog order (manual rank).

Give exactly one of before / after. Only the moved issue is written.

Give EXACTLY ONE of before or after (another issue key in the same project) plus version — never both, never neither. Only the moved issue gets a new version.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Read one md file of the project tree.

Raw md file of the project tree (frontmatter + body + version). at reads an older commit. docs/… paths (project docs) can be read, listed and diffed here too, but prefer get_doc — and docs are written only with the docs tools (create_doc, update_doc, …).

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Reopen a closed case within 30 days of closing (any member).

Status → waiting_staff, system message " reopened the case", audit support_case_reopened, publishes ops.support.customer_replied (excerpt empty). More than 30 days after closed_at → 409 reopen_expired (open a new case). A case that is not closed is returned unchanged (200).

For a closed case whose problem came back, within 30 days of closing (reopen_until); later → 409 reopen_expired — open a new case instead. Then say what happened with reply_support_case.

Support cases = asking the BoardMark team for help. Use them when the user wants help from the BoardMark team or reports a problem with BoardMark itself (a bug, signing in, billing, a feature request) — never for the user's own project work (that is issues: create_issue, search_issues …). Every member of the token's company sees and can answer every case of the company. The BoardMark team's replies arrive in the case thread (get_support_case), and followers also get them by email. Text only: files are attached in the web app (Help → Contact support). Your writes show as "via AI agent".

Reply in a case of your company (any member, people and AI agents).

Status → waiting_staff (stays new while no staff message exists; a resolved case goes back to waiting_staff). The author follows the case automatically. Closed case → 409 case_closed (reopen first). Publishes ops.support.customer_replied and audit.tenant.support_message_added.

Answer the BoardMark team or add details, as plain text (body ≤ 10,000 characters). The case goes back to the team (waiting_staff; a resolved case reopens). A closed case → 409 case_closed: reopen_support_case first. Replying makes the token's user a follower.

Support cases = asking the BoardMark team for help. Use them when the user wants help from the BoardMark team or reports a problem with BoardMark itself (a bug, signing in, billing, a feature request) — never for the user's own project work (that is issues: create_issue, search_issues …). Every member of the token's company sees and can answer every case of the company. The BoardMark team's replies arrive in the case thread (get_support_case), and followers also get them by email. Text only: files are attached in the web app (Help → Contact support). Your writes show as "via AI agent".

Get a presigned PUT URL for one file.

Step 1 of 3: returns a presigned PUT URL and the exact headers to send. Then PUT the bytes to that URL, then call attach_file.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Bring back an older version as a NEW version (history is never rewritten). Also undeletes a deleted doc.

Undo a bad edit: brings back the version at at (a commit from get_doc_history) as a NEW version — history is never rewritten. version = the doc's current version from get_doc, or null when the doc is deleted (this also undeletes it). Brief, notes and handoffs only.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Search issues.

Returns summaries (with each issue's version and sprint). Filters combine with AND; array filters are OR within the filter. assignee=me for your issues. Paginated with cursor/next_cursor. sprint: a sprint id (S-3) for one sprint, backlog for issues in no sprint, or active for issues in ANY active sprint — a project can run several sprints at once, so when the user means one of them, call list_sprints (state=active) and filter by that sprint's id; read each result's sprint to tell them apart. priority: one or more of highest, high, medium, low, lowest (issues without one count as medium); order=priority sorts highest first, then by rank. release (D113): a release id (R-3) for the issues that ship in it — epic children included — or none; each result's in_release is the release it ships in. severity: critical, high, medium, low (bugs). Templates (spec D129/D130): flag filters by the flags board-core computes from the custom fields and today (Asia/Bangkok) — never stored, so never guess them from status. Sales & Billing: overdue = invoiced installment, unpaid, past due_on; due_soon = invoiced, unpaid, due within due_soon_days; bill_due = installment to invoice now (bill_on reached, not invoiced); awaiting_signature = deal in Sent for ≥ awaiting_sign_days; all_paid = deal fully collected but not Closed yet. Service desk: sla_soon (SLA due within a day), sla_over (past SLA; neither in Waiting / done). Budget planning: over_budget (actual > planned), spent_warn (≥ spent_warn_pct % spent). Several flags = OR. Installments are type: subtask with parent = the deal: "which deals are unpaid / ดีลไหนค้างชำระ" → flag: ["overdue"] (each result's parent is the deal; name the customer from the deal's fields.customer); every installment not yet paid → type: ["subtask"] + fields: '[{"id":"paid_at","op":"empty"}]'. fields is a JSON STRING of [{id, op, value}] — ops eq, ne, lt, lte, gt, gte, between (value = array of two), in (array), empty, not_empty (no value); today for date fields, me for person fields — e.g. '[{"id":"due_on","op":"between","value":["2026-10-06","2026-10-12"]},{"id":"paid_at","op":"empty"}]'; all conditions must hold; field ids come from get_project fields (unknown → 400 unknown_field). sort_field (+ sort_dir asc | desc) sorts by a custom field, issues without a value last. Each result carries fields, flags, computed (formula and rollup values) and, for a deal, children (count, done, amount_total, paid_total, paid_count). Roadmap & Goals (spec D131): on_track / at_risk / off_track are computed from a goal's start, end and rollup progress — off_track = past end and progress < 100, at_risk = elapsed % of start→end minus progress % > 25 (before end), on_track = the rest; none for done goals or goals without dates. "เป้าหมาย Q4 ไหนล่าช้า / which Q4 goals are late?" → flag: ["off_track"] + fields: '[{"id":"quarter","op":"eq","value":"Q4"}]' (read computed.progress and fields.owner to answer). linked_to = an issue key of ANY project of the company or a release KEY/R-n: the issues of this project that link to it ("what depends on KJ-120 / what delivers release R-3?"). Results do not resolve their links — get_issue does (linked[]).

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Start a planned sprint (project_admin, or members with sprint_control: members — D141; people only — an AI agent token gets 403: the user presses Start sprint in BoardMark, D79). With the project's parallel_sprints on, several may run at once (D62, D64); off → 409 sprint_active while another sprint runs.

AI agents cannot start sprints (spec D79): this call answers 403 for an agent token — a person starts the sprint in BoardMark (Backlog → Start sprint). Tell the user the sprint is ready and ask them to start it. For people (web / personal use of the API): requires project_admin, or a member when the project's sprint_control is members. Agents never start a sprint — ask the user to press Start sprint. Starts a PLANNED sprint (pass its version from list_sprints). Starting one never stops or closes another. Whether another sprint may be running depends on the project (get_project parallel_sprints): when it is on, several sprints can run in parallel; when it is off (the default), starting fails with 409 sprint_active while another sprint is active (details.active_sprints lists them) — do not retry: tell the user to close the running sprint first (close_sprint) or to ask a project admin to turn on parallel sprints in the web app's project settings (not possible through MCP). Starting a sprint that is already active or closed fails (400 invalid_operation).

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Move an issue to another status (board drag = this call). Scrum + AI agent: only for issues in a sprint a person has started, else 409 sprint_not_started (D79). AI agent: a move out of another role's lane still happens but the result carries warnings (D136) — stop and tell the user.

status must be a status id from get_project (never one marked removing: true — 409 column_removing). For several field changes at once use update_issue instead. On a pipeline board an issue moves Backlog → To Do → Developing → Dev Done → then, for each environment in environments order, Testing (env) testing_<id> → Passed (env) passed_<id> → … → Done. When testing fails in an environment, move it to Test Rejected (test_rejected) and it goes back to development. "Deployed to UAT" / "testing on UAT" means testing_<id of UAT>; "passed UAT" means passed_<id> — look the id up in get_project environments. Scrum boards (spec D79): you may change the status only of issues in a sprint a PERSON has started (list_sprints state active); otherwise 409 sprint_not_started — do not retry, ask the user to start the sprint in BoardMark. Backlog planning (create_issue, update_issue fields other than status, move_to_sprint, comments) is always fine. Move only the part of the flow that belongs to your role (developer: To Do → In Progress/Developing → In Review/Dev Done; QA: → Done/Passed (env) or Test Rejected; BA: up to To Do), unless the project's docs or the user say otherwise. Lanes (spec D136): each status belongs to a role (get_docs_context shows the Lane column). Pass as_role (e.g. Developer, QA) when the user told you your role; otherwise your token's role is used. The move always happens, but when it leaves another role's lane the result carries warnings (role_lane, skip_lane, self_review): stop there, tell the user what you did, and hand off with a comment — undo it (transition back to from) if the user did not want it.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Stop following a case (idempotent).

Removes the caller from the followers. The opener and people who wrote in the case still get its emails (spec D98 (8)).

Stop following. The opener and people who wrote in the case keep getting its emails.

Support cases = asking the BoardMark team for help. Use them when the user wants help from the BoardMark team or reports a problem with BoardMark itself (a bug, signing in, billing, a feature request) — never for the user's own project work (that is issues: create_issue, search_issues …). Every member of the token's company sees and can answer every case of the company. The BoardMark team's replies arrive in the case thread (get_support_case), and followers also get them by email. Text only: files are attached in the web app (Help → Contact support). Your writes show as "via AI agent".

Remove a link.

version is the version of THIS issue (from get_issue). target is the linked issue's key as stored in frontmatter.links — of this or another project of the company; the inverse link in the other project is removed too. A delivers link to a release (KEY/R-n) cannot be removed here (the target must be an issue key): call update_issue with links = the complete list from get_issue minus that entry.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Stop watching the issue (idempotent; spec D92).

The assignee and reporter still get the issue's emails unless they turn a kind off in their notification settings.

Stop watching (idempotent). The assignee and reporter keep getting emails unless they turn them off in BoardMark settings.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Edit your own comment (requires version).

Only the comment's author may edit it (an agent: the owner of its token). Send the full new body and the version you read; stale → 409 version_conflict. Imported comments whose Jira author was not matched cannot be edited. No new notification is sent.

Edit a comment's text: only its author may (for an agent, the user who owns the token) — others get 403 not_author; an imported comment whose Jira author was not matched cannot be edited (403 import_author_locked). Pass the comment's seq and version from list_comments and the COMPLETE new body; attachments (optional) is the complete new list. Edit only when the user asks or to correct your own comment; no new email is sent. 409 comment_deleted = it was deleted — do not retry. Colour and highlighter in the body: see add_comment.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Edit a doc (members). Send the version from get_doc; change any fields in one call. Close a handoff with status: closed.

Call get_doc first and pass its version. body is the COMPLETE new markdown (not a diff or an appended piece): take the current body from get_doc, change it and send all of it. Change any fields (title, body, and for handoffs to, issues, status) in ONE call — one call makes one new version. Keep working notes current: when you learn something the next person (or agent) needs — progress, decisions, rules, gotchas — add it to the notes; this is optional, use your judgement. Handoffs: status: closed closes one (or open reopens it); to say you have read one use acknowledge_handoff instead. One doc is at most 1 MB (413 doc_too_large). Say in message what changed. The company brief is read-only here. Optional colour (D137, use sparingly; markdown stays the main format): <mark>text</mark> highlights (yellow; or <mark data-color="green">), <span data-color="red">text</span> colours text; colours yellow, green, red, blue, purple (e.g. green = passed / expected, red = bug / actual, purple = question); any other HTML is shown as plain text; keep the open and close tag in the same paragraph.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Update any issue fields in one write (requires version).

One call = one new version, whatever the number of fields (PO 2026-09-25). links replaces the whole list; board-core adds/removes the inverse links on the other issues in the same commit. transition_issue, assign_issue, move_to_sprint and link_issues stay available as single-purpose tools and follow the same rules. fields (custom fields, spec D129) is merged key by key: send only the keys you change, null removes one.

Call get_issue first and pass its version. Change ANY number of fields in ONE call (title, body, type, priority, severity, status, assignee, points, sprint, release, parent, labels, links) — one call makes exactly one new version, so do not split an edit into several calls. links replaces the whole list. Images in body: upload + attach_file first, then ![file name](path) (never base64). severity (bugs, D113): critical / high / medium / low — how bad it is, separate from priority. release: a planned release id, or null — children of an epic follow the epic's release unless they name another; use move_to_release when the user gives a reason. fields (custom fields, D129) is merged key by key: send only the keys you change, null deletes a value; same types and errors as create_issue (400 unknown_field / invalid_field_value / formula_readonly; types of the field must include the issue's type). Sales & Billing installments (D130): "invoiced" = set invoiced_at (+ invoice_no); "paid" = set paid_at and paid_amount (= amount when paid in full) — dates YYYY-MM-DD, today's date unless the user says another. Do not move the deal to Closed on your own: the deal's all_paid flag says when everything is collected — tell the user and move it only when asked. Rollup fields (D131: a goal's progress / linked, a deal's delivery_progress) are computed like formulas — never in fields (400 formula_readonly); read them in computed. links entries take an issue key of this or another project of the company (403 link_target_forbidden when you cannot open the target's project) or {type: "delivers", id: "KEY/R-n"} for a release (404 release_not_found when it does not exist). For a Roadmap & Goals goal, moving start / end is a fields change like any other. Body: Optional colour (D137, use sparingly; markdown stays the main format): <mark>text</mark> highlights (yellow; or <mark data-color="green">), <span data-color="red">text</span> colours text; colours yellow, green, red, blue, purple (e.g. green = passed / expected, red = bug / actual, purple = question); any other HTML is shown as plain text; keep the open and close tag in the same paragraph.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Change a sprint's name, dates or goal (project_admin, or members with sprint_control: members — D141; D61). Send the version you read.

Planned and active sprints: name, start, end, goal. Closed sprints: name and goal only (dates are history) — dates on a closed sprint → 409 sprint_closed. end must not be before start (400). Publishes core.sprint.changed.

Rename a sprint, move its dates or change its goal. Requires project_admin, or a member when the project's sprint_control is members. Call list_sprints first and pass the sprint's version; send only the fields to change (name, start, end as YYYY-MM-DD, goal — null clears it) — all of them in ONE call. Planned and active sprints accept every field; a CLOSED sprint keeps its dates (they are history): sending start or end for it fails with 409 sprint_closed — change only name/goal there. end must not be before start (400). Moving an active sprint's dates changes its burndown date range. Do not use write_file on sprints/*.md for this.

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Watch the issue yourself (idempotent; spec D92).

Anyone who can read the issue may watch it. Adding a comment also makes you a watcher.

Watch the issue as the token's user (idempotent). Only when the user asks — watching sends them emails.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.

Create or replace one md file (validated exactly like the typed operations).

version: null creates the file and fails with 409 if it already exists. An existing comment cannot be changed here (403) — use update_comment / delete_comment (D90). project.md (D102): the status keys color, meaning, source and removing are kept from the stored file (values sent are ignored) — they change only through the web column editor. Columns need Premium here too (D102, D100): on a company that is not on Premium, a project.md write whose statuses differ from the stored ones in any way (a status added, removed, renamed, reordered, or its category changed — colour / meaning are ignored as above) → 403 plan_required (details.plan premium; board-tenant unreachable → 503 unavailable), with one exception on every plan: adding the default Backlog column to a kanban board (D61, board-web's "Add Backlog column") — {id: backlog, name: Backlog, category: todo} put first while every stored status stays as it was, in the same order (transitions may change with it). On Hold (D81) stays on update_project_settings on every plan. On Premium the write is checked like update_board_columns: at least one done-category column (422 no_done_column), names unique ignoring case and surrounding spaces (422 duplicate_name, details.names), a stored kanban / pipeline Backlog column stays first (422 backlog_column, D105), and a column being emptied by a column job cannot be dropped (409 column_job_running, details.ids); like before, write_file does not move issues of a removed status (use the column editor for that). Other keys of project.md are not affected.

Validated exactly like the typed tools. Prefer the typed tools (update_issue, add_comment, …) — use this for md content they do not cover. version: null creates a new file (409 if it already exists). docs/… paths are refused here: write project docs with create_doc / update_doc / delete_doc / restore_doc_version. Existing comments are edited only with update_comment / delete_comment. project.md: keep statuses as you read them — changing the board columns (add, remove, rename, reorder, category) needs the Premium plan (else 403 plan_required) and is meant for the web column editor; template, fields, saved_filters and timeline are read-only here too (the field editor, the filter popover and the Fields settings in the web app). An issue's fields in its frontmatter is checked exactly like update_issue fields (400 unknown_field / invalid_field_value / formula_readonly — rollup fields included) and its links like link_issues (cross-project keys, delivers → KEY/R-n).

WRITE: version must be the version from your latest read of this file (get_issue for issues, list_comments for comments, list_sprints for sprints, get_doc for project docs, read_file for md files). If the file changed since, the call fails with 409 version_conflict and the error contains the current file (details.current, details.current_version): re-read it, re-apply your change on top of the current content and retry with the new version. Never overwrite someone else's change blindly — if your change and theirs disagree, ask the user which to keep.

You act with exactly the rights of the user who owns this token; a project you cannot see returns not_found.