A discovery API for your software center.

Search the repository index, follow incremental changes, and let users star projects from your app.

Browse and search

GET /api/v1/projects?q=terminal&fedora=44&limit=24
GET /api/v1/projects/{id}
GET /api/v1/changes?after=0&limit=100
GET /api/v1/status
GET /api/v1/ranking

Lists support category, Fedora target, ordering, and offset pagination. Changes use an increasing sequence cursor; store next_cursor after processing each page. Fetch project details for created or updated items and remove deleted items. All unknown metrics are null.

Sign in from a desktop app

Register an application and its exact redirect URIs with the COPRHub operator at coprhub@balsa.info. Public clients use Authorization Code with S256 PKCE; there is no client secret. HTTPS redirects and explicit localhost loopback redirects can be registered.

1. Generate a random state, nonce, and PKCE verifier. Hash the verifier with SHA-256 and base64url-encode it.
2. Open /oauth/authorize in the system browser with client_id, redirect_uri, response_type=code, scope, state, nonce, code_challenge, and code_challenge_method=S256.
3. Validate state on return. Exchange the code at /oauth/token with the same client_id, redirect_uri, and code_verifier.
4. Validate the ID token’s signature, issuer, audience, expiry, and nonce using the advertised JWKS.

Supported scopes: openid, profile, stars:read, stars:write. Access tokens expire after one hour. Refresh tokens are not currently issued; reauthorize when needed. ID tokens use RS256.

Stars

PUT /api/v1/projects/{id}/star
Authorization: Bearer YOUR_ACCESS_TOKEN

DELETE /api/v1/projects/{id}/star
Authorization: Bearer YOUR_ACCESS_TOKEN

GET /api/v1/me/stars
Authorization: Bearer YOUR_ACCESS_TOKEN

PUT and DELETE are idempotent. Write access requires stars:write; listing personal stars requires stars:read. Tokens can be revoked using /oauth/revoke or from account settings.

Limits and errors

Lists allow up to 60 entries; changes allow up to 500. Authentication and mutation endpoints allow 30 requests per minute per IP and return HTTP 429 with Retry-After when exceeded. Errors use a JSON error string. Public API responses allow cross-origin access without cookies; use bearer tokens in native clients.

Integrations such as Discover must implement this API flow. COPRHub does not install or modify a client integration automatically.