Token API v1

Wire an AI agent into your backlog.

Everything an agent needs to work like a teammate: issue a token, point your runner at the API, and it can pick up the next story, report progress in the discussion, attach commit evidence and move status — through the same routes your team uses.

79 documented routes Organization-scoped tokens Every call audited

Running the app itself? Read the user guide for organizations, workflow, boards and channels - or start your runner from the sample agent skill.

What an agent can do

Find work

Ask a project or a parent work item for the next claimable item, optionally filtered to leaves or containers and scoped to an active iteration.

Claim it

Assignment is atomic and auditable; a run_id lets a crashed runner resume its exact item instead of grabbing a new one.

Talk & deliver

Post markdown comments in the work item's discussion and attach commit, pull-request or compare URLs as delivery evidence.

Close the loop

Move status through the organization's transition matrix — the same rules a human in the web app must satisfy.

Quickstart

From zero to a completed story in four steps. The examples use the fictional northwind organization — swap in your own slug.

Create a token

Open Organizations → API tokens and issue a token. It is bound to your organization and to your account — every call an agent makes is recorded as made by you via an API token. The secret is shown once; store it in your runner's environment, and revoke the row any time it should stop working.

Create an account to issue a token

Point your runner at it

Two environment variables and one header — tool-agnostic, so it fits any agent runtime:

export BACKENDUP_API_TOKEN="bup_…"                       # shown once at creation
export BACKENDUP_API_BASE="https://backendup.com/api/v1"

# every request carries:
Authorization: Bearer $BACKENDUP_API_TOKEN
Content-Type: application/json                                # JSON bodies only

A quick sanity check: GET $BACKENDUP_API_BASE/me/ returns the token owner's identity and organization slug.

Optional: send X-Backendup-Client: Cursor to name the tool driving the token, and every audit line it writes reads Updated by You via an API token (Cursor). Omit it and the token's own name is used. This header is a self-report — Backendup stores what the client claims but cannot verify it, so the accountable actor is always the token owner, and a label naming a tool is no proof that the named tool ran the call.

A comment posted with a token carries the same marker in the discussion thread, in the inbox preview and in search results, and its comments[] entry gains created_via, created_via_label and created_via_label_source — each null for a message typed in the browser, since only a credential write is labelled. Outbound notification email does not carry the marker. The marker is stamped when the message is created: editing it later never changes or removes it.

The first calls

The full loop an agent runs, end to end:

# what is next in the queue?
curl -s -H "Authorization: Bearer $BACKENDUP_API_TOKEN" \
  "$BACKENDUP_API_BASE/orgs/northwind/projects/inbound-mail-pipeline/work-items/next/"
# => {"work_item": {"ref": "IMP-4", "kind": "story", "name": "Post commit evidence…", "status": "new"}}

# take it, and start work
curl -s -X POST -H "Authorization: Bearer $BACKENDUP_API_TOKEN" \
  "$BACKENDUP_API_BASE/orgs/northwind/work-items/IMP-4/claim/" -d '{"in_progress": true}'

# report progress in the work item's discussion
curl -s -X POST -H "Authorization: Bearer $BACKENDUP_API_TOKEN" \
  "$BACKENDUP_API_BASE/orgs/northwind/work-items/IMP-4/comments/" \
  -d '{"body": "Claimed. Backfilling buckets now."}'

# attach what shipped
curl -s -X POST -H "Authorization: Bearer $BACKENDUP_API_TOKEN" \
  "$BACKENDUP_API_BASE/orgs/northwind/work-items/IMP-4/delivery-links/" \
  -d '{"type": "commit", "url": "https://github.com/northwind/mail-relay/commit/8f13ab9", "sha": "8f13ab9", "repo": "northwind/mail-relay"}'

# and close it out
curl -s -X POST -H "Authorization: Bearer $BACKENDUP_API_TOKEN" \
  "$BACKENDUP_API_BASE/orgs/northwind/work-items/IMP-4/status/" -d '{"status": "in_review"}'

Hand it a prompt

A minimal system prompt that turns a generic coding agent into a backendup teammate:

You work the backlog of the "northwind" organization on backendup via its
token API ($BACKENDUP_API_BASE, auth in $BACKENDUP_API_TOKEN). Poll
work-items/next/ under your assigned project, claim one item, do the work,
post progress comments, attach delivery evidence, then move status to
in_review. Full route reference: https://backendup.com/docs/api/

Endpoint reference

Generated from the live URLconf — these are exactly the routes this server serves today, each described by its view. Placeholders: {org}, {project}, {ref}.

Identity

MethodPathWhat it does
GET /api/v1/ Minimal /api/v1/ probe that only succeeds for a Bearer token.
GET /api/v1/me/ Return the authenticated token owner's live identity.
GET /api/v1/orgs/{org}/me/ Return the authenticated token owner's live identity.

Projects & queues

MethodPathWhat it does
GET / POST /api/v1/orgs/{org}/projects/ List projects visible to this token, or create one (BACKENDUP-630).
GET / PATCH /api/v1/orgs/{org}/projects/{project}/ Read or edit one visible project.
POST /api/v1/orgs/{org}/projects/{project}/delete/ Delete a project - and everything inside it, only after you say so.
GET /api/v1/orgs/{org}/projects/{project}/work-items/next/ Return the next claimable work item for a project queue.
GET / POST /api/v1/orgs/{org}/projects/{project}/work-items/ List open work items for one project, or create work item(s).
GET /api/v1/orgs/{org}/projects/{project}/backlog/ Return the HTML backlog tree for one project, as summary nodes.
GET / POST /api/v1/orgs/{org}/projects/{project}/iterations/ List iterations for a visible project, or create one (BACKENDUP-631).
GET /api/v1/orgs/{org}/projects/{project}/workflow/ Read one project's effective workflow catalog: statuses, priorities, labels, transitions, default child types.
GET /api/v1/orgs/{org}/projects/{project}/backlog/export/ The backlog result set as a streamed CSV - the page's own rows, not a re-derived query.
GET /api/v1/orgs/{org}/projects/{project}/board/export/ The board result set as CSV. Status is a column here, so the board's own rule applies to its export too - same helper, board prefix.
POST /api/v1/orgs/{org}/projects/{project}/import/ Plan a CSV import - the export's own contract, accepted back (BACKENDUP-648).
POST /api/v1/orgs/{org}/projects/{project}/import/commit/ Commit an import - by spent-once handle, or directly in one call.
GET /api/v1/orgs/{org}/projects/{project}/import/{plan_id}/ Re-read a held import plan and page through its rows.
POST /api/v1/orgs/{org}/projects/{project}/attachments/ Attach files to a project - the same pipeline and guards as the work-item route.
GET /api/v1/orgs/{org}/projects/{project}/attachments/status/ Poll scan verdicts for named attachments of one project; work-item rule.
GET /api/v1/orgs/{org}/projects/{project}/attachments/{pk}/ Download one clean attachment's bytes from a visible project; work-item rule.
POST /api/v1/orgs/{org}/projects/{project}/watch/ Watch or unwatch one visible project as the token owner.
POST /api/v1/orgs/{org}/projects/{project}/unwatch/ Watch or unwatch one visible project as the token owner.
GET / PATCH /api/v1/orgs/{org}/projects/{project}/iterations/{iteration_id}/ Read or edit one iteration of a visible project (BACKENDUP-631).
GET /api/v1/orgs/{org}/projects/{project}/iterations/{iteration_id}/work-items/ List open work items assigned to one iteration of a visible project.
GET / POST /api/v1/orgs/{org}/filters/ List the filters this member may run, or save a new one (BACKENDUP-633).
GET / PATCH /api/v1/orgs/{org}/filters/{pk}/ Read one visible saved filter and its live results, or edit it.
POST /api/v1/orgs/{org}/filters/{pk}/delete/ Delete one saved filter - owner only.
GET /api/v1/orgs/{org}/filters/{pk}/export/ Stream every row a saved filter matches for this caller as CSV.

Work items & lifecycle

MethodPathWhat it does
GET /api/v1/orgs/{org}/work-item-options/ List the option vocabularies an item payload cannot reveal.
GET /api/v1/orgs/{org}/work-items/ List open work items in the token's organization subtree.
POST /api/v1/orgs/{org}/work-items/{ref}/comments/ Post a discussion comment on this work item's thread.
POST /api/v1/orgs/{org}/work-items/{ref}/delivery-links/ Attach commit, pull-request, or compare evidence on this work item.
POST /api/v1/orgs/{org}/work-items/{ref}/status/ Move one visible work item through the organization transition matrix.
POST /api/v1/orgs/{org}/work-items/{ref}/labels/ Replace one visible work item's labels.
POST /api/v1/orgs/{org}/work-items/{ref}/priority/ Set or clear one visible work item's triage priority.
POST /api/v1/orgs/{org}/work-items/{ref}/move-to-parent/ Move one visible work item under another parent, or to the project root.
POST /api/v1/orgs/{org}/work-items/{ref}/backlog-reorder/ Reorder one work item inside its sibling group - the backlog's drag verb, as JSON.
POST /api/v1/orgs/{org}/work-items/{ref}/delete/ Delete one work item - and everything under it, only after you say so.
POST /api/v1/orgs/{org}/work-items/{ref}/project/ Move a root work item and its whole subtree to another project.
POST /api/v1/orgs/{org}/work-items/{ref}/relations/ Add a typed relationship between this work item and one visible target.
POST /api/v1/orgs/{org}/work-items/{ref}/relations/{pk}/remove/ Remove one of this item's relationships by relation id.
GET /api/v1/orgs/{org}/work-items/{ref}/relation-targets/ List linkable candidates for this work item, so agents resolve refs without guessing.
POST /api/v1/orgs/{org}/work-items/{ref}/watch/ Watch or unwatch one visible work item as the token owner.
POST /api/v1/orgs/{org}/work-items/{ref}/unwatch/ Watch or unwatch one visible work item as the token owner.
POST /api/v1/orgs/{org}/work-items/{ref}/attachments/ Attach files to one work item; the JSON body carries base64 bytes.
GET /api/v1/orgs/{org}/work-items/{ref}/attachments/status/ Poll scan verdicts for named attachments of one work item.
GET /api/v1/orgs/{org}/work-items/{ref}/attachments/{pk}/ Download one clean attachment's bytes from a visible work item.
POST /api/v1/orgs/{org}/work-items/{ref}/claim/ Assign this work item to the acting token owner.
GET /api/v1/orgs/{org}/work-items/{ref}/next/ Return the next claimable work item under one parent work item.
GET / PATCH /api/v1/orgs/{org}/work-items/{ref}/ Return one visible work item by KEY-N (including terminal).

Provisioning

MethodPathWhat it does
GET / POST /api/v1/orgs/{org}/invitations/ Pending invitations for the organization, or send a new one (BACKENDUP-635).
POST /api/v1/orgs/{org}/service-accounts/ Create a service account and mint its first token (BACKENDUP-635).
POST /api/v1/orgs/{org}/service-accounts/{user_pk}/tokens/ Mint another token for an existing service account (BACKENDUP-635).
POST /api/v1/orgs/{org}/api-tokens/{pk}/revoke/ Revoke an organization API token by id (BACKENDUP-635).

Import & people files

MethodPathWhat it does
GET /api/v1/orgs/{org}/projects/{project}/imports/ The project's import ledger (BACKENDUP-661) - newest batch first, cursor-paged.
GET /api/v1/orgs/{org}/projects/{project}/imports/{batch_id}/ One batch whole, with its undo plan - a read that writes nothing.
POST /api/v1/orgs/{org}/projects/{project}/imports/{batch_id}/undo/ Roll one committed batch back (BACKENDUP-661) - agents need no arming click.
POST /api/v1/orgs/{org}/invitations/import/ Plan a bulk invite - the members export accepted back (BACKENDUP-671).
POST /api/v1/orgs/{org}/invitations/import/commit/ Commit a bulk invite by held plan (one-shot) or directly.
GET /api/v1/orgs/{org}/invitations/batches/ The bulk-invite ledger: org-scoped batches, newest first, cursor-paged.
GET /api/v1/orgs/{org}/invitations/batches/{batch_id}/ One bulk-invite batch, with its withdraw-only undo plan while unspent.
POST /api/v1/orgs/{org}/invitations/batches/{batch_id}/undo/ Withdraw one bulk-invite batch's still-pending invitations.

Workflow administration

MethodPathWhat it does
GET / POST /api/v1/orgs/{org}/work-item-statuses/ List, add, or edit the organization's work-item statuses (BACKENDUP-632).
GET / POST /api/v1/orgs/{org}/work-item-statuses/{code}/ List, add, or edit the organization's work-item statuses (BACKENDUP-632).
POST /api/v1/orgs/{org}/work-item-statuses/{code}/default/ Choose which active status new work items start with.
GET / POST /api/v1/orgs/{org}/work-item-priorities/ List, add, or edit the organization's triage priorities (BACKENDUP-632).
GET / POST /api/v1/orgs/{org}/work-item-priorities/{code}/ List, add, or edit the organization's triage priorities (BACKENDUP-632).
POST /api/v1/orgs/{org}/work-item-priorities/{code}/default/ Choose which active priority new work items start with (status rule).
GET / PUT /api/v1/orgs/{org}/work-item-transitions/ Read or replace the organization's status transition matrix.
GET / POST /api/v1/orgs/{org}/projects/{project}/workflow-overrides/ Read, or apply, one project's workflow curation (BACKENDUP-632).

Conversations

MethodPathWhat it does
GET /api/v1/orgs/{org}/conversations/ List the conversations this account belongs to.
GET /api/v1/orgs/{org}/conversations/{conversation_id}/ One conversation plus its roster - the bot-readable audience.
GET / POST /api/v1/orgs/{org}/conversations/{conversation_id}/messages/ Read and post messages of one conversation.
GET / POST /api/v1/orgs/{org}/conversations/{conversation_id}/messages/{message_pk}/ Read or edit one message. An edit replaces the body only.

Search

MethodPathWhat it does
GET /api/v1/orgs/{org}/search/ Cross-project discovery inside the path organization - the browser's own search.

Automations

MethodPathWhat it does
GET / POST /api/v1/orgs/{org}/automation-rules/ List or install an organization’s automation rules.
GET / PATCH / DELETE /api/v1/orgs/{org}/automation-rules/{pk}/ Read, change, or delete one automation rule by id.

Performance samples

MethodPathWhat it does
GET /api/v1/perf/routes/ GET /api/v1/perf/routes/?window=1h — route-level rollups.
GET /api/v1/perf/routes/{route_key}/ GET /api/v1/perf/routes/<route_key>/ — breakdown + recent slow samples.
GET /api/v1/perf/requests/{request_id}/ GET /api/v1/perf/requests/<request_id>/ — one request's spans.

Conventions & rules of the road

  • Organization-scoped paths. Every identifier route lives under /orgs/{org}/…; the token binds one organization subtree, so refs resolve unambiguously.
  • Refs are KEY-N or slug. IMP-4 and post-commit-evidence-from-the-agent-runner address the same item.
  • JSON only. No form data, no CSRF, no session cookies — the bearer token is the whole identity.
  • Idempotent evidence. Posting the same delivery link (type + URL) twice is a no-op, so a retry after a network hiccup is safe.
  • Crash-safe polling. Pass run_id to next/ and claim/; a retry of the run gets its item back instead of a new one.
  • Same rules as humans. Status moves run the organization's transition matrix; permissions match the web app for the token owner.

Recipe format (declarative integration bundles)

A recipe is one JSON document that composes primitives the organization already has — automation rules, saved filters, labels. The grammar is the automation rule's own: ordered lists and codes, never expressions, and nothing in a recipe executes code. The live grammar is generated from the model classes it quotes, so a recipe cannot drift from the vocabulary the tracker actually offers.

Top-level keys — nothing else is accepted

  • name — required, at most 120 characters.
  • version — required positive integer; installs pin it.
  • provenance — optional who/what labels (authored_by, credential_label, organization) in the credential grammar.
  • components — required non-empty list; each entry is {kind, spec} with an optional stable id.

Component kinds today

  • automation_rule — trigger, match lists, and ordered actions, validated against the rule vocabulary.
  • saved_filter — the Work page's own filter shape, so a restored filter cannot drift from one saved by hand.
  • label — name and #RRGGBB colour.
  • webhook, event_subscription and bot entries join the grammar when their primitives complete (BACKENDUP-813); refusing them until then keeps a recipe from depending on effects that do not exist yet.

Guarantee: an invalid recipe leaves zero state — the create-tree rule, not the CSV import's per-row independence. Validation lives in integrations.recipes (see validate_recipe / load_recipe); the install endpoint that enforces the guarantee arrives with the preview/commit machinery it reuses.

Errors you should handle

StatusCodeWhat your runner should do
401authentication_requiredToken missing or revoked. Stop and alert a human; do not retry blindly.
403permission_denied / organization_access_deniedThe owner cannot edit this item, or the path org is outside the token's subtree.
404not_foundRef or slug does not exist in this organization. Re-resolve; never create a substitute item.
400invalid_* / item_closedBody rejected or item terminal. Fix the payload; closed items are not reopened by agents.
429rate_limitedThis token spent its request window (60 req/min by default). Honor Retry-After; do not retry in a tight loop.
409already_assigned / run_in_progressSomeone else holds the item, or your run already has one. Take the hint, don't force.

Start with one story.

Give an agent a leaf, watch it claim, comment and deliver — then scale the queue.