docs~/agents/api.md
/esc
~/agents/api.md
agents/api.md · 15 min · updated 2026-11-09 · as markdown

# API

The API is plain JSON over HTTPS, authorized by an API token. It speaks in names, not ids: issues by key (WEB-12), states and labels by name, people by email. Descriptions and comments are Markdown. Every write goes through the same checks as a change made in the browser: rights, the agent rules, the issue's history, and live updates to every open window. The rsva CLI is a client of this API; rsva api sends any request below that has no command of its own.

Address and token

All endpoints but files live under one base address:

text
https://app.rsva.dev/api/v1/workspaces/<workspace>/

<workspace> is the workspace's slug, the first part of its address in the app. A token opens exactly one workspace; any other slug answers 404.

Send the token in the Authorization header:

text
Authorization: Bearer rsva_...

Make tokens in Settings › API tokens (how). The examples below use two shell variables:

sh
export RSVA_TOKEN=rsva_...      # your token
export RSVA_WS=acme             # your workspace's slug

Check whose token it is and what it may change:

sh
curl -s https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/workspace \
  -H "Authorization: Bearer $RSVA_TOKEN"

The answer has the workspace's slug, name, color and memberRights, and me: your email, name, kind (human or agent), role, the token's scope (read, write or custom) and grants, the resources it may change right now.

Conventions

  • Issues by key, in any case: WEB-12 or web-12. A key the issue had before its project was renamed, or before it moved to another project, still finds it.
  • Projects by key. States, labels and cycles by name, in any case; a cycle also by its short form, C12.
  • People by email, or me for the token's own member. GET …/members lists the emails.
  • Priority: urgent, high, medium, low or none (or 0–4).
  • Dates: YYYY-MM-DD.
  • Text: descriptions and comments are Markdown, read and written. A description is at most 200,000 characters, a comment 65,536, a title 500. Titles are stored cleaned: line breaks and tabs become spaces, invisible characters go.
  • Mentions: [@Sam](mention:sam@example.com), or mention:me; an empty label ([](mention:sam@example.com)) gets the person's name. When the text is read back, the target is the person's id.
  • Images: a line of its own, ![caption](/files/<workspace>/<sha256>), with a file uploaded to this workspace. Any other image address stays text.
  • Files in a comment: a paragraph of its own, [report.pdf](/files/<workspace>/<sha256>?name=report.pdf&size=2100), shows as a file card.
  • A write answers {"ok": true, "lastSyncId": 1234} plus what the endpoint adds. lastSyncId is the change's place in the workspace's log.
  • Answers over 1 KB are compressed when the request asks for it (Accept-Encoding: br or gzip). With curl, add --compressed.

Limits

Limit Value
Requests per token 600 a minute
Changes per person 3,000 operations and 16 MiB a minute, across all their sessions and tokens
Uploads per person 256 MiB a minute
One file 25 MiB
Files per workspace 10 GiB
Issues changed or moved in one request 500

Over a limit, the answer is 429 rate_limited with a retry-after header in seconds. Inbox and comment reads also count against a per-person read budget and answer 429 the same way.

Too many wrong tokens from one IP address (300 in 15 minutes) also get 429, before the token is even looked up.

Errors

An error is JSON with a code and a message that says what is wrong, often listing what there is:

json
{"error": "bad_ref", "message": "no label \"nope\"; labels: \"bug\", \"chore\""}
Status error When
400 invalid A field is missing or malformed, or there is nothing to change.
400 bad_ref A name, key or email resolves to nothing.
400 deleted The issue is in the trash. Restore it first with {"deleted": false}.
400 invalid_query q does not parse; errors lists each problem with suggestions.
401 unauthorized No token, or it is revoked or expired.
403 forbidden The token, the role or a rule does not allow it. The message names what is missing. Nothing was written.
404 not_found No such workspace (for this token), issue, comment or link.
409 conflict A name or key is taken, or cycle dates overlap.
409 similar A new issue looks like an open one. See below.
413 too_large, quota A file over 25 MiB, or the workspace's files would pass 10 GiB.
429 rate_limited Over a limit. Wait retry-after seconds.
503 unavailable The database is busy or restarting. As a rule nothing was written; retry after retry-after.

Other pipeline refusals also answer 400 with their own code.

Pagination

  • Issue lists take limit (1 to 500, default 100) and answer {"total": 230, "issues": [...]}. There is no offset: narrow the query to see more.
  • Comments come a page at a time, newest page first. If there are earlier ones, the answer has older; pass it back as ?until= for the page before.

Issues

Method and path Purpose
GET /issues List or search issues.
GET /issues/:key One issue, with description, relations, links, files and GitHub.
POST /issues Create an issue.
PATCH /issues/:key Change the fields given.
PATCH /issues Change many issues at once.
POST /issues/move Move issues to another project.
DELETE /issues/:key Put an issue in the trash.

Paths here and below are relative to the base address.

GET /issues takes:

  • project: a project key. Without it, the whole workspace.
  • q: a query in the app's query language, for example state:"In Review" assignee:me label:bug -label:security updated:last-7-days. Short forms work too: #WEB @me !high +bug. Relative dates use the time zone and first day of the week from the token member's profile.
  • view: a saved view's name or id. Its query and order apply; q narrows it.
  • order: updatedAt (default, newest first), createdAt, priority, dueDate, startDate or manual. order:priority inside q does the same; the parameter wins.
  • limit: 1 to 500, default 100.

Archived and deleted issues are not listed.

sh
curl -s --compressed -G https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/issues \
  -H "Authorization: Bearer $RSVA_TOKEN" \
  --data-urlencode 'project=WEB' \
  --data-urlencode 'q=assignee:me state:"In Progress"'

Each issue has key, title, state, stateGroup, priority, labels, assignees, delegate, parent, cycle, startDate, dueDate, createdBy, createdAt, updatedAt, completedAt, archivedAt and deletedAt.

Read one

GET /issues/:key adds:

  • description, as Markdown;
  • relations: blockedBy, blocks, related, duplicateOf, duplicates, as keys;
  • links and files, each with an id;
  • branch: a branch name for the issue; a pull request from it links itself;
  • pullRequests and commits from GitHub. closing: false means the link only relates; merging it does not change the state.

An issue in the trash still reads by key, with deletedAt set.

Create

POST /issues takes project and title, and optionally state (else the project's default), priority, labels, assignees, delegate, parent, cycle, startDate, dueDate, description and force.

sh
curl -s https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/issues \
  -H "Authorization: Bearer $RSVA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project": "WEB", "title": "Fix the sign-in page on Safari", "priority": "high", "labels": ["bug"], "assignees": ["me"], "description": "Steps:\n\n1. Open the page\n2. ..."}'

The answer is 201 with key and similar: up to five open issues in the workspace whose titles look like this one (score 0.35 or more, best first), each with key, title, state and score. A match in another project counts at 0.8 of its score.

If the best score is 0.75 or more, nothing is created. The answer is 409:

json
{"error": "similar", "message": "looks like WEB-9 \"Sign-in page broken on Safari\" (0.91); send force: true to create it anyway", "similar": [...]}

Send the same request with "force": true to create it anyway.

Change

PATCH /issues/:key changes only the fields sent, by the same names as create:

  • labels and assignees replace the whole list.
  • parent: null, delegate: null, cycle: null clear them. A completed cycle takes no new issues.
  • description replaces the whole description; "" clears it.
  • archived: true archives (completed and cancelled issues only); false restores.
  • deleted: true puts it in the trash; false restores it. An issue in the trash takes no other change until it is restored.
  • project moves it to another project. state, labels and cycle sent with it are names in the new project. Left out, the server picks the state of the same name, else of the same group, else the default; keeps project labels of the same name and drops the rest; keeps workspace labels; clears the cycle. The answer has the new key and the old one as was.
sh
curl -s -X PATCH https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/issues/WEB-12 \
  -H "Authorization: Bearer $RSVA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": "In Review", "delegate": null}'

Change many

PATCH /issues takes keys (up to 500) and the same fields, except project. It also takes addLabels, removeLabels, addAssignees and removeAssignees, which change each issue's own list. They cannot be combined with labels or assignees. Names resolve in each issue's own project. Rights are checked on every change before anything is written: one refused change refuses the whole request. The answer has changed, the number of issues that changed.

sh
curl -s -X PATCH https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/issues \
  -H "Authorization: Bearer $RSVA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["WEB-1", "WEB-3"], "state": "Done", "addLabels": ["shipped"]}'

Move many

POST /issues/move takes issues (keys, up to 500), project, and optionally subIssues: true to move their sub-issues at any depth too. It is one change. Each issue keeps its history, comments, links, files and relations, and gets the next number in the new project. Issues already there are skipped. The answer lists moved: [{"key": "APP-1", "was": "WEB-1"}].

Trash

DELETE /issues/:key puts the issue in the project's trash, as Delete does in the app. Only the issue's creator or an admin may. The server deletes it for good after 30 days in the trash. Deleting it for good sooner is done by a person in the app; no token can.

Method and path Purpose
POST /issues/:key/relations Relate two issues.
DELETE /issues/:key/relations/:other Remove the relation between the two.
POST /issues/:key/links Add a link.
DELETE /issues/:key/links/:id Remove a link.
PUT /files/<workspace>/<sha256> Upload a file (no /api/v1).
GET, HEAD /files/<workspace>/<sha256> Download a file, or check that it exists.
POST /issues/:key/files Attach an uploaded file.
DELETE /issues/:key/files/:id Remove a file from the issue.

Relations. Send {"type": "blocks", "issue": "WEB-3"}. type is blockedBy, blocks, related, duplicateOf or duplicates. A pair of issues has one relation: a new one replaces the old. An issue cannot relate to itself, to one in the trash, or to one in another workspace.

Links. Send {"url": "https://...", "title": "..."}; the title is optional. Only http and https, up to 2,048 characters. GitHub pull requests and commits are recognised by their address. The answer is 201 with the link's id.

Files. Upload first, then attach:

sh
SHA=$(shasum -a 256 report.pdf | cut -d' ' -f1)

curl -s -X PUT https://app.rsva.dev/files/$RSVA_WS/$SHA \
  -H "Authorization: Bearer $RSVA_TOKEN" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

curl -s https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/issues/WEB-12/files \
  -H "Authorization: Bearer $RSVA_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"sha256\": \"$SHA\", \"name\": \"report.pdf\"}"
  • The upload's address is the SHA-256 of the bytes, in hex, and it needs a Content-Length. It answers 201 when stored, 200 when the workspace already has that file (the bytes are not read again), 400 hash_mismatch when the bytes hash to something else, 413 when too large.
  • Uploading needs Issues or Comments write access. To anyone outside the workspace the address answers 404.
  • Attaching an unknown sha256 is 400 bad_ref. The answer is 201 with the file's id.
  • Removing a file from an issue keeps the bytes: an image in a description or comment may still show them.
  • On download, ?name= sets the file name. Images open in the browser; other files download.

Comments

Method and path Purpose
GET /issues/:key/comments The issue's comments, a page at a time.
POST /issues/:key/comments Add a comment, or a reply with parentId.
PATCH /issues/:key/comments/:id Replace the text of your own comment.
DELETE /issues/:key/comments/:id Delete your own comment.
sh
curl -s https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/issues/WEB-12/comments \
  -H "Authorization: Bearer $RSVA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "Fixed in the branch. [@Sam](mention:sam@example.com), can you check?"}'

A comment reads as id, parentId, author (email), body (Markdown), createdAt, editedAt, and via (telegram or email) when it was written there. Deleted comments are left out of the list. A deleted comment's replies stay in their thread. Another member's comment is 403; one from another issue is 404. A comment mentions at most 50 people.

Inbox

Method and path Purpose
GET /inbox The token member's inbox. ?all=1 includes snoozed lines.
POST /inbox Mark lines read, unread or archived.

The answer is {"unread": 3, "lines": [...]}, newest first, one line per issue: key, title, state, stateGroup, kind (assigned, review, approved, state, mention, reply or comment), kinds, count, by (email), at, unread and snoozedUntil. unread counts what the app's badge counts. An agent's token reads the agent's own inbox.

Marks take one action per request: {"read": ["WEB-12"]}, {"unread": [...]} or {"archive": [...]}. "all" instead of a list means every line that is not snoozed. They show in the person's open tabs at once. A key with no line is 400 bad_ref; a read-only token is 403.

sh
curl -s https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/inbox \
  -H "Authorization: Bearer $RSVA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"read": "all"}'

Cycles

All cycle paths but create take ?project=KEY. :cycle is the short form (C12) or the name, URL-encoded.

Method and path Purpose
GET /cycles?project=KEY The project's cycles in time order.
GET /cycles/:cycle?project=KEY One cycle.
POST /cycles Create a cycle.
PATCH /cycles/:cycle?project=KEY Change name, description, dates or lead.
POST /cycles/:cycle/complete?project=KEY Complete it and move its open issues.
DELETE /cycles/:cycle?project=KEY Take every issue out and delete it.
  • A cycle reads as name, short, status (draft, upcoming, active, ended or completed), startDate, endDate, description, lead, issues, done, open and completedAt. A cycle's issues are GET /issues?project=KEY&q=cycle:C12 (also cycle:active, cycle:next, cycle:none).
  • Create takes project, name, and optionally startDate and endDate (both or neither; neither makes a draft), description and lead. Overlapping dates are 409 conflict. The answer has short, name and id.
  • In a change, null dates make it a draft again and lead: null clears the lead. A completed cycle's dates do not change.
  • Complete needs moveTo: a cycle ahead by name, "next", or null for no cycle. keep lists keys of open issues that stay in the completed cycle. The answer has moved and kept. A draft or a cycle that has not started cannot be completed.
  • Delete answers moved. A completed cycle cannot be deleted.

Projects, states and labels

These change the workspace's setup. A member, and so an agent, changes labels, states or projects only where an admin opened them to members (details).

Method and path Purpose
GET /projects Projects by key, archived ones too.
GET /projects/:key A project with its states and labels.
POST /projects Create a project with the default states.
PATCH /projects/:key Change name, key, color, archived or rollover.
GET /states?project=KEY The project's states in the app's order.
POST /states Create a state.
PATCH /states/:name?project=KEY Rename, regroup, place or make default.
DELETE /states/:name?project=KEY&moveTo=Name Delete a state, moving its issues.
GET /labels?project=KEY Labels the project's issues can use, as a tree.
POST /labels Create a label.
PATCH /labels/:name?project=KEY Change name, color or parent.
DELETE /labels/:name?project=KEY Take a label off every issue and delete it.
  • A project reads as key, name, color, formerKeys, archivedAt and rollover. Create takes key, name and optionally color; its states are Backlog (the default), Todo, In Progress, Done and Cancelled. A key another project has is 409, and so is a key another project had before, while that project still has issues. A new key in a change keeps the old one as an alias. rollover: true completes each cycle by itself once it is over and moves its open issues to the next.
  • Project and workspace colors: ink, slate, signal, umber, ochre, olive, forest, teal, cobalt, indigo, plum, rose, or null.
  • A state reads as name, group (backlog, unstarted, started, completed or cancelled), default, onlyPeople and issues. Create takes project, name, group, and optionally before or after a state of the same group. default: true makes a state the default; default: false is refused, as a default is replaced, not turned off. Delete needs moveTo when the state has issues or is the default.
  • A label reads as name, color, parent, depth, workspace (true for a label of the whole workspace), onlyPeople and issues. Create takes project, name, and optionally color (#rrggbb, or red, orange, amber, green, teal, blue, indigo, purple, pink, brown, gray, slate) and parent. A taken name, in any case, is 409. Delete answers removedFrom; labels inside it move up a level.
  • The Only people switch is not changed through the API.

Workspace, members and views

Method and path Purpose
GET /workspace The workspace and who the token belongs to.
PATCH /workspace Change name or color. Admins only.
GET /members People and agents: email, name, kind, role. Read only.
GET /views Saved views the token member sees: name, id, query, layout, shared, mine.

Members, roles, invites and tokens are not changed through a token.