Dokumentacja API

Open a dispatch run, with the SET of cards it owns

OPEN one run of a Motir CLI command and record THE SET it owns: every card, in the run’s own order, including the ones it has already decided to SKIP, each with its reason. ⚠️ THE SET IS SETTLED HERE BECAUSE THIS IS THE ONE MOMENT IT EXISTS — a scope claim has just returned its members, or a batch snapshot has just been frozen. Rebuilt afterwards from per-card events it becomes a list of what the run got round to, and the skipped cards vanish entirely. A single-card `motir next` is the degenerate case: one card in the set. IDEMPOTENT on `idempotencyKey`: a repeat returns the EXISTING run with `created: false` rather than forking history, so a retry after a timeout is safe. It records the run and NOTHING ELSE: it moves no work-item status, writes no pull request and holds no cost. Requires the `work_item:edit` permission.

Treść żądania

The command, its origin, the agent and model, an optional scope, an optional idempotency key, and the ordered SET of cards.

Przykład

curl -X POST 'https://app.motir.co/api/v1/dispatch-runs' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"projectKey":"<projectKey>","command":"next"}'

Odpowiedzi

Schemat odpowiedzi

Get a dispatch run, with the SET of cards it owns

READ one run and its set: every card in the run’s own order with its current disposition, and the stream’s cursor. It is how a CLI that did not open a run — a hosted run the SERVER opened, which the `motir` CLI in its container then adopts (`docs/decisions/hosted-run-runs-the-cli-as-the-app.md` §3) — learns the cards it owns and their order, instead of claiming a second set. A hosted run’s own credential may read its own run and no other. A read: it writes nothing and moves no status. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/dispatch-runs/{id}' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

Close a dispatch run with its stop reason

CLOSE the run: its terminal status, its `stopReason`, and every leg still unsettled — a `queued` card becomes `not_reached` (the run never got to it) and a `running` one becomes `failed` (the run ended while an agent was on it and nothing reported an outcome). Omit `status` and it is DERIVED from the stop reason, which is the mapping every caller would otherwise re-implement differently: `halted` is the only failure, `interrupted` is `cancelled`, and `replanned` is a SUCCESS — an agent that refused a card and submitted a plan exited 0. Guarded by a row lock and a re-read, so a close racing the server’s own abandoned-run reap cannot overwrite an already-terminal answer; the loser is a conflict. It writes NO work-item status — the CLI owns every transition. Requires the `work_item:edit` permission.

Żądanie

Treść żądania

The stop reason, and optionally an explicit terminal status.

Przykład

curl -X POST 'https://app.motir.co/api/v1/dispatch-runs/{id}/close' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"stopReason":"drained"}'

Odpowiedzi

Schemat odpowiedzi

Get the prompt that writes a run’s How to test onto its run target

The CLOSE-OUT prompt for a run launched against a work item (a scoped run): the text a CLI hands ONE agent after the run’s last card lands and BEFORE it marks the run’s pull requests ready, so HOW TO TEST is written once onto the run target by an agent that sees every card the run landed. The target and the landed cards are read from the run’s own record — the caller names only the run. A run with no scope (an unscoped batch, whose every card was its own target) is refused with `NO_RUN_TARGET` rather than answered with a defaulted target. A read: it writes nothing and moves no status. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/dispatch-runs/{id}/close-out-prompt' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

Append a batch of events to a dispatch run

APPEND events to a run’s ordered stream. Each is RUN-scoped, or CARD-scoped by naming a `workItemKey` the run already owns — an event never ADDS a card to a run’s set, because the set is the plan the run published. The server assigns each event its `seq` inside ONE transaction, so a batch’s order survives and the response’s `seq` is the cursor for the next append. Batch them: a chatty agent must not cost one request per line. An event may also carry the leg’s new `disposition` (plus `sessionBranch` / `exitCode`), applied to that card in the SAME transaction — so a viewer sees a card go `implemented` at the moment it happens rather than at close. `body` is the OPT-IN log payload: send it only when the operator asked for it. It is REFUSED above 16 KiB rather than truncated, and it is cleared 30 days after the event. Appending to a run that has already closed is a conflict, not a silent no-op. Requires the `work_item:edit` permission.

Żądanie

Treść żądania

Up to 200 events, in the order they happened.

Przykład

curl -X POST 'https://app.motir.co/api/v1/dispatch-runs/{id}/events' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"events":[]}'

Odpowiedzi

Schemat odpowiedzi

Get a running hosted run’s git credentials

A running HOSTED run trades its own run credential for fresh git credentials: one entry per repository of the run, each an installation token of the Motir GitHub App that writes that repository, narrowed to the run’s repositories and to contents + pull-request write. Repositories in one installation share a token. Each lives one hour, so the run asks again whenever it needs one — this is also its FIRST git credential. Every token handed out is recorded against the run and revoked when the run ends. The author is the App’s bot, never a person; `dispatchedBy` names the dispatcher for pull-request bodies. Only the run’s own credential is answered — any other token, a person’s included, is refused before the run is read. Requires the `work_item:edit` permission.

Żądanie

Przykład

curl -X POST 'https://app.motir.co/api/v1/dispatch-runs/{id}/git-credential' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

Report that a local dispatch run is still alive

A LOCAL run says it is still working. The CLI sends one every 60 seconds while a run is open; a local run silent for 5 minutes is DEAD — its card shows the run died and `motir continue` may take the work over — and the server closes it `abandoned`. The server stamps the time itself; the request carries no body. Only the operator who opened the run may beat for it. A run that is already closed — usually by that lapse — is a conflict, and the answer is to stop beating, not to retry. It writes NO work-item status and no event. Requires the `work_item:edit` permission.

Żądanie

Przykład

curl -X POST 'https://app.motir.co/api/v1/dispatch-runs/{id}/heartbeat' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Delete a folder, moving its contents up

Delete a folder. NOTHING inside it is deleted: its child folders and filed work items move to the folder’s own parent (or the project root), and the body names them. Refused whole, changing nothing, when a child folder’s name collides at the destination (`FOLDER_NAME_TAKEN`) or when a ROOT folder holds a subtask that would be left with neither a parent nor a folder (`SUBTASK_NEEDS_PLACEMENT`). Requires the `work_item:edit` permission.

Żądanie

Przykład

curl -X DELETE 'https://app.motir.co/api/v1/folders/{folderId}' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

Read a folder

One folder by id, with its project key and path. A folder in another workspace, one in a project this token is not bound to, and one that never existed are the same 404 — the existence-oracle rule. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/folders/{folderId}' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

Rename, move or reorder a folder

A RENAME (`name`) OR a PLACEMENT (`parentFolderId`, `beforeId`, `afterId`) — never both in one request, because the two are applied separately and a combined request could half-apply; sending both is a 422 `INVALID_REQUEST`. A placement with no `parentFolderId` keeps the current parent (a pure reorder). Moving a folder into itself or one of its own folders is `FOLDER_CYCLE`; a destination in another project is `CROSS_PROJECT_FOLDER`; a name clash at the destination is `FOLDER_NAME_TAKEN`. There is no `If-Match`: folders carry no concurrency token. Requires the `work_item:edit` permission.

Żądanie

Treść żądania

Either the new name, or the new placement.

Przykład

curl -X PATCH 'https://app.motir.co/api/v1/folders/{folderId}' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Odpowiedzi

Schemat odpowiedzi

Who this token is

The token owner, the workspace the token is bound to, and the scopes it was granted. Call this first: the scope list is how a client discovers what its own credential may do without probing endpoints and collecting 403s. Requires the `project:browse` permission.

Przykład

curl -X GET 'https://app.motir.co/api/v1/me' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

Read a plan with the proposals it bundles

Read a plan WITH its proposals — what a planning pass actually proposed, not just how many. Each proposal carries its `op` (`add` / `modify` / `remove`), the `proposedFields` of an `add`, the `patch` of a `modify`, and the `parentRef` / `blockedByRefs` that let you rebuild the proposed tree and its dependency edges. ⚠️ These are PROPOSALS, not work items: an `add`’s `workItemKey` is `null` and stays null until the plan is approved in Motir, which is the only path from a proposal to a work item. A plan still generating returns the proposals that have arrived so far. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/plans/{planId}' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

Read what became of a submitted planning job

Read a plan’s status (`generating` / `planned` / `approved` / `declined`), how many PROPOSALS it bundles, and — while it is still generating — whether the producing job is alive or already FAILED. That last distinction is the point of this endpoint: a failed job writes no terminal plan state of its own — a background reconciler declines an empty one within the hour, so the plan status alone cannot tell you to stop polling NOW. `job.reachable: false` means motir-ai could not be asked, not that the job died. A pure read; the proposal count is NOT a count of created work items. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/plans/{planId}/status' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

List the projects in this token’s workspace

Every project the token owner may browse in the bound workspace, ordered by key ascending — a total order the page addressing owns, so a cursor can never skip or duplicate a row. A token BOUND to one project lists exactly that project — the same set `getProject` lets it open — so a narrowed credential is never shown a project it would then be refused. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/projects' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

PageEnvelope & object

Read a project

One project by key. A project the caller may not browse answers 404, not 403 — a 403 would confirm the project exists and let a caller enumerate which keys are real. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/projects/{projectKey}' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

Read a project’s backlog

The to-be-planned pile, in backlog-rank order. ⚠️ Done-category items are EXCLUDED — a finished unsprinted item does not belong in the backlog. (A sprint’s members are deliberately NOT filtered that way; see `listSprintWorkItems`.) Reports a total, because the read behind it already computes one. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/projects/{projectKey}/backlog' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

RankedPageEnvelope & object

Move work items out of their sprint and back to the backlog

An atomic batch move. An EMPTY array is a deliberate 200 no-op, not an error: a script that computed an empty batch has nothing to do rather than a mistake to fix. An over-cap batch is refused WHOLE, never partially applied. Requires the `sprint:manage` permission.

Żądanie

Treść żądania

The work items to move.

Przykład

curl -X POST 'https://app.motir.co/api/v1/projects/{projectKey}/backlog/work-items' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"workItemKeys":[]}'

Odpowiedzi

Schemat odpowiedzi

Browse a project’s approved designs

A cursor-paged collection of the project’s APPROVED designs, newest first — what an agent browses when the design it was handed is not the one it needs. A design still under review is not listed: it is not something to build against. ⚠️ NO download links: a list would mint one presign per row, and every one of them would start expiring before the caller read the page. Take links from `GET /api/v1/work-items/{key}/design` on the design you actually want. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/projects/{projectKey}/designs' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

PageEnvelope & object

List one level of a project’s folders

The CHILD folders of one level, in the order the tree shows them — the project root by default, or `parentFolderId`’s children. The tree is read level by level: walk down by listing a folder’s children. Each row carries its `path`, root first. A `parentFolderId` that is not a folder of this project is `FOLDER_NOT_FOUND`. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/projects/{projectKey}/folders' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

PageEnvelope & object

Create a folder

Create a folder at the project root or inside `parentFolderId`, appended last among its siblings. A sibling already holding the name (case-insensitively) is `FOLDER_NAME_TAKEN` (409); an empty or over-long name is `INVALID_FOLDER_NAME`; a parent in another project is `CROSS_PROJECT_FOLDER`. The `Location` header names the created folder. Requires the `work_item:edit` permission.

Żądanie

Treść żądania

The folder to create.

Przykład

curl -X POST 'https://app.motir.co/api/v1/projects/{projectKey}/folders' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"<name>"}'

Odpowiedzi

Schemat odpowiedzi

Open or resume the planning conversation for a scope

Open — or RESUME — the planning conversation for a project, and read its thread. Changing a plan in Motir is a multi-turn CONVERSATION: add turns, then send the accumulated intent. There is ONE thread per project per anchor set, so calling this again returns the SAME conversation, with every turn already on it — including the one the Motir web app shows. Pass `targetKeys` to anchor the conversation at specific work items ("re-plan these two"); omit it for the project-wide thread. The anchor set is the thread’s identity: order and duplicates do not matter. Opening submits nothing and costs nothing — which is why it is `read`-scoped despite being a POST (a GET that creates a row would not be safe). Requires the `ai:plan` permission.

Żądanie

Treść żądania

The optional anchor set. Omit for the project-wide thread.

Przykład

curl -X POST 'https://app.motir.co/api/v1/projects/{projectKey}/plan-session' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Odpowiedzi

Schemat odpowiedzi

Send the thread’s accumulated intent to the planner

Send this conversation’s accumulated intent to the planner: every turn on the thread, in order, as ONE change. Returns `202` with `{ jobId, planId, statusUrl }` the moment the job is accepted — it does not wait, and the body carries no result because there is none yet. The thread stays INTACT and can be refined with another turn. ⚠️ This is the act that SPENDS the token owner’s AI credits, and it produces a PLAN of proposals: approving that plan in Motir is the only thing that turns a proposal into a work item. Submitting a thread with no turns is refused. Requires the `ai:plan` permission.

Żądanie

Treść żądania

The optional anchor set naming which thread to submit.

Przykład

curl -X POST 'https://app.motir.co/api/v1/projects/{projectKey}/plan-session/submissions' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Odpowiedzi

Schemat odpowiedzi

Add one turn to the planning conversation

Add ONE turn — what you want changed about the plan. ⚠️ IMPORTANT: appending does NOT submit. The turn is persisted immediately, but no job starts, no credits are spent and no work item changes; turns ACCUMULATE until you post a submission, which is what sends them to the planner. That separation is the point — a later turn REFINES the earlier ones rather than replacing them, so "add auth to the billing epic" then "keep them under 3 points" go out as ONE coherent change. Addresses the thread by scope, so it always extends the same conversation. Requires the `ai:plan` permission.

Żądanie

Treść żądania

What to say in this turn, and the optional anchor set it belongs to.

Przykład

curl -X POST 'https://app.motir.co/api/v1/projects/{projectKey}/plan-session/turns' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"body":"<body>"}'

Odpowiedzi

Schemat odpowiedzi

Read a project’s ready BUGS lane

The ready BUG WORK: a ready `bug` (its own group, `container: null`), and the ready subtasks of a bug (grouped under it, `container` = the bug). The same order, facets and cascade as `getProjectReadyLeaves`; the two lanes are disjoint and together hold the whole ready set. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/projects/{projectKey}/ready/bugs' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

PageEnvelope & object

Read a project’s ready CONTAINERS lane

The RUNNABLE CONTAINERS — a `story`, `task` or `bug` whose every child is childless — that hold at least one row of the leaves lane, bugs excluded: the units a parent run takes. An `epic` is never one, nor is a container holding a grandchild. In the leaves lane’s group order, so `items[0]` is the next parent run. `readyLeafCount` counts its leaves-lane rows; `childCount` every live child. The facets apply to the CONTAINER; `kind`, `ancestor` and `allowSoftBlock` do not apply here and are a 422. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/projects/{projectKey}/ready/containers' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

PageEnvelope & object

Read a project’s ready LEAVES lane

The ready set minus BUG WORK (a `bug`, or a leaf whose parent is a `bug`), each row naming the RUNNABLE CONTAINER it groups under — a `story`, `task` or `bug` whose every child is childless, the shape a parent run accepts — or `null`. ORDER is part of the contract: rows are grouped by `container ?? self`, a group ranks by its best member’s `(kind, priority, key)`, and members keep that rank inside it, so `items[0]` is the next leaf to run. Readiness is the parent-ready cascade — a childless leaf, not terminal, every `blocked_by` blocker terminal and every ancestor ready; this lane and `getProjectReadyBugs` are disjoint and together hold the whole ready set. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/projects/{projectKey}/ready/leaves' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

PageEnvelope & object

List a project’s repositories

The project’s repository SET, in set order — the FIRST row is the project’s primary repository. Each row carries what a client needs to FIND and CLONE one: the checkout `name` (the host’s own casing, which is what a `targetRepo` pin stores), `repoRef`, `cloneUrl`, `defaultBranch` and `archived`. ⚠️ A row with no repository behind it yet is PRESENT with those fields `null` and its own `state` — a `proposed` row is a real member of the set, and a client must be able to say why it was skipped rather than watch it vanish. Branch on `established`, which is the same two-part rule (`state` is `created` or `connected` AND the repository is still connected) that dispatch itself resolves a checkout with. `cloneUrl` is DERIVED, and is `null` for a provider this build cannot address — the API never invents a host. Gated on `project:browse`, the key a CLI-minted token already holds. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/projects/{projectKey}/repositories' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

PageEnvelope & object

List a project’s sprints

The project’s sprints in sequence order, cursor-paged. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/projects/{projectKey}/sprints' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

PageEnvelope & object

Create a planned sprint

Create a sprint in the `planned` state. ⚠️ TWO gates apply: the token must be granted `sprint:manage`, AND its OWNER must be a sprint admin — a grant narrows a role and never widens it, so an ordinary member’s token is refused with the distinct `NOT_SPRINT_ADMIN` code rather than `INSUFFICIENT_PERMISSION`. The `Location` header names the created sprint. Requires the `sprint:manage` permission.

Żądanie

Treść żądania

The sprint to create.

Przykład

curl -X POST 'https://app.motir.co/api/v1/projects/{projectKey}/sprints' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Odpowiedzi

Schemat odpowiedzi

List a project’s work items

A cursor-paged collection of a project’s work items, optionally narrowed by a filter expression. Ordered by `(createdAt, id)` ascending — the position the cursor encodes. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/projects/{projectKey}/work-items' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

PageEnvelope & object

Create a work item

Create a work item in a project. The parent, if given, is named by its key and must be a kind-legal parent in the same project. Alternatively send `folderId` to file the new item into one of the project’s folders; naming both a parent and a folder is refused with `PLACEMENT_CONFLICT`. `obsolescence` (`outdated` / `deprecated`) and `obsolescenceNoteMd` may be set on any kind; a value outside the enum is refused with `INVALID_OBSOLESCENCE`. A MARK is a finished card’s state: a new item lands at the workflow’s initial status, so a mark on create is refused with `OBSOLESCENCE_REQUIRES_FINISHED` (422, `item`: the key and status) unless that status is in the done category — set it once the item is finished, and archive an item nobody will finish instead. A parent that carries a mark takes no new children: `MARKED_CARD_CANNOT_REOPEN` (422, `mark`: the parent’s key and mark). Requires the `work_item:edit` permission.

Żądanie

Treść żądania

The work item to create.

Przykład

curl -X POST 'https://app.motir.co/api/v1/projects/{projectKey}/work-items' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"epic","title":"<title>"}'

Odpowiedzi

Schemat odpowiedzi

Count a project’s work items

How many work items match a filter, in ONE request and without paging the match set. Takes the same `filter` the collection takes, and counts exactly what that collection would page. Exact, never capped. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/projects/{projectKey}/work-items/count' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

Atomically claim a whole story or sprint, all or nothing

CLAIM an entire SCOPE — a container work item and its children, or a project’s ACTIVE sprint — so a scoped run owns the whole set before its first agent starts. In ONE transaction the scope is validated, every row is locked in a deterministic order, every row’s status is re-checked against the TO-DO category, and — if all of them hold — every row is assigned to the caller AND moved to “In progress”. ⚠️ ALL OR NOTHING: if ANY member is un-claimable the whole claim rolls back and NOTHING is written, because a partially-claimed scope is the one outcome with no good handling — you can neither finish it nor cleanly abandon it. ⚠️ EVERY WORK ITEM IN A CLAIMED SCOPE READS “In progress” FOR THE WHOLE RUN, while only one of them is being worked at a time. That is deliberate and it changes what the status MEANS: from “an agent is on this right now” to “this run owns it”. The board therefore shows the run’s FOOTPRINT rather than its cursor — the price of exclusive ownership, which is what lets a scoped run promise to finish what it started. A refusal is a 200 with an `outcome`: `claimed`, `mine` (already yours — resume), `taken` (a member is held by somebody else, and they are named), `not_claimable` (a member is finished or under review), `wrong_shape` (a work-item scope whose child is itself a container — re-plan it, do not retry), `not_finishable` (work OUTSIDE the scope gates work inside it). A STORY scope is ONE LAYER and that is checked; a SPRINT scope may span many layers and no shape check applies, because `validate_sprint` has already guaranteed its membership is closed. A sprint’s scope is exactly the items whose OWN `sprintId` matches — an item under an in-sprint parent but not itself in the sprint is NOT claimed. The claim IS the dispatch status flip — do not also POST a transition afterwards. Requires the `work_item:edit` permission.

Treść żądania

The scope to claim: `{ "kind": "work_item", "key": "MOTIR-42" }` for a container and its children, or `{ "kind": "sprint", "projectKey": "MOTIR" }` for that project’s active sprint.

Przykład

curl -X POST 'https://app.motir.co/api/v1/scope-claims' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"<kind>","key":"<key>"}'

Odpowiedzi

Schemat odpowiedzi

Close out a merged session branch

Close out a session branch after its pull request is merged: every work item recorded on the branch moves to “Done” and its recorded branch is cleared. Returns a PER-ITEM outcome (`completed` / `already_done` / `failed`) — a partial close-out is a real result, not an error: the items that could close DID, and the ones that could not are named with a reason. Read the results; do not infer an outcome from their count. A branch nothing is recorded on returns an empty list, not a 404. The branch travels in the BODY because a git ref routinely contains `/`. Requires the `work_item:edit` permission.

Treść żądania

The merged session branch, and optional provenance for every item closed.

Przykład

curl -X POST 'https://app.motir.co/api/v1/sessions/complete' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"sessionBranch":"<sessionBranch>"}'

Odpowiedzi

Schemat odpowiedzi

Read a sprint

One sprint by id. A sprint in another workspace and one that never existed are the same 404 — the existence-oracle rule. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/sprints/{sprintId}' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

Update a sprint

Patch a sprint’s name, goal or window. A COMPLETED sprint is frozen: the body is fine, the state is not, so the refusal is a 409 rather than a 422. Requires the `sprint:manage` permission.

Żądanie

Treść żądania

The fields to change.

Przykład

curl -X PATCH 'https://app.motir.co/api/v1/sprints/{sprintId}' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Odpowiedzi

Schemat odpowiedzi

Complete a sprint

Close an active sprint, optionally carrying its unfinished items over to a named target. Completing a sprint that is not active is a 422. Requires the `sprint:manage` permission.

Żądanie

Treść żądania

Where unfinished items go, if anywhere.

Przykład

curl -X POST 'https://app.motir.co/api/v1/sprints/{sprintId}/complete' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Odpowiedzi

Schemat odpowiedzi

Start a sprint

Move a planned sprint to active. ⚠️ Losing the race to activate is a 409, not a 422: the request was valid when it was sent and another one committed first, so the right instruction is re-read-and-retry rather than fix-your-body. Starting a sprint that is not planned is a 422 — a state the caller can see from a read. Requires the `sprint:manage` permission.

Żądanie

Treść żądania

The sprint window, if it is being set here.

Przykład

curl -X POST 'https://app.motir.co/api/v1/sprints/{sprintId}/start' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Odpowiedzi

Schemat odpowiedzi

List a sprint’s members

The items in a sprint, in rank order. ⚠️ Deliberately asymmetric with the backlog: done items STAY in their sprint, because that is what makes a completed sprint a historical record. Reports a total, because the read behind it already computes one. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/sprints/{sprintId}/work-items' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

RankedPageEnvelope & object

Move work items into a sprint

An atomic batch move into this sprint. An empty array is a 200 no-op; an item belonging to another project rejects the WHOLE batch before any write, so a partial move cannot happen. Requires the `sprint:manage` permission.

Żądanie

Treść żądania

The work items to move.

Przykład

curl -X POST 'https://app.motir.co/api/v1/sprints/{sprintId}/work-items' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"workItemKeys":[]}'

Odpowiedzi

Schemat odpowiedzi

Read a work item

The full work item: its own fields, its parent and children, its five link groups, its readiness verdict, its comment count and — when it is filed — its folder (`folderId` and the root-first `folderPath`). The response carries an `ETag` for use as an `If-Match` on a later update. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/work-items/{key}' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

Update a work item

Patch any subset of a work item’s fields. A field that is ABSENT is untouched; a field explicitly set to `null` CLEARS it. Send `If-Match` to make the update conditional on the item not having moved. `folderId` files the item into a folder (or `null` takes it out), in the same write as every other field; setting `parentKey` on a filed item takes it out of its folder, and sending both is refused with `PLACEMENT_CONFLICT`. `obsolescence` and `obsolescenceNoteMd` mark the item as no longer true of the code on ANY kind, and `null` clears either; a value outside the enum is refused with `INVALID_OBSOLESCENCE`. A MARK is a FINISHED card’s state: setting `outdated` or `deprecated` on an item whose status is outside the done category is refused with `OBSOLESCENCE_REQUIRES_FINISHED` (422, `item`: the key, the status and its category) — archive an item nobody will finish instead. Clearing is always legal, and a patch that omits the mark never meets it. Re-parenting under a marked item (`parentKey`) is refused with `MARKED_CARD_CANNOT_REOPEN` (422, `mark`). Requires the `work_item:edit` permission.

Żądanie

Treść żądania

The fields to change.

Przykład

curl -X PATCH 'https://app.motir.co/api/v1/work-items/{key}' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Odpowiedzi

Schemat odpowiedzi

Read a work item’s activity — changes, comments, or both

Read a work item’s activity in one of three views: `all` (default — comments and the change trail interleaved in timestamp order), `comments` (the discussion), or `history` (the change trail only). Every entry carries a `type` so one renderer serves all three. The `cursor` is OPAQUE and SCOPED TO ITS VIEW: echo it back verbatim, never construct or parse one, and never hand a cursor from one view to another — that is a 422, not a silent restart. A page may be SHORTER than you expect while more remains (the change scan is noise-filtered and a comment page drags whole reply threads along), so walk until `nextCursor` is `null`, never until a page looks short. `GET /api/v1/work-items/{key}/comments` still exists and is unchanged — this view is the same data through the same read, offered so one code path can walk all three. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/work-items/{key}/activity' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

RankedPageEnvelope & object & object

Submit a hosted review run’s ONE verdict

Decide a work item’s `agent_review` gate as the REVIEW AGENT: `pass` approves it, which raises the approve-and-merge gate for the same version; `changes_requested` records `findingsMd` (required, non-empty) as the gate’s note and moves nothing — the card is To fix. `subjectVersion` must be the version the review prompt named. ONE verdict per run (`REVIEW_VERDICT_ALREADY_SUBMITTED`, 409). A verdict for a version the gate no longer asks about, or a gate already superseded or decided, is RECORDED on the run and decides nothing (`REVIEW_STALE`, 409). Accepts ONLY the credential of a `review` dispatch run, for that run’s own card. Requires the `work_item:edit` permission.

Żądanie

Treść żądania

The reviewed version, the verdict, a short summary and the findings.

Przykład

curl -X POST 'https://app.motir.co/api/v1/work-items/{key}/agent-review' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"subjectVersion":"<subjectVersion>","verdict":"pass"}'

Odpowiedzi

Schemat odpowiedzi

One gate’s decision record on a work item

The DECISION a person made on one approval gate — its `state`, the `noteMd` they wrote, who wrote it, when, on which `subjectVersion`, under which authority and through which surface (`docs/decisions/approval-gates.md` §6a’s audit set). This is how an agent reads the answer to a question it raised: **Request changes** records its reason in `noteMd`, and before this read every door onto that column was session-authed, so the one gate kind whose author is always an agent — `decision_approval`, raised only on a `type: decision` + `executor: coding_agent` card — was the one kind whose refusal an agent could not read. ⚠️ `gate: null` is an ANSWER, not a miss: the card has no gate of that kind, so nothing is waiting and nothing was decided; a key that does not resolve is the 404 instead. Read `state` BEFORE the audit fields — five of them are written by the decision, so a null means *not yet decided* and never *decided by nobody*. ⚠️ A READ ONLY: nothing on this API decides a gate, and nothing here asserts `approval:decide_any` — deciding stays session-authed, deliberately (§1, §2). Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/work-items/{key}/approval-gate' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

Archive a work item

A recoverable soft-remove. Does NOT cascade to children — the irreversible subtree delete is not exposed by this API at all (ADR §3). Requires the `work_item:archive` permission.

Żądanie

Przykład

curl -X POST 'https://app.motir.co/api/v1/work-items/{key}/archive' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

Attach a file to a work item

Upload a file and attach it to the work item, as `multipart/form-data` with a single `file` part. This is the GENERAL door: it carries no artifact kind and belongs to no lifecycle, so any deliverable a work item produces — a research findings document, a review’s notes — can reach the item that commissioned it. A DESIGN asset does not use this endpoint; it has its own publisher, whose result renders in the Design result panel. ⚠️ Two size limits apply and the SMALLER one is not this API’s: the organization’s plan sets a per-file entitlement (10 MB, or 100 MB on a paid plan) and is what returns 413, while a direct upload is separately capped at roughly 4.5 MB by the serving platform and is refused before the request reaches Motir. Requires the `work_item:edit` permission.

Żądanie

Treść żądania

The file to attach, in a `file` part. An empty part is a 422.

Przykład

curl -X POST 'https://app.motir.co/api/v1/work-items/{key}/attachments' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -d '{"file":"<file>"}'

Odpowiedzi

Schemat odpowiedzi

Atomically claim one work item by key

CLAIM one work item, named by key, so that concurrent dispatchers cannot both start it. In ONE transaction the row is locked, its status is re-checked against the TO-DO category, and — if it holds — the item is assigned to the caller AND moved to “In progress”. The to-do category is `todo` AND `blocked`, so a deliberately forced dispatch of an item whose dependencies are unmet still works. ⚠️ A refusal is a 200 with an `outcome`, not an error, because three of the four outcomes are ordinary: `claimed` (it is yours), `mine` (already yours — resume your own interrupted run), `taken` (somebody else holds it, and they are named), `not_claimable` (finished, under review, or otherwise outside the to-do category). Claiming is IDEMPOTENT for the holder and never re-opens finished work. The claim IS the dispatch status flip — do not also POST a transition afterwards. Requires the `work_item:edit` permission.

Żądanie

Przykład

curl -X POST 'https://app.motir.co/api/v1/work-items/{key}/claim' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

List a work item’s comments

Root comments with their single-level reply threads, cursor-paged. This collection DOES report a total, because the shipped read computes it as a bounded aggregate. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/work-items/{key}/comments' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

RankedPageEnvelope & object

Comment on a work item

Add a root comment, or a reply by naming a root comment as its parent. Replies are single-level: a reply to a reply is a 422. Requires the `comment:add` permission.

Żądanie

Treść żądania

The comment to add.

Przykład

curl -X POST 'https://app.motir.co/api/v1/work-items/{key}/comments' \
  -H 'Authorization: Bearer $MOTIR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"bodyMd":"<bodyMd>"}'

Odpowiedzi

Schemat odpowiedzi

Claim the continue of a work item whose last run died

Take over a work item whose last run DIED (`motir continue <key>`), for any member who may edit the project, and hand back what the continuing agent needs: the dead run, the branch its work is on, and its open pull request. In ONE transaction the item’s row is locked and, in order: an open dispatch run with command `continue` already holding the item answers `mine` (yours — same `runId`, the branch again) or `taken` (named, with its start); a run that is still ALIVE (a local run that heartbeat within 5 minutes, an open hosted run) is `not_continuable` (`run_alive`, naming its dispatcher); an item at Implemented / In Review / Approved is `use_fix` (its pull request is open — CI or `motir fix` owns it); any other status but In Progress is `not_in_progress`; a leg of a dead PARENT run is `continue_the_parent` (naming `parentKey`); no run that ended without success is `no_dead_run`; a run that STOPPED AT A GATE (closed `gated`) whose gates all still wait is `gate_awaiting`, and one whose gates were sent back and none approved is `gate_sent_back` (both naming `gates`); a dead run that left no branch is `no_branch`. A gated run with an APPROVED gate is taken over like a dead one, as a resume (`resumesGated`, the approved `gates`). Otherwise a LAPSED run still reading `running` is closed `abandoned`, the item is RE-ASSIGNED to the caller, and a `continue` run is opened: `claimed`. ⚠️ A refusal is a 200 with an `outcome`, not an error. ⚠️ The item’s STATUS is never written. Heartbeat the run (`heartbeatDispatchRun`) and CLOSE it (`closeDispatchRun`) when the continue ends. Requires the `work_item:edit` permission.

Żądanie

Przykład

curl -X POST 'https://app.motir.co/api/v1/work-items/{key}/continue' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi

Schemat odpowiedzi

One design card’s approved design

The verdict for ONE design card, addressed by its own key — the read behind following a design a `…/designs` verdict named, and behind finding a delta mock’s amended base by its `sourcePath`. Same verdict rules and same link terms as `…/designs`. Requires the `project:browse` permission.

Żądanie

Przykład

curl -X GET 'https://app.motir.co/api/v1/work-items/{key}/design' \
  -H 'Authorization: Bearer $MOTIR_TOKEN'

Odpowiedzi