API reference
codqual is a REST API. Point any HTTP client or coding agent at it with a bearer token. This page documents every endpoint an API key can reach.
Stable contract for agents
GET /issues, GET /reviews, and GET /reviews/:id are the blessed, contract-tested public surface — described by the OpenAPI spec at https://api.codqual.com/openapi.json. Other endpoints on this page work with the same key but may evolve with the dashboard.
Authentication
codqual's REST API lives at one base URL. Every request must include an API key as a bearer token in the Authorization header.
https://api.codqual.com
Authorization: Bearer cc_...Create keys in Settings → API Keys, or copy the one shown once at signup. The secret is shown only once; you can revoke a key anytime.
curl -H "Authorization: Bearer $CODQUAL_API_KEY" https://api.codqual.com/reviewsRead endpoints
Every read endpoint accepts the same bearer token. Lists come back newest-first and page with a cursor — pass the last item's cursor value to fetch the next page.
| Endpoint | Returns | Useful parameters |
|---|---|---|
GET /reviews |
Your reviews, newest first. | repo, focus, source, cursor (ISO date), limit (max 100) |
GET /reviews/:id |
One review and all of its findings. | (UUID) |
GET /issues |
Your deduplicated open-issue state (up to 500 issues). | repo, branch, status (default open), module, severity |
GET /issues/:id/timeline |
The full history of one issue — every observation, status change, and merge. | — |
GET /scans/:id |
One scan run. Poll it until run.reviewId is set — that is completion — and the same response then carries the scan and its findings. | — |
GET /repositories |
The repositories you can see. | — |
GET /repositories/:fullName |
One repository's detail and its review history. | — |
GET /repositories/:fullName/branches |
The repository's live branch list. | — |
GET /activity |
Your organization's review and scan feed. | source, cursor |
GET /maturity |
The current 25-check maturity rubric result for a repository. | repo |
GET /maturity/history |
A repository's maturity-score trend (up to 90 points). | — |
curl -H "Authorization: Bearer $CODQUAL_API_KEY" "https://api.codqual.com/issues?status=open&severity=high"The API is read-only
An API key is a read credential. It reads the results codqual has already produced — your issues, reviews, findings, scans, and maturity scores — and nothing on this page starts an analysis.
Analysis has exactly two triggers. The GitHub App reviews a pull request on every push to it. The dashboard scans a whole repository when you press Scan now, or when the weekly schedule fires.
The dashboard also owns the rest of the write surface: creating and revoking API keys, changing an issue's status, suppressing findings, and managing repositories, teams, and webhooks. Feedback on a finding goes back through the /codqual PR-comment commands.
Errors
| Status | Meaning |
|---|---|
401 |
Your API key is missing or invalid. |
404 |
Not found — or not yours. codqual returns 404 instead of 403, so it never confirms that a resource you cannot see exists. |
429 |
Rate limit reached — 120 requests per minute on the read endpoints. |
Outbound webhooks
Configure webhook endpoints in Settings → Webhooks (dashboard only). codqual POSTs review.completed and finding.created events to your HTTPS URL, each signed with an HMAC secret shown once when you create the endpoint.