Skip to main content

REST API

The REST API does everything the pages do, through the same application services. This page covers the conventions and lists every endpoint; each guide linked below describes its endpoints' bodies and behavior in full.

Sessions and CSRF​

REST clients use the same session and CSRF policy as the server-rendered pages. Every write needs a CSRF token, and CSRF protection is never turned off: the only paths excused are the signed webhook endpoints under /webhooks/, which carry no cookie and prove themselves with an HMAC over the request instead. See ADR-0023.

There are no API tokens: a script signs in as a person, with that person's email and password, and keeps the session cookie.

  1. GET /api/csrf and keep the session cookie it sets. It answers {"headerName": "X-CSRF-TOKEN", "parameterName": "_csrf", "token"}.
  2. Send the token in that header with every POST, PUT, and DELETE, for example POST /api/registrations.
  3. Sign in through POST /login with email and password form fields and the token. It answers with a redirect, never JSON: to / when it worked, and to /login?error when it did not.
  4. Fetch a new token. Signing in replaces the session and its token, so the token from step 1 is now refused with 403 access_denied.
  5. Read the signed-in identity from GET /api/session.

With curl and jq:

bash
BASE=http://localhost:8080
JAR=$(mktemp)
csrf() { curl -s -c "$JAR" -b "$JAR" "$BASE/api/csrf" | jq -r .token; }

curl -s -c "$JAR" -b "$JAR" -o /dev/null -w '%{redirect_url}\n' \
-H "X-CSRF-TOKEN: $(csrf)" \
--data-urlencode "email=$RELEASEFLOW_EMAIL" \
--data-urlencode "password=$RELEASEFLOW_PASSWORD" \
"$BASE/login" # prints $BASE/ when it worked, $BASE/login?error otherwise

TOKEN=$(csrf) # the signed-in session's token
curl -s -b "$JAR" "$BASE/api/session"
curl -s -b "$JAR" -c "$JAR" -H "X-CSRF-TOKEN: $TOKEN" \
-H 'Content-Type: application/json' -d '{"name": "Website"}' "$BASE/api/projects"

Running the commands above against a deployment: a CSRF token, signing in, the session, and a new Project

A session ends after 30 minutes without a request, when the application restarts, and on its next request once the person's role changes or they are removed; after that, every call answers 401 authentication_required until the script signs in again. POST /logout ends it at once. Set RELEASEFLOW_SESSION_COOKIE_SECURE=true whenever the application is served over HTTPS.

The Organization always comes from the signed-in person, never from a request body. A resource of another Organization is reported as not found, never as forbidden.

Errors​

Every failure under /api is application/problem+json with a stable code:

json
{
"title": "Release not found",
"status": 404,
"detail": "…",
"code": "release_not_found"
}

title and detail are written in the reader's interface language; code never changes, so match on it. A validation failure adds errors, a map from field to message.

StatusCodes that can come from any endpoint
400validation_failed (a field is missing or out of range), malformed_request (the body cannot be read), invalid_parameter (a path or query parameter is missing or does not convert, such as an ID that is not a UUID)
401authentication_required (no session)
403access_denied (an administrator endpoint, or a missing or stale CSRF token)
404not_found (no such address)
405method_not_allowed (the address does not take that method)
415unsupported_media_type (the address does not read a body of that type)
500internal_error (a fault ReleaseFlow did not foresee; the body never carries the exception behind it)

A status no endpoint gives itself, such as a 4xx from the server container, is request_failed.

Stability​

ReleaseFlow has not published a release yet. Versions follow Semantic Versioning, and an incompatible change to an endpoint is recorded as a BREAKING CHANGE that raises the major version (see Releasing). An error's code never changes. A minor release only adds to a response: a new field goes beside the one clients already read rather than changing its shape. A change, for example, keeps audienceNarratives as a map from audience code to narrative text, and audienceNarrativeDetails beside it gives each narrative's relevance, headline, and body (What each audience reads); Edit summary accepts either shape in narratives. Likewise a release gained glossaries, and each note glossaryStatus and glossaryReason, beside the fields it already had (Glossary). A change gained security, a release upgradeGuideUrl, previousReleaseId, and previousVersion, and an audience footerTemplateBody and footerTemplateVariants; a request that leaves one of their fields out keeps working as before (Footer). The API has no version prefix and no OpenAPI document; this page and the guides are its description. Only GET /api/automation/runs is paged; every other list, the Change Inbox included, returns everything at once.

Endpoints​

Roles: public needs no session; member needs any signed-in person; admin needs an administrator.

Account and Organization — Workspace​

Method and pathRole
GET /api/statuspublic
GET /api/csrfpublic
POST /api/registrationspublic
GET /api/sessionmember
GET /api/me/ui-locale, PUT /api/me/ui-localemember
GET /api/organization/output-languagemember
PUT /api/organization/output-languageadmin
GET /api/organization/slugmember
PUT /api/organization/slugadmin
GET /api/members, GET /api/members/changesadmin
PUT /api/members/{memberId}/role, DELETE /api/members/{memberId}admin
GET /api/invitations, POST /api/invitationsadmin
POST /api/invitations/{invitationId}/reissueadmin
DELETE /api/invitations/{invitationId}admin
POST /api/public/invitations/inspect, POST /api/public/invitations/acceptpublic

Projects and sources — Sources​

Method and pathRole
GET /api/projects, POST /api/projectsmember
GET /api/projects/{projectId}/sources, GET /api/projects/{projectId}/sources/{sourceId}member
POST /api/projects/{projectId}/sourcesadmin
PUT /api/projects/{projectId}/sources/{sourceId}/tokenadmin
POST /api/projects/{projectId}/sources/{sourceId}/webhook-secret, PUT /api/projects/{projectId}/sources/{sourceId}/webhook-secretadmin
POST /api/projects/{projectId}/sources/{sourceId}/disconnect, POST /api/projects/{projectId}/sources/{sourceId}/reconnectadmin
GET /api/projects/{projectId}/importsmember
POST /api/projects/{projectId}/sources/{sourceId}/importsadmin
POST /api/projects/{projectId}/sources/{sourceId}/imports/resumeadmin

Changes — Changes and review​

Method and pathRole
GET /api/projects/{projectId}/changesmember
POST /api/projects/{projectId}/changes/{changeId}/reviewmember
POST /api/projects/{projectId}/changes/{changeId}/exclusionadmin
DELETE /api/projects/{projectId}/changes/{changeId}/exclusionadmin
POST /api/projects/{projectId}/changes/{changeId}/ai-classificationmember
POST /api/projects/{projectId}/changes/{changeId}/missing-narrativesmember
GET /api/projects/{projectId}/duplicate-candidatesmember
POST /api/projects/{projectId}/duplicate-candidates/{candidateId}/decisionmember
GET /api/projects/{projectId}/sensitive-pathsmember
PUT /api/projects/{projectId}/sensitive-pathsadmin
GET /api/projects/{projectId}/contextmember
PUT /api/projects/{projectId}/contextadmin
GET /api/categoriesmember
POST /api/categoriesadmin
PUT /api/categories/{categoryId}, DELETE /api/categories/{categoryId}admin
POST /api/categories/{categoryId}/unarchiveadmin
GET /api/category-suggestionsadmin
POST /api/category-suggestions/{suggestionId}/decisionadmin

Releases and notes — Release notes​

Method and pathRole
GET /api/projects/{projectId}/releases, POST /api/projects/{projectId}/releasesmember
GET, PUT, DELETE /api/projects/{projectId}/releases/{releaseId}member
PUT /api/projects/{projectId}/releases/{releaseId}/schedulemember
GET /api/projects/{projectId}/releases/{releaseId}/available-changesmember
POST /api/projects/{projectId}/releases/{releaseId}/changesmember
DELETE /api/projects/{projectId}/releases/{releaseId}/changes/{changeId}member
POST /api/projects/{projectId}/releases/{releaseId}/request-reviewmember
POST /api/projects/{projectId}/releases/{releaseId}/linked-issues/acceptancemember
PUT /api/projects/{projectId}/releases/{releaseId}/folding-suggestions/{trackerChangeId}/decisionmember; EXCLUDE admin
PUT /api/projects/{projectId}/releases/{releaseId}/changes/{changeId}/decisionmember
PUT /api/projects/{projectId}/releases/{releaseId}/changes/{changeId}/summarymember
POST /api/projects/{projectId}/releases/{releaseId}/approvemember
POST /api/projects/{projectId}/releases/{releaseId}/return-to-draftmember
POST /api/projects/{projectId}/releases/{releaseId}/publishmember
POST /api/projects/{projectId}/releases/{releaseId}/translations/retrymember
GET /api/projects/{projectId}/releases/{releaseId}/note-previewsmember
GET /api/projects/{projectId}/releases/{releaseId}/notesmember
PUT /api/projects/{projectId}/releases/{releaseId}/notes/{noteId}member
GET /api/projects/{projectId}/releases/{releaseId}/notes/{noteId}/downloadmember
GET /api/projects/{projectId}/release-assignmentsmember
GET /api/audiences, POST /api/audiencesadmin
GET, PUT, DELETE /api/audiences/{audienceId}admin
PUT /api/audiences/{audienceId}/templates/{language}admin
POST /api/audiences/{audienceId}/retire, POST /api/audiences/{audienceId}/restoreadmin
POST /api/audiences/{audienceId}/reset-to-presetadmin
POST /api/audiences/previewadmin
GET /api/organization/release-languagesmember
PUT /api/organization/release-languagesadmin
GET /api/glossary, GET /api/glossary/suggestionsmember
POST /api/glossary/kept-terms, DELETE /api/glossary/kept-terms/{termId}admin
POST /api/glossary/translations, DELETE /api/glossary/translations/{translationId}admin

Automation — Automation​

Method and pathRole
GET /api/automation/rules, POST /api/automation/rulesadmin
GET, PUT, DELETE /api/automation/rules/{ruleId}admin
POST /api/automation/rules/{ruleId}/enable, POST /api/automation/rules/{ruleId}/disableadmin
POST /api/automation/rules/{ruleId}/executeadmin
POST /api/automation/rules/{ruleId}/webhook-secret/rotateadmin
POST /api/automation/rules/cron-previewadmin
GET /api/automation/runs, GET /api/automation/runs/{runId}admin
POST /api/automation/runs/{runId}/retry, POST /api/automation/runs/{runId}/canceladmin

A run's action that was skipped is SKIPPED, and its errorCode says why: audience_retired or nothing_for_audience. A skip is not an error and has no Problem Details; see Runs.

Signed webhooks​

These take no session and no CSRF token; each proves itself with its own secret. Anything else under /webhooks/ is refused.

Method and pathProofGuide
POST /webhooks/github/{webhookId}X-Hub-Signature-256Sources
POST /webhooks/gitlab/{webhookId}Standard Webhooks headers or X-Gitlab-TokenSources
POST /webhooks/linear/{webhookId}Linear-Signature, delivery, stamp, and workspaceSources
POST /webhooks/automation/{webhookId}X-ReleaseFlow-Signature-256Automation
GET /webhooks/automation/{webhookId}/runs/{runId}X-ReleaseFlow-Signature-256Automation

Public changelog​

Anonymous, GET only, and never given a session: /changelog/{slug}, /changelog/{slug}/releases/{entryId}, and /changelog/{slug}/rss.xml. See Public changelog.

Error codes by area​

AreaStatusCodes
Account400output_language_invalid, ui_locale_invalid, invitation_invalid, organization_slug_invalid
Account404invitation_not_found, member_not_found
Account409email_already_registered, invitation_already_pending, invitation_email_unavailable, organization_slug_taken, member_last_administrator
Sources400gitlab_base_url_invalid, gitlab_host_not_allowed, jira_site_invalid, github_token_rejected, gitlab_token_rejected, linear_token_rejected, jira_token_rejected, source_credential_required, source_signing_token_invalid
Sources404project_not_found, source_not_found
Sources409github_repository_already_connected, gitlab_project_already_connected, linear_team_already_connected, jira_project_already_connected, source_token_missing, source_sync_in_progress, source_import_not_supported, source_import_not_resumable, source_disconnected, source_not_disconnected, source_reconnect_required, source_has_no_webhook, source_secret_generated, source_secret_pasted
Sources503github_unavailable, gitlab_unavailable, jira_unavailable
Webhooks400webhook_payload_malformed
Webhooks401webhook_signature_invalid
Webhooks413webhook_payload_too_large
Webhooks422webhook_repository_mismatch
Changes400invalid_change_filter, invalid_change_review, invalid_sensitive_paths
Changes404change_not_found, duplicate_candidate_not_found
Changes409change_processing, change_not_eligible_for_ai, duplicate_candidate_decided, change_excluded, change_in_release
Changes502ai_classification_failed
Changes503ai_classification_unavailable
Categories404category_not_found, category_suggestion_not_found
Categories409category_code_taken, category_system, category_suggestion_decided
Audiences400template_invalid, template_narratives_path, template_language_not_targeted, invalid_release_languages
Audiences404audience_not_found
Audiences409audience_code_taken, audience_limit, audience_last, audience_last_active, audience_already_retired, audience_not_retired, audience_in_use, audience_not_preset
Glossary404glossary_term_not_found
Glossary409glossary_term_taken, glossary_limit
Releases400invalid_release_schedule, invalid_upgrade_guide_url, invalid_previous_release, invalid_fold_decision
Releases404release_not_found, release_note_not_found, folding_suggestion_not_found, linked_issue_not_found
Releases409release_status_conflict, release_published, release_empty, release_review_incomplete, change_summary_required, release_version_taken, classification_changed, change_not_releasable, change_excluded, release_note_render_failed, release_notes_missing, translations_not_ready, linked_issue_status_changed
Automation400, 404, 409See Automation