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.
- Create a PAT. Sign in at
/tokens. A PAT is valid for 180 days and is shown once.
- Exchange it.
POST /api/jwt/create returns a JWT.
- 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.
- Start a draft.
atr release start calls POST /api/release/create.
- 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.
- Wait for checks.
atr check wait polls GET /api/checks/ongoing/{project_key}/{version_key}. Finished doesn’t mean passed.
- Review.
atr check blockers and atr check concerns read GET /api/checks/list/{project_key}/{version_key}. Acknowledge remaining concerns when starting the vote.
- 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).
- Tabulate and resolve.
atr vote tabulate calls POST /api/vote/tabulate, then atr vote resolve calls POST /api/vote/resolve (Trusted Vote mode only).
- Record distributions if your project requires them.
atr distribution record calls POST /api/distribution/record.
- 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
API: Releases
API: Votes
API: Checks
API: Distributions
API: Keys
API: Projects and policy
API: Committees and 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
API: SBOM
API: Signatures
API: Tasks
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
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
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
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. |