User guide
Sample agent skill
A ready-to-install SKILL.md that teaches a coding agent the entire
Backendup token API: configuration, organization-scoped routes, creating and
retrieving work, finding and claiming the next item, commenting, triage, re-parenting,
automation rules, status moves, and completion with commit evidence. It is the same contract
this site's own agents run on, with one machine's specifics removed.
install into your agent's skills directory
no bundled scripts required
yours to adapt
The skill
---
name: backendup-work-items
description: >-
Create, retrieve, claim, and complete work items on Backendup via the token
API (/api/v1/). Use when the user asks to create a work item, file a story or
task under a parent, fetch or list work, get the next claimable item, claim
work, post progress comments, set priority, tag labels, re-parent an item with
move-to-parent/, read organization
vocabularies, install or read automation rules, move status, and complete
items with commit delivery evidence. Every route is organization-scoped:
/api/v1/orgs/<org>/...
---
# Backendup work items (starter skill)
> This is a template. Install it as your agent's skill (adjust `name` and
> `description` to your agent runtime's conventions), set the environment
> variables below, and let the agent act **as the token owner** - never with
> shared credentials. It documents the whole contract the token API offers;
> the live endpoint table is at `/docs/api/` on any Backendup site.
Act only as the token owner using their live project membership and grants.
Never log, print, expose, or commit the bearer token.
Every project and work-item route is addressed through its organization:
`/api/v1/orgs/<org_slug>/...`. The path org must be the token's own
organization or one of its descendants; refs (`KEY-N`) and slugs resolve
uniquely inside that one org, so there is no cross-org lookup. A path org
outside the token's subtree returns 403; an unknown or deactivated org returns
404.
## Config
Read configuration from the environment; never hardcode a host, token, or
project slug.
| Variable | Required | Meaning |
|---|---:|---|
| `BACKENDUP_API_TOKEN` | Yes | Organization API token (`bup_...`), bound to one organization |
| `BACKENDUP_API_BASE` | No | Defaults to `https://backendup.com/api/v1` without a trailing slash |
| `BACKENDUP_PROJECT_SLUG` | If project unnamed | Project slug from `/o/<org_slug>/projects/<slug>/` |
Tokens carry a **scope**. `work` (the default, and every token issued
before BACKENDUP-624) covers the whole tracker surface this skill describes.
`admin` is a superset for organization administration - invitations, service
accounts, token issuance, workflow administration - and only managers may mint
it. Check your credential with `GET me/` (`token_scope`); using a work token on
an admin route answers 403 `admin_scope_required`, and minting or revoking
service-account tokens over the API is itself an admin verb, never something a
work token can do (human personal tokens are minted in the browser only).
Derive `<org_slug>` for a call: the token's organization comes from
`GET $BACKENDUP_API_BASE/me/` (`organization_slug`); when the target lives in
a descendant org, use that org's slug in the path. If the user gives a project
URL (`/o/<org>/projects/<slug>/`), take the org and project slugs from it.
Otherwise use `BACKENDUP_PROJECT_SLUG` with the token's org. If neither is
available, ask the user.
Send these headers with every request:
```http
Authorization: Bearer $BACKENDUP_API_TOKEN
Content-Type: application/json
```
Use JSON bodies only. Do not send form data, CSRF tokens, or session cookies.
## Workflow rules
- Routine lifecycle calls for the work item currently being worked on need no
confirmation: reading items, claiming, posting progress comments, changing
status, and completing with evidence. Report what was done afterwards
instead of asking first.
- Confirm before writes that create or change something the user did not ask
for: new work items or nested trees, edits to an unrelated item, a re-parent,
relations, or any item outside the current task.
- When asked to start work, claim the item before working. Do not use
`force: true` unless the user explicitly asks to take over an assigned item.
- Do not reopen terminal work items or parents. Do not invent an assignee,
project slug, kind, iteration, priority, or status.
- Write every work item or project you name inside a `description` or a
comment as a clickable markdown link - `[KEY-N](/o/<org_slug>/w/KEY-N/)` -
see *Link items in prose*. Never invent an org slug to complete a link.
- Do not print the bearer token in terminal output, comments, commits, issue
descriptions, or logs.
## Create work items
Create one item, a nested tree, or several roots with:
```text
POST $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/work-items/
```
A request body may be one JSON object or a non-empty JSON array (transactional:
if any entry fails, none are created). At most 50 total nodes per request,
including nested children. Do not send `number`; Backendup assigns it.
Each item requires `name` and `kind`. Optional fields are `description`,
`assignee`, `iteration_id`, `priority`, `labels`, `start_date`, `due_date`,
`end_date`, `story_points`, and `status`. Dates use `YYYY-MM-DD`; story points
must be positive with at most two decimal places. Omitting `priority` applies
the organization default; sending null means deliberately untriaged. A `status`
the project offers and the matrix reaches from the default moves the new item
through the normal status change (lifecycle dates and audit included) instead of
a second call; omit it to start at the project default.
Use only enabled work-item type codes the organization exposes. Built-in
examples include `epic`, `feature`, `story`, `task`, `subtask`, `bug`,
`investigation`, `spike`, `improvement`, and `chore`; `subtask` must have a
parent, and never create a root `subtask`.
**Child** (the usual case when the user names a parent - `KEY-N` or slug):
```json
{
"name": "Wire webhook",
"kind": "task",
"parent_ref": "PAY-1",
"description": "Optional implementation context."
}
```
The parent must be in the same project, open, and allowed by the organization's
hierarchy to contain the requested kind. A child inherits an ancestor due date
when no explicit `due_date` is supplied; explicitly sending `null` overrides
inheritance.
**Root item**: omit `parent_ref`.
**Nested tree**: for a parent plus children in one request, use `children`;
nested entries ignore `parent_ref` because their enclosing node is the parent.
```json
{
"name": "Feature",
"kind": "feature",
"children": [
{"name": "Story", "kind": "story", "children": [{"name": "Task", "kind": "task"}]}
]
}
```
The response is `{"work_items": [<detail>, ...]}` (or one detail envelope for
a single-object create). For every created item, retain `ref` for API actions
and `slug` plus `organization_slug` for web links. Confirm creation with
`GET .../work-items/<ref>/`. Build the web URL as
`<site-origin>/o/<organization_slug>/projects/items/<slug>/`, deriving
`<site-origin>` by removing `/api/v1` from `BACKENDUP_API_BASE`. Never
construct a web URL from the project slug or item ref alone.
When the URL belongs in prose a human reads on the site (a description or
comment), prefer the rename-proof ref permalink
`<site-origin>/o/<organization_slug>/w/<ref>/` - see *Link items in prose*.
## Author projects
```text
POST $BACKENDUP_API_BASE/orgs/<org_slug>/projects/ {"name": "Payments", "key": "pay"}
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/
PATCH $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/ {"description": "…", "status": "active"}
POST $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/delete/ {"confirm": "cascade"}
```
Creating needs a contributor membership (member or above) in the organization -
grant-only external collaborators cannot mint projects. `key` uppercases,
stays unique inside the organization, and derives from the name when omitted;
`slug` derives too and collides into a numeric suffix instead of an error,
exactly like the form. New projects start at the organization default status
and belong to the acting user; watching one is a `watch/` POST.
PATCH runs each field through the browser's own parser and permission tier:
contributor fields (`name`, `description`, `github_repository`,
`github_auto_status`) need edit; `key`, `slug`, and `status` need project
management; `delivery_evidence` needs configuration, and switching it to `off`
while evidence exists answers `delivery_evidence_in_use`. **Close and reopen**
are ordinary `status` writes to an active organization status code - a terminal
category is what makes `work-items/` refuse with `project_closed`, and the
reopening is the same PATCH back to an active code. `organization` is not
patchable: moving a project between organizations stays in the browser, like
the work-item subtree rule.
Deleting follows the cascade discipline (see "Delete and re-home items"): a
project still containing work items refuses with `work_items_conflict` until
`{"confirm": "cascade"}`; an empty project deletes on an empty body. The
cascade - items, comments, attachments, relations, evidence, audit history -
is the browser's and is not recoverable through this API.
## Plan iterations
```text
POST $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/iterations/ {"name": "Sprint 3", "start_date": "2026-11-16", "end_date": "2026-11-27", "goal": "…", "status": "planned"}
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/iterations/<iteration_id>/
PATCH $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/iterations/<iteration_id>/ {"status": "active"}
```
The `iterations/` list stays a summary (`id`, `name`, `status`, dates); the
detail payload adds `goal` and `position`. Creating needs `name`, `start_date`,
and `end_date` (`YYYY-MM-DD`, never inverted); the name must stay unique inside
the project - a collision answers 409 `duplicate_iteration` from either route.
`status` is a free choice among `planned`/`active`/`completed` in both
directions: an iteration is a planning container, not work - there is no
transition matrix, no open-children confirmation, and closing one completes
nothing by itself (record the item statuses themselves). You may record a past
iteration as `completed` in one POST. New iterations append after the last
`position`, like the form. The gate is project edit permission - a member can
plan, a viewer cannot. Iterations carry no audit trail in either surface; work
items hold the history.
## Import what you exported (the loop closes)
```text
POST $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/import/ {"csv": "<text>" ["mode": "create-only"|"upsert"|"update-only", "update_columns": ["status", ...], "blanks_clear": true]}
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/import/<plan_id>/ (page rows: ?limit&cursor)
POST $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/import/commit/ {"plan": "<plan_id>"} | {"csv": "<text>" [+ the mode fields]} ["expect": {"to_create": N, "to_update": N} | {"digest": "..."}]
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/imports/ (the ledger: newest first, ?limit&cursor)
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/imports/<batch_id>/ (one batch + its undo_plan; a committing call answers batch_id)
POST $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/imports/<batch_id>/undo/ {}
```
`GET backlog/export/` -> edit -> `POST import/` -> `POST import/commit/`, no
browser: the export's exact contract is accepted back by the **same** engine
the web preview runs (BOM tolerance, semicolon dialects, the 50,000
parsed-row cap reported as the file's own `usable: false` +
`row_limit_exceeded`). Row failures are never request errors - a 200 report
with `summary.failed > 0` is a usable file. A usable plan is held 24 hours,
owner- and project-scoped: `plan_id` + `digest` come back, and commit
replans the **stored** text, so what you previewed is what commit answers
for (a Ref that appeared since the preview skips, the same race guard as the
UI). Rows page through the plan route (100 at a time, `next` is an offset
token; summary always states the whole file).
Update modes (BACKENDUP-652/656): `upsert` updates rows whose Ref matches an
existing item (blank Ref creates), `update-only` updates and never creates
(blank or unmatched Refs refuse per row). Blanks **preserve**; `blanks_clear`
is the deliberate exception, and Name/Status never clear. `update_columns`
declares the scope - the file cannot carry intent, a spreadsheet re-save
writes every header - and Type/Parent are never updated, only warned. The
held plan remembers the choices it was previewed under (the plan routes echo
`mode`/`update_columns`/`blanks_clear`); commit by handle refuses mode fields
(400) because they are the preview's own.
Commit answers `{"result": {counts, created, updated, unchanged, skipped, failed}}`. The handle
is **one-shot**: a second commit is 409 `plan_not_found`, never a re-run -
re-importing a ported file into a fresh project legitimately creates again
(foreign Refs have no identity to skip against), so double-submitting is
refused rather than trusted. `expect` lets commit refuse to disagree with
what you read (counts of creations and updates, or the digest): mismatch is
409 `plan_stale` and the plan survives for a corrected retry. `{"csv": ...}` direct commit is the same code path without
a preview - a refusal carries the report (`file_unusable` arrives with it).
Import creates work items only, so plain `work` scope suffices; every
created row's audit says "via an API token" like the rest of this API.
Upsert over existing Refs remains deferred (skips are reported, never
guessed); same-project Refs inside a file stay inert by guard. A commit that wrote anything answers `batch_id`; the ledger routes show its outcomes and the read-only `undo_plan` (what would be deleted, restored, and what a human edited since - left standing with its reason). The undo POST rolls the batch back exactly once: `undone_at` is claimed under a row lock, so a concurrent second call gets 409 `already_undone`, an undo batch answers 409 `not_undrollable`, and a failed undo un-spends its claim for a retry.
## Saved filters and exports
```text
GET $BACKENDUP_API_BASE/orgs/<org_slug>/filters/
POST $BACKENDUP_API_BASE/orgs/<org_slug>/filters/ {"name": "My week", "query": "status:in_progress", "visibility": "private"}
GET $BACKENDUP_API_BASE/orgs/<org_slug>/filters/<id>/ (definition + results page, ?page=N)
PATCH $BACKENDUP_API_BASE/orgs/<org_slug>/filters/<id>/ {"statuses": ["new"]}
POST $BACKENDUP_API_BASE/orgs/<org_slug>/filters/<id>/delete/
GET $BACKENDUP_API_BASE/orgs/<org_slug>/filters/<id>/export/ (CSV)
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/backlog/export/
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/board/export/
```
Saved filters are the **Work page's own question shape**: conditions live in
`projects`/`statuses`/`kinds`/`priorities`/`labels`/`dues` plus
`needs_attention`/`source`, or arrive as a `query` sentence in the same
grammar `?q=` uses - the API runs the *same* `SavedFilterForm`, so a condition
outside the caller's visible choices is refused and the sentence always
compiles exactly as the page's box does. `GET` detail renders the stored filter
back into `query`, so read-modify-write round-trips through one grammar.
A filter stores a **question, not an answer**: results (paged detail rows, and
the CSV export) always resolve against the *reading* caller's visibility - a
shared filter shows each member only work they could already open. Sharing
grants a read and nothing more: only the owner can PATCH or delete, shared or
not; `editable` on the payload names your own rights. The surface is member
only - external collaborators and the org gate mirror the dashboard's rule.
Name collisions answer 409 `duplicate_filter`; other refusals list per-field
messages in `fields` with `invalid_filter`.
Backlog/board exports take the same query parameters the list routes accept
and stream the *page's own* rows as CSV (tree order for backlog, status as a
column for board) - never a re-derived second rule.
## Retrieve work items
List endpoints are read-only GETs and accept no body. By default lists omit
terminal items; use `include_closed=true` or `open=0` to include them.
Supported filters include `q`, repeatable `status`, `type`, `priority`,
`label`, plus `assignee` (`unassigned` for null), `claimable=true`, and
`iteration`. Follow the returned `next` cursor; `limit` defaults to 50,
maximum 100.
```text
GET $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/work-items/?type=story&claimable=true
GET $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/backlog/
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/iterations/
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/iterations/<iteration_id>/work-items/
```
`<ref>` is `KEY-N` or the item slug; both are unique within the path org. A
reference belonging to another organization is simply `not_found`. The detail
envelope includes the full description, direct children, comments, relations,
attachments, dates, story points, priority, labels, `allowed_transitions`, and
the watcher roster (`watchers`, plus your own `is_watching`).
## Find the next item
When asked to start work without a named item, do not guess from a general
list - ask for a structural leaf and exclude containers:
```text
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/work-items/next/?leaf=true&container=false
GET $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<parent-ref>/next/?leaf=true&container=false
```
The result is `{"work_item": <summary>}` or `{"work_item": null}`. Selection
favors active iterations, then unplanned work; it never pulls from future
planned iterations. Use a `run_id` (letters, digits, dots, underscores,
colons, hyphens; max 64) when a run must survive a crash or restart:
```text
GET .../work-items/next/?leaf=true&container=false&run_id=<run-id>
```
## Claim a work item
Before beginning work:
```text
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/claim/
{}
```
To claim and move to the organization's in-progress status in one transaction:
```json
{"in_progress": true, "run_id": "<run-id>"}
```
Do not send `in_progress` unless it is the JSON boolean `true`. Claiming an
item already assigned to the token owner is idempotent. Stop on
`already_assigned` or `already_in_progress`; never force-claim without explicit
user authorization. Terminal items cannot be claimed or reopened.
## Comment, rename, re-text
```text
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/comments/ {"body": "...", "parent_id": null}
PATCH $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/ {"name": "...", "description": "...", "due_date": "2026-12-05", "assignee": "roster-username"}
```
Comments are full-length markdown; `@name` mentions notify, so treat comment
text like any outward-facing write. `parent_id` must identify a top-level,
non-deleted comment on the same item - replies are one level deep. An empty
body is rejected (`invalid_body`).
`PATCH` accepts `name`, `description`, `start_date`, `due_date`, `end_date`,
`story_points`, `assignee`, and `iteration_id` (any other key returns
`invalid_payload` listing what is accepted; status moves go through
`POST .../status/` - a status is a transition, not a field). Dates are
`YYYY-MM-DD` and story points follow the create limiters (positive, at most two
decimals); `null` clears any optional field, including `assignee` (unassign)
and `iteration_id` (must name an open iteration of this project). Every value
runs through the same parser create uses, so the routes cannot disagree, and a
payload with one bad value applies none of its good ones. `description`
replaces outright - send `""` or `null` to clear. A rename never changes `slug`
or `ref`, so pasted links keep resolving. Submitting an unchanged value writes
nothing, checked per field. Terminal items stay updatable on purpose, so an
agent can refresh a spec that has drifted. Each real change records one audit
event attributed to the token owner.
## Link items in prose
Descriptions and comments render as CommonMark, and a reader can follow every
link you give them but no bare ref. When you name another work item or a
project inside a `description` or a comment body, write it as a markdown link
to the ref permalink:
```text
[KEY-N](/o/<org_slug>/w/KEY-N/) work item (rename-proof)
[<project name>](/o/<org_slug>/projects/<project_slug>/) project
```
You nearly always hold the pieces already: every detail envelope carries
`organization_slug`, `ref`, and `project_slug`, and every list and search row
names its organization. The `/w/` route resolves the ref and redirects to the
canonical page; refs are allocated once and never reused, so a pasted link
cannot drift when the item is later renamed - prefer it over the slug URL in
prose. Root-relative links are right for text a human reads on the site; when
the same text may also be read off it (mail, chat mirrors), prefix
`<site-origin>` as derived in *Create work items*.
Leave a ref as plain text only when you cannot know its organization - a bare
`KEY-N` the user typed without context, or an item outside the token's
subtree. Never guess an org slug to complete a link: a wrong link is worse
than plain text. Do not wrap `@name` mentions, status codes, priorities, or
label names in links - mentions notify on their own and the rest are not
pages.
## Triage: priority, labels, vocabularies
```text
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/priority/ {"priority": "high"}
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/labels/ {"labels": ["incident", "customer-reported"]}
GET $BACKENDUP_API_BASE/orgs/<org_slug>/work-item-options/
```
Priority codes are organization configuration, not a fixed enum - read them
from `work-item-options/` (which also lists labels) rather than guessing;
never invent a code from another organization. `{"priority": null}` clears the
field ("deliberately untriaged"), which is not the same as omitting it on
create. Labels are a **replace**, not an append: send the full desired set;
`{"labels": []}` clears. Unknown label names are created (typing is how the
vocabulary grows), matched case-insensitively. Filter lists by label `slug`.
Every item payload carries `priority*` fields and `labels` as
`{name, slug, color}` objects.
## Re-parent an item
```text
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/move-to-parent/ {"parent_ref": "PAY-12"}
```
`parent_ref` is a `KEY-N` ref or a slug **in the same project**; send `null` to detach the
item to the project root, which works only for kinds the organization's hierarchy allows at
root. The item's whole subtree travels with it, the item lands at the **end of its new
sibling group** (there is no ordering parameter), and `slug` and `ref` never change, so
pasted links keep resolving. The response is the item's full detail envelope.
Rules are checked in an order that names the one that broke: a target the token cannot see,
or one in another project, is `parent_unavailable` (404); the item itself or one of its
descendants is `parent_cycle`; a kind the target may not contain is
`parent_cannot_have_children`; a subtree that would pass the nesting limit is
`invalid_hierarchy`. **A closed parent refuses live work** with `parent_closed`, because
nothing reopens a status a human chose - reopen that parent deliberately through
`POST .../status/` if the user asked for it, or leave the item where it is. A closed item
**may** be moved under a closed parent. Completion then reconciles along both the ancestor
chain the item left and the one it joined, and one audit event is written, attributed to the
token owner.
No payload carries a `depth` value, so confirm a move from the two shapes that encode it:
`GET .../projects/<project_slug>/backlog/?include_closed=true` nests each item under its
parent, so the nesting level is the depth (without `include_closed=true` a finished child is
absent and reads as lost), and `GET .../work-items/<new-parent-ref>/next/?leaf=true&container=false`
should answer with that subtree's first open leaf in backlog order - a stale depth shows up
there as a queue the board disagrees with.
Sending the parent the item already has returns it and writes nothing. Edit rights are
required (`permission_denied`). A `404` whose body is HTML, or that carries no `code`, means
the server predates the route rather than that the token lacks rights.
## Delete and re-home items
```text
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/delete/ {"confirm": "cascade"}
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/project/ {"project": "<target-slug>"}
```
Deleting is irreversible through this API: the item, its descendants, their
comments, attachments, relations, and audit history all cascade. A leaf takes
an empty body. When the item has descendants the route refuses with
`descendants_conflict` naming the count and previewing up to ten visible
children - resubmit with `{"confirm": "cascade"}` only when the user asked for
this deletion. Parents' completion rollups reconcile after the delete, as in
the browser.
Reassignment moves a **root** item and its whole subtree to another project in
this organization: manage permission on both projects, fresh `KEY-N` refs in
the target's sequence, the subtree appended after the target's last root, and
iterations cleared (they belong to the old project). Every preflight the
browser enforces answers `move_conflict` (or `delivery_evidence_in_use`) with
the human message and a scrubbed preview of what blocks the move: kinds,
excluded statuses/priorities, status-mapping confirmation (retries only honor
`{"confirm_status_mapping": true}`), parented items answer `item_has_parent`.
Cross-organization reassignment stays in the browser - the token's subtree is
the API's boundary. The response is the item's detail envelope under its
**new** ref.
### Ordering on the move
```text
POST $BACKENDUP_API_BASE/orgs/<slug>/work-items/<ref>/backlog-reorder/ {"direction": "up|down|top|bottom", "steps": 2} | {"position": 3} | {"before": "PAY-4"} | {"after": "some-slug"}
```
Exactly one of `direction` (with optional `steps`), `position` (1-based slot in the
sibling group), or a `before`/`after` sibling anchor (ref or slug). The group is
the item's current parent and project - the set the backlog draws - locked and
re-indexed with the browser's own helpers, so positions stay on the 1000-step
lattice and concurrent reorderers cannot interleave a torn order. Refusals carry
the sidebar's messages under `invalid_reorder`; the response is the detail
envelope with the new `backlog_position`. Moving to a parent appends to the new
group by default; a move body may add `"placement": "top"` or a
`"before"/"after"` anchor **from the destination group** - an unknown anchor is
refused before anything moves, and ordering writes no audit rows anywhere, in
either surface, by design.
## Relate work items
```text
GET $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/relation-targets/?q=<text>
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/relations/ {"relation_type": "blocks", "target": "KEY-N"}
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/relations/<id>/remove/
```
Types: `blocks`, `relates_to`, `duplicates`, `causes`, `solves` (read them from
the docs page; they are fixed vocabulary). A relationship edits two rows, so the
token needs edit permission on **both** ends - the same rule the browser picker
enforces. `relation-targets/` lists independently visible, same-organization
candidates (max 20, `has_more`), never the source itself; a candidate that is
visible but not editable is still refused by the create route. `relates_to` and
`duplicates` are symmetric: stating the same pair from the other side is the
same link and answers 409 `relation_exists` (treat it as done, not as an error
to retry differently). A `blocks` edge that would close a dependency cycle
answers 400 `relation_cycle`; an unseen or foreign-organization target is
`not_found`; both endpoints' audit timelines record the add/remove. Both verbs
return this item's detail envelope, whose `relations` list carries the relation
`id` needed for a later removal.
## Watch progress
```text
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/watch/
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/unwatch/
POST $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/watch/
POST $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/unwatch/
```
Watching is a subscription, not a write: seeing the item or project is the only
requirement, and it never changes anyone else's state. Subscribe to work you are
not assigned to follow its progress; subscribe to a whole project to hear about
everything in it. Both verbs are idempotent - repeating the current state adds
no audit - and the response carries `watchers` (usernames) and your
`is_watching` so you can confirm the outcome. Work-item routes return the full
detail envelope; project routes return the project row plus the two watch
fields (BACKENDUP-627).
## Provision people and machines (admin scope)
```text
GET $BACKENDUP_API_BASE/orgs/<org_slug>/invitations/
POST $BACKENDUP_API_BASE/orgs/<org_slug>/invitations/ {"email": "[email protected]", "role": "member"}
POST $BACKENDUP_API_BASE/orgs/<org_slug>/service-accounts/ {"username": "deploy-bot", "name": "CI token", "scope": "work"}
POST $BACKENDUP_API_BASE/orgs/<org_slug>/service-accounts/<user_pk>/tokens/ {"name": "Nightly runner"}
POST $BACKENDUP_API_BASE/orgs/<org_slug>/api-tokens/<id>/revoke/
```
This is the provision-on-behalf door, and its boundary is the point: **agents
staff the org, humans activate themselves.** An invitation creates the pending
membership and posts the activation email - the person sets their own password,
MFA and social login in the browser, and an account registered with an invited
email claims the invitation automatically. The API never sends, stores, or sees
a human credential. Service accounts (bot users that cannot sign into the
website) and their tokens are created over the API, and the token's secret is
returned exactly once, in the issuing response - store it in the runner's
secret store immediately. Revoke is incident response: idempotent, the row
stays as history, and `already: true` tells a retry its work is done.
Every verb needs an admin-scoped token **and** organization management rights,
runs the browser's own forms (duplicate members, email-domain policy, the
external-collaborator project requirement), shares the token-create throttle
(`429 too_many_token_creations`), and fires the same account-security
notifications. A personal token for a human cannot be minted here - that
stays a browser action, gated on the human's own MFA freshness.
## Shape the workflow (admin scope)
```text
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/workflow-overrides/
POST $BACKENDUP_API_BASE/orgs/<org_slug>/projects/<project_slug>/workflow-overrides/ {"section": "work_item_status", "hidden": ["in_verification"], "default": "new", "aliases": {"new": {"name": "Backlog"}}}
GET $BACKENDUP_API_BASE/orgs/<org_slug>/work-item-statuses/
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-item-statuses/ {"name": "Blocked", "category": "to_do", "color": "#b91c1c"}
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-item-statuses/<code>/ {"name": "On ice"}
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-item-statuses/<code>/default/
GET $BACKENDUP_API_BASE/orgs/<org_slug>/work-item-priorities/ (+ POST create/update/default, same shape)
GET $BACKENDUP_API_BASE/orgs/<org_slug>/work-item-transitions/
PUT $BACKENDUP_API_BASE/orgs/<org_slug>/work-item-transitions/ {"transitions": [{"from": "new", "to": "in_progress"}]}
```
Every verb here is organization administration: writes require an **admin-scoped**
token (403 `admin_scope_required` otherwise; reads need org management rights but
any project viewer may read that project's curation). Each route reuses the
browser editor's form or model service - retirement guards, default transfer,
position/color validation, transition locks and their per-edge audit history -
so the API and the page cannot drift into two different rulebooks.
Project curation is per-section and opt-out: `hidden` lists entry refs (codes;
label slugs), `default` picks one or `"org"`, `aliases` renames/recolors catalog
entries for this project, `{"reset": true}` returns a section to inheritance.
Hiding an entry that live work still carries refuses with 400
`override_conflict` naming the blocking refs - re-type those items first. The
organization's override policy may lock or inherit a section; the payload says
which are `editable` and who `locked_by` is before you try.
The transitions PUT **replaces the whole matrix** - send every edge you want to
keep. Unknown or retired codes answer 400 `invalid_transition` with an `index`;
self-pairs are never stored. Remember the order: after a replace or a curation
change, re-read the project `workflow/` route before driving item transitions,
because `illegal_transition` now reflects what you just shaped. Creating new
statuses and priorities, hierarchy rules, project lifecycle statuses, and
organization override policies themselves stay browser-only in this round.
## Automation rules
These routes *manage* event-to-action rules; installing one decides what
happens to other people's work, so the token owner needs organization-admin
standing - a token that may move its own items cannot rewrite everyone's, and
every call answers 403 `permission_denied` until it has that standing.
```text
GET $BACKENDUP_API_BASE/orgs/<org_slug>/automation-rules/
POST $BACKENDUP_API_BASE/orgs/<org_slug>/automation-rules/
GET $BACKENDUP_API_BASE/orgs/<org_slug>/automation-rules/<int:pk>/
PATCH $BACKENDUP_API_BASE/orgs/<org_slug>/automation-rules/<int:pk>/
DELETE $BACKENDUP_API_BASE/orgs/<org_slug>/automation-rules/<int:pk>/
```
The list returns rules in `position` order, which is also execution order.
A rule carries `name` (unique per organization), `trigger` (`created`,
`status_changed`, or `assignee_changed`), optional `project_slug` (omit for
org-wide), optional `from_status`/`to_status` (a status rule must name at
least one), `conditions` (`kinds`, `priorities`, `labels`, `iterations` as
code/slug/id lists - empty matches anything), and an ordered `actions` list.
Action `type` and `value`: `set_status` (an **active** status code),
`set_assignee` (username, or `none`/`unassigned`), `add_label`, `add_comment`,
`set_due_offset` (whole days from today), `link_iteration` (id or
`unplanned`).
Behaviours worth knowing before installing a rule: actions run in order and
`set_status` must come **last** if present (it can start another rule; the
validator refuses it elsewhere). One user action cascades through at most
**3** passes; a non-converging cycle stops as a reported `skipped` outcome,
never a stuck request. Only `set_status` re-enters the rules. Project and
organization rules match together in position order. `PATCH` leaves unsent
keys alone; sending `actions` replaces the whole list. Deleting keeps the
history: each mutation a rule made carries the rule's name in the audit
change set. The same validation backs the web editor (Organization settings
-> Automations), so a rule an agent can install is a rule a person can save.
## Move files
```text
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/attachments/ {"files": [{"name": "log.txt", "content_base64": "…"}]}
GET $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/attachments/status/?id=<pk>&id=<pk>
GET $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/attachments/<pk>/
```
Project subjects take the same three routes under `…/projects/<project_slug>/attachments/`.
The token API is JSON-only, so uploads ride as `content_base64` (strict base64;
`name` and `content_type` optional). The browser's pipeline runs untouched: the
same size limit per file **and per request total**, magic-byte sniffing, image
re-encode, sha256 infected-verdict reuse, and virus-scan queueing - a refusal
reads `invalid_attachment` with the offending file's `index`. At most 10 files
per request. Upload needs participate permission on the subject.
New rows appear in the detail envelope as `{id, original_name, content_type,
size, scan_status, is_image, created_at}`. While a row is `pending` its bytes
are not downloadable: poll `attachments/status/` (or re-read detail) until it
turns `clean` - `infected` rows never download, and a not-clean or unseen file
answers the same `not_found` as a missing one, by design. Downloads come as
plain bytes with `Content-Disposition: attachment` under the stored content
type. Never copy base64 bodies into work-item comments: the bytes belong to
the file, not the thread.
## Move status and record delivery
```text
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/status/
{"status": "<transition-code>"}
```
The code must be one of the item's `allowed_transitions` from the detail
response (e.g. `in_review`, `completed`, `wont_do`, `on_hold`). A terminal
item's status cannot be changed again.
```text
POST $BACKENDUP_API_BASE/orgs/<org_slug>/work-items/<ref>/delivery-links/
{"type": "commit", "url": "https://github.com/<owner>/<repo>/commit/<full-sha>", "sha": "<full-sha>", "repo": "<owner>/<repo>"}
```
Always send the **full commit hash** read from `git rev-parse HEAD` - never a
hash typed from memory. A malformed hash is accepted silently and becomes a
permanent broken evidence link: the API can add delivery links but has no
route to remove one; only a human clearing it in the item's evidence list can
undo it. Duplicates of the same type+url are idempotent.
## Complete with evidence
When the item is a story whose delivery is a pushed commit, the completion
workflow is: post the delivery link **first**, then move the status - if
evidence fails to post, the status must not change. Then stop; do not start
another work item until the user explicitly asks.
## Search across the organization
```text
GET $BACKENDUP_API_BASE/orgs/<org_slug>/search/?q=<query>&scope=all
```
The Work-page search, on the token API: the same grammar (`status = New`,
quoted phrases, refs like `PAY-12`), the same repeatable refinements
(`organization`, `project` as `project:<org>:<slug>` tokens, `type`, `status`)
and single-valued `assignee`, `author`, `after`, `before`
(`YYYY-MM-DD`), the same fixed 25-row pages behind an opaque `cursor` -
echo the response's `next_cursor` back as `cursor` (it is a value, not a URL
like the list routes' `next`, because search pages cross sources).
Two API conventions apply: the search runs **inside the route's organization**
by default (widen with `organization` values, but only inside the token's own
subtree - foreign values answer 403 like a foreign path would), and rows carry
content only - `{result_type, reference, title, subtitle, organization,
excerpt, updated_at}` - never HTML links or highlight markup. Resolve a hit by
sending its `reference` to `work-items/{ref}/` or the project route.
`result_type` covers `project`, `work_item`, `delivery_link`, `discussion`, and
`conversation_discussion`; `scope` selects among `all`, `projects`,
`work-items`, and `collaboration`. Bad values answer 400 `invalid_search` with
the browser's own message; an empty `q` returns no rows, as on the page.
Visibility is never widened by search: every row is something the token owner
could already open, and shared-scope results (discussions) follow the same
rule as in the browser.
## Identity and projects
```text
GET $BACKENDUP_API_BASE/me/
GET $BACKENDUP_API_BASE/orgs/<org_slug>/me/
GET $BACKENDUP_API_BASE/orgs/<org_slug>/projects/
```
`/me/` answers the acting user, their `organization_slug`, membership role,
and the token's name and expiry - the first call to make when the org is
unknown.
## Error handling
| HTTP status | Code | Action |
|---:|---|---|
| 401 | `authentication_required`, `invalid_token` | Verify the environment token is present and valid; never display it. |
| 403 | `organization_access_denied`, `permission_denied`, `admin_scope_required` | Stop; the token lacks organization or write access, or the route needs admin scope (re-issue from a manager account; do not retry the work token) (also returned when the path org is outside the token's subtree). |
| 404 | `not_found`, `parent_unavailable` | Stop; verify the org, project, and reference with the user. Cross-organization refs are `not_found`. |
| 400 | `project_closed`, `parent_closed`, `item_closed` | Stop; do not reopen items or projects. On `move-to-parent/`, `parent_closed` means the item being moved is still live work. |
| 400 | `parent_cycle`, `invalid_parent_kind`, `invalid_hierarchy` | The move's shape is wrong, not its permission: pick a target that is not the item's own descendant, keep a parented kind under a parent, or place it higher in the tree. Never retry the same target. |
| 400 | `invalid_name`, `invalid_kind`, `parent_cannot_have_children` | Correct the requested name/kind/hierarchy, clarifying as needed. |
| 400 | `invalid_payload`, `invalid_json` | Correct the JSON shape; never use form data. |
| 400 | `invalid_search` | A search parameter broke a browser-defined rule (scope, work-item type, status, visible organization, cursor, or query length); the message says which - fix that value, do not retry the same one. |
| 400 | `invalid_project_key`, `invalid_project_slug`, `invalid_status`, `invalid_delivery_evidence`, `invalid_github_repository`, `invalid_github_auto_status` | The project field failed the browser's own parser for that field: fix the value (keys uppercase and stay organization-unique; slugs suffix themselves; statuses must be active organization codes). |
| 409 | `duplicate_filter` | This owner already saves a filter with that name (case-insensitive): pick another or edit the existing one from `filters/`. |
| 409 | `duplicate_iteration` | An iteration name belongs to the project already - reuse the existing one (find it in `iterations/`) or rename; never assume the create half-succeeded. |
| 400 | `work_items_conflict` | The project delete would destroy its work items too: read the totals, and resubmit with `{"confirm": "cascade"}` only when the user asked for it. |
| 400 | `descendants_conflict` | The delete would cascade to descendants: read the preview, and resubmit with `{"confirm": "cascade"}` only if the user asked for this deletion. |
| 400/409 | `move_conflict`, `item_has_parent` | The reassignment fails a browser-equal preflight (kinds, excluded statuses/priorities, cross-org target, relations, or a status mapping needing `{"confirm_status_mapping": true}`); a parented item must move with its root. |
| 409 | `invitation_exists` | An unclaimed invitation for that address is already pending - reuse it (its id is in the payload), do not pile up invites. |
| 429 | `too_many_token_creations` | The shared token-create throttle answered; back off and retry later - do not mint around it with another name. |
| 400 | `invalid_invitation`, `invalid_service_account`, `invalid_token_request` | A provisioning form refused the payload; `fields` names what to fix (email/role/projects, username, token name/scope/expiry). |
| 400 | `invalid_reorder` | A backlog reorder or move placement broke a sibling-group rule (anchor outside the group, self-anchor, position out of range, direction or steps invalid); re-read the group and retry with a real sibling. |
| 400 | `invalid_override`, `override_conflict` | Project curation failed a browser-equal guard (default hidden, unknown entry ref, or the entry still carries live work - `override_conflict` names the blocking refs). |
| 400 | `invalid_transition`, `invalid_catalog_entry` | A transition pair names a non-active status (fix the `index`-ed entry), or a catalog write failed the editor's own form rules (see `fields`). |
| 400 | `invalid_attachment`, `invalid_attachment_id` | The file list or its base64/sizes failed the pipeline guards (the payload names which index); resubmit the whole request after fixing it. |
| 400 | `invalid_assignee`, `invalid_iteration`, `invalid_date`, `invalid_story_points`, `invalid_priority`, `invalid_labels` | Resolve or remove the invalid optional value; read a label's real spelling from the options route. |
| 400 | `invalid_status`, `illegal_transition` | The status move (explicit or on create) is not offered: read the project's `workflow/` route for active statuses and reachable transitions; never force it. |
| 409 | `already_assigned`, `already_in_progress` | Stop; never force-claim without explicit user authorization. |
| 409 | `relation_exists` | The link is already there (symmetric types count both directions): treat it as done; do not retry from the other side. |
| 400 | `invalid_relation_type`, `invalid_target`, `relation_cycle` | Pick a type from the docs vocabulary; resolve the target through `relation-targets/`; a cycle needs a human to remove the closing edge first. |
| 409 | `run_in_progress` | Continue the existing run, or use a new run id after the item is In Review or terminal. |
If a create request fails, correct the relevant org path, name, kind,
hierarchy, assignee, iteration, priority, labels, dates, story-points value,
JSON body, or project slug - never retry by setting `number`. Creation is
transactional: an unreachable `status` answers `invalid_status` or
`illegal_transition` and leaves no half-built tree behind.
## Out of scope
The token API does not cover custom slugs, or moving a
work item across **organizations**. The web UI does the latter. Note the URL prefix when linking pages by hand:
project pages live under `/o/<org_slug>/`, organization settings under
`/orgs/<org_slug>/`; they are mounted by different URLconfs and are not
interchangeable.
Set BACKENDUP_API_TOKEN (an organization token from
Settings → API tokens) in the environment your agent runs in, adjust
the front-matter name/description to your agent runtime's
conventions, and treat the workflow rules as a starting point - they encode good
agent manners, not law.