API Overview

The Codity public API lets you run reviews, scans, navigation, and automation from your own systems: CI pipelines, internal tools, bots, or scripts.

The API draws from the same monthly pools as the dashboard, CLI, and your version control integration. There is no separate API allowance. See Usage and Limits for how the pools work.

Base URL

https://api.codity.ai/v1

Authentication

Every request needs an organization-scoped API key. Create and manage keys on the API Access page in the dashboard.

Pass the key in either header:

# Preferred
curl -H "X-API-Key: $CODITY_API_KEY" https://api.codity.ai/v1/me/usage

# Also supported
curl -H "Authorization: Bearer $CODITY_API_KEY" https://api.codity.ai/v1/me/usage

Keys are tied to your organization, so usage from any key counts against the same shared pools. Treat a key like a password: store it in a secret manager or environment variable, never commit it, and revoke it from the API Access page if it is exposed.

Endpoints

Checking your usage and polling job status are always free and never draw from a pool.

How Work Is Submitted

The API is asynchronous. Submitting work returns immediately with an identifier; you then poll for the result.

1. POST to an endpoint such as /v1/review.
2. Codity validates the request and reserves one unit from the relevant pool.
3. You get back 202 Accepted with a job_id.
4. Poll GET /v1/jobs/{job_id} until status is terminal.

A successful submission looks like this:

{
  "job_id": "3f2a9c84-1b7d-4e55-9a10-6c2f8b0d4e11",
  "workflow_id": "8d41e6b2-77a3-4c19-b0f5-2e9a1c7d3f6b",
  "status": "accepted"
}

Checking Your Usage

GET /v1/me/usage returns the live state of all three pools for the current billing period. The exact limits reflect your contract.

{
  "billing_period": "2026-07",
  "reviews_scans":   { "limit": 0, "used": 0, "remaining": 0, "overage_count": 0, "overage_charges_usd": 0.0 },
  "code_navigation": { "limit": 0, "used": 0, "remaining": 0, "overage_count": 0, "overage_charges_usd": 0.0 },
  "automation":      { "limit": 0, "used": 0, "remaining": 0, "overage_count": 0, "overage_charges_usd": 0.0 },
  "total_overage_charges_usd": 0.0
}

The values above are placeholders. Your response carries your organization's real figures, matching what the dashboard shows.

Quota Headers

Every response carries your current quota state, so you can track headroom without a separate call:

Reading these is the cheapest way to keep an eye on usage inside a long-running pipeline.

Response Codes

A 429 names the exhausted pool:

{
  "detail": "Monthly public API quota exhausted for reviews_scans. Enable soft caps or increase the configured pool limit."
}

On a soft cap you will not see 429 for pool exhaustion. Work continues and the excess is recorded as overage.

Quota Behavior You Can Rely On

• Rejected requests are free. A 429, 422, or 401 never consumes a unit.
• Failed dispatch is refunded. If Codity accepts a request but cannot queue the job, the reserved unit is released.
• Retries are safe. A single logical job consumes a single unit even if it is retried internally. However, submitting the same payload twice creates two jobs and consumes two units, so deduplicate on your side if that matters.
• Polling is free. Poll GET /v1/jobs/{job_id} as often as you need.

Next Steps

See API Examples for complete, runnable requests covering reviews, scans, navigation, automation, and handling limits in CI.