# 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:
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:
Authorization: Bearer rsva_...Make tokens in Settings › API tokens (how). The examples below use two shell variables:
export RSVA_TOKEN=rsva_... # your token
export RSVA_WS=acme # your workspace's slugCheck whose token it is and what it may change:
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-12orweb-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
mefor the token's own member.GET …/memberslists the emails. - Priority:
urgent,high,medium,lowornone(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), ormention: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,
, 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.lastSyncIdis the change's place in the workspace's log. - Answers over 1 KB are compressed when the request asks for it (
Accept-Encoding: brorgzip). 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:
{"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.
List and search
GET /issues takes:
project: a project key. Without it, the whole workspace.q: a query in the app's query language, for examplestate:"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;qnarrows it.order:updatedAt(default, newest first),createdAt,priority,dueDate,startDateormanual.order:priorityinsideqdoes the same; the parameter wins.limit: 1 to 500, default 100.
Archived and deleted issues are not listed.
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;linksandfiles, each with anid;branch: a branch name for the issue; a pull request from it links itself;pullRequestsandcommitsfrom GitHub.closing: falsemeans 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.
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:
{"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:
labelsandassigneesreplace the whole list.parent: null,delegate: null,cycle: nullclear them. A completed cycle takes no new issues.descriptionreplaces the whole description;""clears it.archived: truearchives (completed and cancelled issues only);falserestores.deleted: trueputs it in the trash;falserestores it. An issue in the trash takes no other change until it is restored.projectmoves it to another project.state,labelsandcyclesent 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 newkeyand the old one aswas.
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.
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.
Relations, links and files
| 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:
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), 400hash_mismatchwhen 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
sha256is 400bad_ref. The answer is 201 with the file'sid. - 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. |
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.
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,endedorcompleted),startDate,endDate,description,lead,issues,done,openandcompletedAt. A cycle's issues areGET /issues?project=KEY&q=cycle:C12(alsocycle:active,cycle:next,cycle:none). - Create takes
project,name, and optionallystartDateandendDate(both or neither; neither makes a draft),descriptionandlead. Overlapping dates are 409conflict. The answer hasshort,nameandid. - In a change,
nulldates make it a draft again andlead: nullclears the lead. A completed cycle's dates do not change. - Complete needs
moveTo: a cycle ahead by name,"next", ornullfor no cycle.keeplists keys of open issues that stay in the completed cycle. The answer hasmovedandkept. 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,archivedAtandrollover. Create takeskey,nameand optionallycolor; 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 newkeyin a change keeps the old one as an alias.rollover: truecompletes 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, ornull. - A state reads as
name,group(backlog,unstarted,started,completedorcancelled),default,onlyPeopleandissues. Create takesproject,name,group, and optionallybeforeoraftera state of the same group.default: truemakes a state the default;default: falseis refused, as a default is replaced, not turned off. Delete needsmoveTowhen 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),onlyPeopleandissues. Create takesproject,name, and optionallycolor(#rrggbb, orred,orange,amber,green,teal,blue,indigo,purple,pink,brown,gray,slate) andparent. A taken name, in any case, is 409. Delete answersremovedFrom; 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.