This is the staging instance of ATR, for testing only. The production server is at releases.apache.org.

7.18. API and CLI reference

Up: 7. Developer guide

Prev: 7.17. TLS security configuration

Next: 7.19. API documentation policy

Sections:

Overview

ATR is the Apache Software Foundation’s service for verifying and distributing releases. Its HTTP API is used by the atr command line client, ASF GitHub Actions and other release tooling. The project is in beta development and says it plans to avoid significant changes, but it gives no guarantees about stability or backward compatibility.

Base URL: https://releases.apache.org. All API calls require HTTPS (TLS 1.2+). Plain HTTP to the API is rejected with 421. Every API path starts with /api.

The live spec is at /api/openapi.json, and the automatically generated reference is the Swagger UI. Links to individual API methods on this page open that Swagger UI. This page reflects spec version v0.1.0.dev3675-31cdc7e3+dirty and the client at commit a07f9fe (10 Nov 2026).

Spec changes

Changes between spec v0.1.0.dev3631 and v0.1.0.dev3675-31cdc7e3+dirty.

Removed

  • POST /api/ssh-key/add. ssh-key/delete remains.
  • The manual vote mode. VoteMode is now email or trusted. policy_manual_vote is gone from the policy response and manual_vote is gone from the policy arguments.

Added

Changed

  • POST /api/release/source declares sources archive by archive. Projects with several GitHub repositories must use it.
  • The test-mode POST /api/test/archive-project now sets DORMANT rather than RETIRED.
  • POST /api/vote/resolve is refused with 403 unless the release is in Trusted Vote mode (the solr-mcp project is exempt). This comes from the source code. The spec’s description does not mention it.

Authentication

You create a long-lived Personal Access Token (PAT) once in the web UI, then exchange it for a short-lived JWT whenever you call the API.

  1. Create a PAT. Sign in at /tokens. A PAT is valid for 180 days and is shown once.
  2. Exchange it. POST /api/jwt/create returns a JWT.
  3. Call the API. Send Authorization: Bearer <jwt>. A JWT is valid for 30 minutes.

PATs can’t call the API directly. A PAT can optionally be bound to one IP address or CIDR range, and JWT issuance is refused from any other address. Never put tokens in URLs.

Get a JWT with curl

curl -sS https://releases.apache.org/api/jwt/create \
  -H 'Content-Type: application/json' \
  -d '{"asfuid": "alice", "pat": "YOUR_PAT"}'
# {"asfuid": "alice", "jwt": "eyJ..."}

Get a JWT with Python

import requests

BASE = "https://releases.apache.org"
r = requests.post(f"{BASE}/api/jwt/create",
                  json={"asfuid": "alice", "pat": "YOUR_PAT"})
r.raise_for_status()
jwt = r.json()["jwt"]

headers = {"Authorization": f"Bearer {jwt}"}
print(requests.get(f"{BASE}/api/user/info", headers=headers).json())

Get a JWT with the atr client

uv tool install "apache-trusted-releases @ git+https://github.com/apache/tooling-releases-client"
atr set asf.uid alice
atr set tokens.pat      # prompts, keeps the PAT out of shell history
atr jwt refresh         # the client renews the JWT itself afterwards

JWT details

  • Algorithm HS256, 30-minute lifetime, stateless. Verification allows two minutes of clock skew.
  • In long-running scripts, re-exchange your PAT every 30 minutes.
  • If the account is banned or removed in LDAP, its PATs are rejected.

Auth labels used in the endpoint tables

  • Bearer JWT: the endpoint declares the BearerAuth scheme in the spec.
  • System token (Bearer): /api/project/config accepts only system tokens, which are minted for trusted services by foundation administrators.
  • Trusted Publisher JWT in body: GitHub Actions workflows pass a GitHub OIDC token in the request body. These endpoints don’t declare BearerAuth.
  • GitHub workflow token: callbacks from workflows that ATR itself triggered.
  • Test mode only: available only when ATR runs in test mode.
  • PAT in body: the JWT exchange itself, which takes the PAT in the request body.
  • Public: the spec declares no security for the endpoint. Embargoed releases are still hidden from callers who can’t view them.

Release workflow

Each step gives the atr command and the API call beneath it.

  1. Start a draft. atr release start calls POST /api/release/create.
  2. Upload artifacts with .asc signature and SHA256/512 checksum. atr upload calls POST /api/release/store (raw bytes), or send JSON to POST /api/release/upload. Each upload creates a revision. Over 512 MiB, use atr rsync. Optionally record the source commit with POST /api/release/commit.
  3. Wait for checks. atr check wait polls GET /api/checks/ongoing/{project_key}/{version_key}. Finished doesn’t mean passed.
  4. Review. atr check blockers and atr check concerns read GET /api/checks/list/{project_key}/{version_key}. Acknowledge remaining concerns when starting the vote.
  5. Start the vote. atr vote start calls POST /api/vote/start. The revision is frozen once voting starts. In Trusted Vote mode, voters cast ballots with POST /api/vote/cast (no atr command for this yet).
  6. Tabulate and resolve. atr vote tabulate calls POST /api/vote/tabulate, then atr vote resolve calls POST /api/vote/resolve (Trusted Vote mode only).
  7. Record distributions if your project requires them. atr distribution record calls POST /api/distribution/record.
  8. Announce. atr announce calls POST /api/release/announce. Five attempts per hour. After this, files can’t change.

Limits and errors

Scope Limit
API requests overall 500 per hour
JWT issuance 10 per hour
Announcements 5 attempts per hour
Upload via JSON endpoint 512 MiB per file (use rsync beyond that)
  • 421: plain HTTP used on the API. Switch to HTTPS.
  • 429: rate limit exceeded. API responses include retry_after when available.
  • 403: cross-site requests and browser navigations to API routes are refused for non-GET methods. Call the API from a client, not a browser page.

The spec lists only success responses (200, 201, 202) and doesn’t describe error bodies.

API endpoints

The 63 endpoints, grouped by area. Each endpoint links to its entry in the Swagger UI, which has the parameters, request body and response schema. The last column lists the atr commands that call the endpoint. See CLI commands for the reverse view.

API: Authentication

Method Endpoint Auth Purpose CLI commands
POST /api/jwt/create PAT in body Create a JWT. atr jwt refresh

API: Releases

Method Endpoint Auth Purpose CLI commands
POST /api/release/announce Bearer JWT Announce a release. atr announce
POST /api/release/commit Bearer JWT Record the commit that the source archives in a draft were built from.
POST /api/release/create Bearer JWT Create a release. atr release start
POST /api/release/delete Bearer JWT Delete a release. atr dev delete
POST /api/release/draft/delete Bearer JWT Delete a draft release. atr draft delete
GET /api/release/get/{project_key}/{version_key} Public Get a release by project and version. atr release info atr upload atr sign atr check status
GET /api/release/manifest/{project_key}/{version_key}/{revision} Public Not described in the spec.
GET /api/release/paths/{project_key}/{version_key} Public List paths in a release by project and version. atr list
GET /api/release/paths/{project_key}/{version_key}/{revision} Public List paths in a release by project and version. atr list
GET /api/release/revisions/{project_key}/{version_key} Public List revisions by project and version. atr revisions
POST /api/release/source Bearer JWT Declare the repository and commit that source archives in a draft were built from, archive by archive.
POST /api/release/store Bearer JWT Store a file in a release, streaming the raw request body to disk. atr upload atr sign
POST /api/release/upload Bearer JWT Upload a file to a release.
GET /api/releases/list Public List releases.

API: Votes

Method Endpoint Auth Purpose CLI commands
POST /api/vote/cast Bearer JWT Cast a Trusted Vote ballot.
POST /api/vote/resolve Bearer JWT Resolve a vote. atr vote resolve
POST /api/vote/start Bearer JWT Start a vote. atr vote start
POST /api/vote/tabulate Bearer JWT Tabulate a vote. atr vote tabulate

API: Checks

Method Endpoint Auth Purpose CLI commands
GET /api/checks/list/{project_key}/{version_key} Public List checks by project and version. atr check blockers atr check concerns atr check exceptions atr check notes atr check suggestions
GET /api/checks/list/{project_key}/{version_key}/{revision} Public List checks by project, version, and revision. atr check status atr check blockers atr check concerns atr check exceptions atr check notes atr check suggestions
GET /api/checks/ongoing/{project_key}/{version_key} Public Count ongoing checks by project, version, and optionally revision. atr check wait
GET /api/checks/ongoing/{project_key}/{version_key}/{revision} Public Count ongoing checks by project, version, and optionally revision. atr check wait
POST /api/ignore/add Bearer JWT Add a check ignore. atr ignore add
POST /api/ignore/delete Bearer JWT Delete a check ignore. atr ignore delete
GET /api/ignore/list/{project_key} Public List ignores by project name. atr ignore list

API: Distributions

Method Endpoint Auth Purpose CLI commands
GET /api/distribution/list/{project_key}/{version_key} Public List recorded distributions for a release. atr distribution list
POST /api/distribution/record Bearer JWT Record a manual distribution. atr distribution record

API: Keys

Method Endpoint Auth Purpose CLI commands
POST /api/key/add Bearer JWT Add a public OpenPGP key. atr key add
POST /api/key/delete Bearer JWT Delete a public OpenPGP key. atr key delete
GET /api/key/get/{fingerprint} Public Get a public OpenPGP key by fingerprint. atr key get
POST /api/keys/upload Bearer JWT Upload a public OpenPGP KEYS file. atr key upload
GET /api/keys/user/{asf_uid} Public List public OpenPGP keys by the ASF UID of a user. atr key user
POST /api/ssh-key/delete Bearer JWT Delete an SSH key. atr ssh delete
GET /api/ssh-keys/list/{asf_uid} Public List SSH keys by ASF UID. atr ssh list

API: Projects and policy

Method Endpoint Auth Purpose CLI commands
GET /api/policy/get/{project_key} Public Get project policy by name.
POST /api/policy/update Bearer JWT Update release policy fields for a project.
POST /api/project/config System token (Bearer) Upsert a project's full configuration.
GET /api/project/get/{project_key} Public Get a project by name. atr sign
GET /api/project/releases/{project_key} Public List releases by project name. atr release list
GET /api/projects/list Public List projects.

API: Committees and users

Method Endpoint Auth Purpose CLI commands
GET /api/committee/get/{name} Public Get a committee by name.
GET /api/committee/keys/{name} Public List public OpenPGP keys by committee name. atr sign
GET /api/committee/projects/{name} Public List projects by committee name.
GET /api/committees/list Public List committees.
GET /api/user/info Bearer JWT Get information about a user.
GET /api/users/list Public List known users.

API: Catalog

Method Endpoint Auth Purpose CLI commands
GET /api/catalog/project/{project_key} Public The release catalogue for a project as JSON: every catalogued version with its artifacts, grouped into cycles for projects that use them.

API: Lifecycle events

Method Endpoint Auth Purpose CLI commands
GET /api/cle/project/{project_key} Public Generate an ECMA-428 Common Lifecycle Enumeration document covering every cycle and release of a project.
GET /api/cle/release/{project_key}/{version_key} Public Generate a CLE document filtered to a single release.

API: SBOM

Method Endpoint Auth Purpose CLI commands
POST /api/sbom/generate Bearer JWT Not described in the spec. atr sbom generate

API: Signatures

Method Endpoint Auth Purpose CLI commands
POST /api/signature/provenance Bearer JWT Get the provenance of a signature. atr verify

API: Tasks

Method Endpoint Auth Purpose CLI commands
GET /api/task/get/{task_id} Bearer JWT Not described in the spec. atr sbom generate

API: Trusted publishing

Method Endpoint Auth Purpose CLI commands
POST /api/distribute/record_from_workflow GitHub workflow token Record the result of an automated distribution from the GH tooling-actions workflow.
POST /api/distribute/ssh/register Trusted Publisher JWT in body Register an SSH key sent with a corroborating Trusted Publisher JWT, validating the requested release is in the correct phase.
POST /api/distribute/task/status GitHub workflow token Update the status of a distribution task Validates the caller is a Github workflow, triggered by ATR itself
POST /api/publisher/distribution/record Trusted Publisher JWT in body Record a distribution with a corroborating Trusted Publisher JWT.
POST /api/publisher/release/announce Trusted Publisher JWT in body Announce a release with a corroborating Trusted Publisher JWT.
POST /api/publisher/release/source Trusted Publisher JWT in body Declare the repository and commit that source archives in a draft were built from, with a corroborating Trusted Publisher JWT.
POST /api/publisher/ssh/register Trusted Publisher JWT in body Register an SSH key sent with a corroborating Trusted Publisher JWT.
POST /api/publisher/vote/resolve Trusted Publisher JWT in body Resolve a vote with a corroborating Trusted Publisher JWT.

API: Test mode

Method Endpoint Auth Purpose CLI commands
POST /api/test/activate-project Test mode only Restore a project to ACTIVE status (test mode only).
POST /api/test/archive-project Test mode only Set a project to DORMANT status, as a PMC archive does (test mode only).

CLI commands

The 55 atr commands from COMMANDS.md, each with the calls it makes, in order. Every command that talks to ATR is a thin wrapper over one or more API calls. atr download, atr sign and atr verify fetch files from outside the /api prefix, and atr rsync uses SSH. Endpoints that no command wraps can still be reached with atr api get and atr api post.

CLI: Releases

Command Description Underlying calls, in order
atr release start Start a release. POST /api/release/create Creates the draft.
atr release list List releases for a project. GET /api/project/releases/{project_key} The client warns when fewer releases are shown than exist.
atr release info Show information about a release. GET /api/release/get/{project_key}/{version_key}
atr draft delete Delete a draft release. POST /api/release/draft/delete
atr list List all files within a release. GET /api/release/paths/{project_key}/{version_key} or …/{revision} With --revision, …/{revision} is used. The client warns when the list is truncated.
atr revisions List all revisions for a release. GET /api/release/revisions/{project_key}/{version_key}
atr dev delete Delete a release. POST /api/release/delete Developer command. Deletes a release.

CLI: Files and signatures

Command Description Underlying calls, in order
atr upload Upload a file to a release. 1. GET /api/release/get/{project_key}/{version_key} Reads the latest revision number first. 2. POST /api/release/store Sends the file as raw bytes, with project, version and relpath as query parameters. 3. GET /api/release/get/{project_key}/{version_key} Only if the upload is quarantined for archive validation: polls this, then GET /api/release/revisions/{project_key}/{version_key}, until a new revision appears (60 s).
atr sign Sign a release file, optionally uploading the signature. 1. GET /download/path/{project}/{version}/{path} (outside /api) Downloads the file to sign. Signing happens locally. 2. GET /api/project/get/{project_key} With --upload: finds the project’s committee. 3. GET /api/committee/keys/{name} With --upload: checks that the signing key belongs to the committee. 4. GET /api/release/get/{project_key}/{version_key} With --upload: reads the latest revision number. 5. POST /api/release/store With --upload: uploads the .asc file, passing the revision as expected_revision.
atr download Download a file from a release. GET /download/path/{project}/{version}/{path} (outside /api) Not an API endpoint.
atr rsync Rsync a release. SSH Runs rsync over SSH (port 2222) to {asf_uid}@{host}:/{project}/{version}/. No HTTP API call.
atr verify Verify an artifact. 1. GET <artifact URL> (outside /api) Downloads the artifact and its .asc from the URLs you give, not from the ATR API. 2. POST /api/signature/provenance Sends the signature to find the matching OpenPGP key and committees. The client then verifies locally.

CLI: Checks

Command Description Underlying calls, in order
atr check status Get check status for a release revision. 1. GET /api/release/get/{project_key}/{version_key} Checks the phase. Checks only apply to release_candidate_draft. 2. GET /api/checks/list/{project_key}/{version_key}/{revision} Always called with a revision (the latest unless --revision is given).
atr check wait Wait for checks to be completed. GET /api/checks/ongoing/{project_key}/{version_key} or …/{revision} Polled until ongoing is 0. With --revision, …/{revision} is used. Defaults: --timeout 60, --interval 500 ms (minimum 500 ms).
atr check blockers Get check blockers for the latest or specified release revision. 1. GET /api/checks/list/{project_key}/{version_key} or …/{revision} Reads the check results for the latest revision, or for the one given by --revision (the …/{revision} variant). 2. Local: The client filters the results to blockers and prints them. --members/-m changes how they are grouped.
atr check concerns Get check concerns for the latest or specified release revision. 1. GET /api/checks/list/{project_key}/{version_key} or …/{revision} Reads the check results for the latest revision, or for the one given by --revision (the …/{revision} variant). 2. Local: The client filters the results to concerns and prints them. --members/-m changes how they are grouped.
atr check exceptions Get check exceptions for the latest or specified release revision. 1. GET /api/checks/list/{project_key}/{version_key} or …/{revision} Reads the check results for the latest revision, or for the one given by --revision (the …/{revision} variant). 2. Local: The client filters the results to exceptions and prints them. --members/-m changes how they are grouped.
atr check notes Get check notes for the latest or specified release revision. 1. GET /api/checks/list/{project_key}/{version_key} or …/{revision} Reads the check results for the latest revision, or for the one given by --revision (the …/{revision} variant). 2. Local: The client filters the results to notes and prints them. --members/-m changes how they are grouped.
atr check suggestions Get check suggestions for the latest or specified release revision. 1. GET /api/checks/list/{project_key}/{version_key} or …/{revision} Reads the check results for the latest revision, or for the one given by --revision (the …/{revision} variant). 2. Local: The client filters the results to suggestions and prints them. --members/-m changes how they are grouped.
atr ignore add Add a check ignore. POST /api/ignore/add
atr ignore delete Delete a check ignore. POST /api/ignore/delete
atr ignore list List check ignores. GET /api/ignore/list/{project_key}

CLI: Voting, announcing and distribution

Command Description Underlying calls, in order
atr vote start Start a vote. POST /api/vote/start
atr vote tabulate Tabulate a vote. POST /api/vote/tabulate
atr vote resolve Resolve a vote. POST /api/vote/resolve The client accepts passed or failed. The server refuses this outside Trusted Vote mode.
atr announce Announce a release. POST /api/release/announce --body or --body-file sets the email body. If neither is given, the server renders the project’s announce template.
atr distribution record DISTRIBUTION-VERSION [ARGS] POST /api/distribution/record
atr distribution list List recorded distributions for a release. GET /api/distribution/list/{project_key}/{version_key}

No atr vote cast command yet. The API has POST /api/vote/cast (Trusted Vote ballots, bearer token required), but the client at commit a07f9fe does not wrap it. Its body takes project, version, choice (+1, 0 or -1) and an optional comment. It returns success and the receipt_email_to address. Until the client adds a command, it can be called with atr api post /vote/cast --project example --version 1.0.0 --choice +1 --comment "Looks good". That command line is untested.

CLI: Keys

Command Description Underlying calls, in order
atr key add Add an OpenPGP key. POST /api/key/add Sends the key text, your asf.uid and the committees.
atr key delete Delete an OpenPGP key. POST /api/key/delete
atr key get Get an OpenPGP key. GET /api/key/get/{fingerprint}
atr key upload Upload a KEYS file. POST /api/keys/upload Uploads a KEYS file for one committee.
atr key user List OpenPGP keys for a user. GET /api/keys/user/{asf_uid}
atr ssh list List SSH keys. GET /api/ssh-keys/list/{asf_uid} Defaults to your configured asf.uid.
atr ssh delete Delete an SSH key. POST /api/ssh-key/delete

CLI: Other API-backed commands

Command Description Underlying calls, in order
atr sbom generate Generate and augment a CycloneDX SBOM for a release artifact. 1. POST /api/sbom/generate Queues a task. 2. GET /api/task/get/{task_id} With --wait: polls every 0.5 s until the task completes or fails (--timeout 600). This endpoint needs a bearer token.
atr jwt refresh Fetch a JWT using the stored PAT and store it in config. POST /api/jwt/create Exchanges your stored PAT for a JWT and stores the JWT in the config file.
atr api get GET a resource from the API. GET <any path under /api> Sends a GET with your JWT. The path is appended to /api.
atr api post POST a resource to the API. POST <any path under /api> Sends the --key value options as a JSON body, with your JWT.

CLI: Local-only commands

Command Description Underlying calls, in order
atr jwt show Show stored JWT token. Local: Shows the stored JWT.
atr jwt dump Show decoded JWT payload from stored config. Local: Decodes the stored JWT payload.
atr jwt info Show JWT payload in human-readable form. Local: Shows the JWT payload in readable form.
atr config file Display the configuration file contents. Local only.
atr config path Show the configuration file path. Local only.
atr set Set a configuration value using dot notation. Local: Sets a config value with dot notation, for example asf.uid.
atr show Show a configuration value using dot notation. Local only.
atr drop Remove a configuration key using dot notation. Local only.
atr dev env Show the environment variables. Local only.
atr dev key Return a test OpenPGP key. Local only.
atr dev pat Read a PAT from development configuration. Local only.
atr dev pwd Show the current working directory. Local only.
atr dev stamp Update version in pyproject.toml. Local only.
atr dev token Generate a random alphabetical token. Local only.
atr dev user Show the value of $USER. Local only.
atr docs Show comprehensive CLI documentation in Markdown. Local: Prints the CLI documentation in Markdown.