# API

> What you can call programmatically today: the release gate check for CI with a workspace API key, and the public evidence pack keys. The API is limited in beta.

Source: https://aicodeops.dev/docs/api

AI CodeOps is used in the browser. During the open beta, the programmatic API is deliberately small: one endpoint for CI, plus the public keys that let anyone check an evidence pack. Everything else in the console needs a signed-in browser session and is not a supported API.

## Workspace API keys

Create a key under **Configure → API Keys**. Give it a name; the secret (it starts with `sk-`) is shown once, so copy it then. AI CodeOps stores only a hash.

- A key acts as the member who created it, with that member's current role. If the member is removed or their role loses a permission, the key loses it too.
- Owners, admins, developers and members can create keys. Viewers can't.
- Admins see every key in the workspace; others see their own.
- **Delete** revokes a key at once. Integrations using it stop working immediately.

Where your plan includes key scoping, an admin can choose **Scope** to limit a key to an IP allowlist (CIDR ranges), a rate limit per minute, an expiry date, and what it may be used for: model gateway calls, the release gate check, or both (the default).

Send the key as a Bearer token:

```http
Authorization: Bearer sk-...
```

## Release gate check

`POST /api/release/check` answers one question for your CI: may this pull request or commit ship? It applies the same checks as the [quality gates](https://aicodeops.dev/docs/quality-gates) across every session that touched the change. The key needs the `workspace:read` permission.

```bash
curl -sf -X POST "https://console.aicodeops.dev/api/release/check" \
  -H "Authorization: Bearer $WORKSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pullRequestURL":"https://github.com/acme/api/pull/42"}'
```

Use the same host you open the console on. [Release gate in CI](https://aicodeops.dev/docs/release-gate-ci) has jobs to copy for GitHub Actions, GitLab CI, Bitbucket Pipelines, and Forgejo and Gitea Actions.

### Request fields

| Field                 | Type                                                                        | Default                      |
| --------------------- | --------------------------------------------------------------------------- | ---------------------------- |
| `pullRequestURL`      | URL                                                                         | one of these two is required |
| `commitSHA`           | string, 7+ characters                                                       |                              |
| `blockingSeverity`    | `critical`, `high`, `medium`, `low`, `info`                                 | `high`                       |
| `blockOnTestFailure`  | boolean: failing tests block, and so does a code change with no test result | `true`                       |
| `blockOnBuildFailure` | boolean: a repository build that did not pass blocks                        | `true`                       |
| `minCoveragePct`      | number 0–100: a coverage floor; denies if no coverage was reported          | not gated                    |
| `requiredWorkflows`   | string array                                                                | none                         |
| `disallowedLicenses`  | string array, checked against the project SBOM                              | none                         |
| `requireDeployedTo`   | environment name, e.g. `staging`                                            | none                         |
| `blockOnInFlight`     | boolean: deny while a run is still going                                    | `false`                      |
| `lookbackMs`          | how far back to look, in milliseconds                                       | 14 days                      |
| `workspaceID`         | workspace id: only when you call with a console session                     | the API key's workspace      |

`GET /api/release/check` accepts the same names as query parameters (lists comma-separated).

**Test evidence.** With `blockOnTestFailure` on, which is the default, every session that changed code in a project needs a test result with counts. If no test ran for it, or the test command ran but reported no test counts, the check denies: "The test command ran but reported no test counts, so nothing shows a test passed. Check the project's test command". No evidence is not a pass. For a project with no test suite, turn on **Don't run tests for this project** in the project's settings under **Plan → Projects**; the check then asks for no test result. The rule also doesn't apply to a session that changed no code, or when you send `"blockOnTestFailure": false`.

**Coverage floor.** With `minCoveragePct` set, the most recent test run that reported coverage must meet it. If no test run on the change reported coverage, the check denies: "Coverage wasn't reported, so the 80% floor can't be checked". A floor that can't be checked does not pass. Make the project's test command print a coverage summary before you set a floor. Leave `minCoveragePct` out and coverage is not gated.

**Calling with a console session.** An API key carries its workspace, so CI sends no `workspaceID`. A signed-in console session can call the endpoint too, and it must name the workspace: add `?workspaceID=<id>` to the URL, or put `workspaceID` in the JSON body of a `POST`. Without it the answer is `400`. The id is the part after `/workspace/` in the console's address.

### Response

The endpoint returns `200` for both outcomes. Read `allowed`:

- `allowed`: `true` or `false`
- `summary` and `reasons`: plain-English explanations
- `blockingFindings`, `testFailures`, `testEvidenceMissing`, `coverageShortfall`, `coverageNotReported`, `licenseViolations`, `licenseEvidenceMissing`: the details behind a deny (`licenseEvidenceMissing` lists projects with no SBOM to check when you pass `disallowedLicenses`)
- `testEvidenceMissing`: one `{ "workflowRunID", "reason" }` for each session that changed code and has no test result with counts; an empty list when nothing is missing
- `coverageNotReported`: `{ "required": 80 }` when you set a floor and no test run reported coverage; `null` when a coverage number exists or no floor is set
- `runsConsidered`: the sessions the verdict was based on

A change with no matching sessions is denied ("No workflow runs found for …"). So is a code change with no test result, as described under Test evidence above. If the evaluation fails, you get `allowed: false` with the summary "Evaluation failed", so a broken check never passes a change.

### Errors

| Status | Meaning                                                                                                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | Invalid JSON or invalid fields. With a console session: `workspaceID` is missing, and the message says so                                               |
| 401    | No API key and no console session, or the key isn't valid                                                                                               |
| 403    | The key's scope or its creator's role doesn't allow this, or the key belongs to another workspace. With a session: you aren't a member of the workspace |
| 429    | More than 60 checks a minute for the workspace; see `Retry-After`                                                                                       |

The same check is in the console under **Review & Gate → Release gate**, with a CI job to copy.

## Evidence pack keys

`GET /api/evidence?action=keys` is public and needs no key. It returns the Ed25519 public keys that sign [evidence packs](https://aicodeops.dev/docs/evidence-packs), so you can verify a pack offline. Downloading a pack needs a signed-in member with audit access; it is not available with an API key.

## API reference

One page per endpoint, generated from the [OpenAPI spec](https://aicodeops.dev/docs/api/openapi.json):

- [Check whether a pull request or commit may ship](https://aicodeops.dev/docs/api/release-check)
- [The keys that sign evidence packs](https://aicodeops.dev/docs/api/evidence-keys)
- [Verify an evidence pack](https://aicodeops.dev/docs/api/evidence-verify)
- [Liveness and readiness](https://aicodeops.dev/docs/api/health)
- [Component status](https://aicodeops.dev/docs/api/status)

## Next steps

- [Release gate in CI](https://aicodeops.dev/docs/release-gate-ci)
- [Quality gates](https://aicodeops.dev/docs/quality-gates)
- [Members and roles](https://aicodeops.dev/docs/members)
- [Troubleshooting](https://aicodeops.dev/docs/troubleshooting)

## Frequently asked questions

### Is there a full REST API for sessions and projects?

Not yet. During the open beta the console is the way to run sessions and manage projects. The endpoints on this page are the ones that accept programmatic access.

### Do API keys expire?

Not by default. A key works until it is deleted, its creator leaves the workspace, or an expiry date set in its scope passes.
