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.
GET /api/csrfand keep the session cookie it sets. It answers{"headerName": "X-CSRF-TOKEN", "parameterName": "_csrf", "token"}.- Send the token in that header with every
POST,PUT, andDELETE, for examplePOST /api/registrations. - Sign in through
POST /loginwithemailandpasswordform fields and the token. It answers with a redirect, never JSON: to/when it worked, and to/login?errorwhen it did not. - 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. - Read the signed-in identity from
GET /api/session.
With curl and jq:
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"

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:
{
"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.
| Status | Codes that can come from any endpoint |
|---|---|
400 | validation_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) |
401 | authentication_required (no session) |
403 | access_denied (an administrator endpoint, or a missing or stale CSRF token) |
404 | not_found (no such address) |
405 | method_not_allowed (the address does not take that method) |
415 | unsupported_media_type (the address does not read a body of that type) |
500 | internal_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
Projects and sources — Sources
Changes — Changes and review
Releases and notes — Release notes
Automation — Automation
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 path | Proof | Guide |
|---|---|---|
POST /webhooks/github/{webhookId} | X-Hub-Signature-256 | Sources |
POST /webhooks/gitlab/{webhookId} | Standard Webhooks headers or X-Gitlab-Token | Sources |
POST /webhooks/linear/{webhookId} | Linear-Signature, delivery, stamp, and workspace | Sources |
POST /webhooks/automation/{webhookId} | X-ReleaseFlow-Signature-256 | Automation |
GET /webhooks/automation/{webhookId}/runs/{runId} | X-ReleaseFlow-Signature-256 | Automation |
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
| Area | Status | Codes |
|---|---|---|
| Account | 400 | output_language_invalid, ui_locale_invalid, invitation_invalid, organization_slug_invalid |
| Account | 404 | invitation_not_found, member_not_found |
| Account | 409 | email_already_registered, invitation_already_pending, invitation_email_unavailable, organization_slug_taken, member_last_administrator |
| Sources | 400 | gitlab_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 |
| Sources | 404 | project_not_found, source_not_found |
| Sources | 409 | github_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 |
| Sources | 503 | github_unavailable, gitlab_unavailable, jira_unavailable |
| Webhooks | 400 | webhook_payload_malformed |
| Webhooks | 401 | webhook_signature_invalid |
| Webhooks | 413 | webhook_payload_too_large |
| Webhooks | 422 | webhook_repository_mismatch |
| Changes | 400 | invalid_change_filter, invalid_change_review, invalid_sensitive_paths |
| Changes | 404 | change_not_found, duplicate_candidate_not_found |
| Changes | 409 | change_processing, change_not_eligible_for_ai, duplicate_candidate_decided, change_excluded, change_in_release |
| Changes | 502 | ai_classification_failed |
| Changes | 503 | ai_classification_unavailable |
| Categories | 404 | category_not_found, category_suggestion_not_found |
| Categories | 409 | category_code_taken, category_system, category_suggestion_decided |
| Audiences | 400 | template_invalid, template_narratives_path, template_language_not_targeted, invalid_release_languages |
| Audiences | 404 | audience_not_found |
| Audiences | 409 | audience_code_taken, audience_limit, audience_last, audience_last_active, audience_already_retired, audience_not_retired, audience_in_use, audience_not_preset |
| Glossary | 404 | glossary_term_not_found |
| Glossary | 409 | glossary_term_taken, glossary_limit |
| Releases | 400 | invalid_release_schedule, invalid_upgrade_guide_url, invalid_previous_release, invalid_fold_decision |
| Releases | 404 | release_not_found, release_note_not_found, folding_suggestion_not_found, linked_issue_not_found |
| Releases | 409 | release_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 |
| Automation | 400, 404, 409 | See Automation |