# 14 — API contract

## Normative OpenAPI contract

`api/openapi.yaml` is the machine-readable v1 contract. Route handlers, generated clients and contract tests must conform to it. Reusable error objects belong under `components.responses`; domain payloads belong under `components.schemas`. A prose endpoint in this document is not considered implemented until it exists in the OpenAPI file and has authorization plus response-contract tests.

## Principles

- JSON over HTTPS;
- explicit version prefix when public stability is required, starting with `/api/v1`;
- OpenAPI generated or verified in CI;
- consistent error shape;
- cursor pagination for large collections;
- idempotency keys for imports, generation and sync jobs;
- ETags or version fields for mutable drafts and profiles;
- authorization at use-case boundary.

## Error shape

```json
{
  "error": {
    "code": "PLAYBOOK_VALIDATION_FAILED",
    "message": "The package contains validation errors.",
    "requestId": "req_...",
    "details": [
      {
        "path": "spec.autonomy.default",
        "rule": "within-range",
        "message": "Default autonomy must be between min and max."
      }
    ]
  }
}
```

Do not expose stack traces or upstream authorization headers.

## Playbooks

### `GET /api/v1/playbooks`

Query:

- `q`
- `category[]`
- `type[]`
- `risk[]`
- `lifecycle[]`
- `autonomy[]`
- `stack[]`
- `source[]`
- `sort`
- `cursor`
- `limit`

Returns compact search records and match explanation.

### `GET /api/v1/playbooks/{slug}`

Returns identity and latest recommended version.

### `GET /api/v1/playbooks/{slug}/versions/{version}`

Returns complete safe package projection, not internal persistence details.

### `POST /api/v1/playbook-imports`

Starts an import job from an uploaded ZIP or staged package. Multipart size limits apply.

### `POST /api/v1/playbooks/{id}/versions/{version}/publish`

Private authoring capability. Requires validated draft state and reviewer permission in future team mode.

## Repositories

### `GET /api/v1/repositories`

Lists accessible manual and connected repository records.

### `POST /api/v1/repositories`

Creates manual repository identity and initial profile revision.

### `GET /api/v1/repositories/{id}/profile`

Returns latest profile and revision metadata.

### `PUT /api/v1/repositories/{id}/profile`

Creates a new revision using optimistic concurrency.

### `POST /api/v1/repositories/{id}/snapshots`

Queues a read-only integration refresh.

### `GET /api/v1/repositories/{id}/snapshots/{snapshotId}`

Returns normalized evidence and findings subject to user permissions.

## Composition

### `POST /api/v1/compositions/preview`

Input:

```json
{
  "playbook": {"slug": "root-cause-bugfix", "version": "1.0.0"},
  "repositoryProfileRevisionId": "...",
  "workMode": "execute",
  "autonomyLevel": "verify",
  "inputs": {},
  "scopeOverrides": {}
}
```

Returns rendered preview, provenance, compatibility and lint findings. It does not create an immutable run.

### `POST /api/v1/runs`

Same logical input plus an idempotency key. Creates immutable run only when blocking findings are absent.
The guided composer also sends `X-DevRunbook-Draft-Id`; when present, the server reloads that authorized persisted draft as the authoritative source and records the relation on the generated run.

### `GET /api/v1/runs/{id}`

Returns immutable snapshots and rendered output.

### `POST /api/v1/runs/{id}/artifacts`

Input artifact type. Returns synchronous result for small Markdown or job reference for ZIP generation.

### `GET /api/v1/artifacts/{id}/download`

Authorized download response with safe content disposition.

### `POST /api/v1/run-pack-imports`

Accepts a bounded `application/zip` body and verifies archive path safety,
declared inventory, file hashes, the canonical manifest digest and the exact
embedded historical prompt digest in memory. The manifest run identity is then
matched against the caller's authorized immutable run; the archive is never
extracted and imported repository text is never executed.

## Integrations

### `GET /api/v1/integrations/gitea`

Lists safe workspace-scoped connection metadata. Secret envelopes, tokens and
authorization headers never appear in the response.

### `POST /api/v1/integrations/gitea`

Creates connection. Token is write-only.

### `POST /api/v1/integrations/gitea/{id}/test`

Tests and updates capability status.

### `GET /api/v1/integrations/gitea/{id}/repositories`

Proxies normalized paginated repository discovery; never exposes token.

### `POST /api/v1/integrations/gitea/{id}/repositories/import`

Imports one discovered identity idempotently, creates a collecting snapshot and
queues the bounded read-only snapshot job. The request contains only the opaque
external repository identity; the worker reloads all trusted integration state.

### `POST /api/v1/integrations/gitea/{id}/rotate-secret`

Replaces token and records audit event.

### `DELETE /api/v1/integrations/gitea/{id}`

Deletes/invalidates secret and detaches repositories after explicit confirmation policy.

## Jobs

### `GET /api/v1/jobs/{id}`

Returns state, stage, progress and safe error.

### `POST /api/v1/jobs/{id}/retry`

Allowed only for retryable failed jobs and authorized users.

## Health

- `GET /health/live` — process alive;
- `GET /health/ready` — required dependencies and migration state ready;
- `GET /api/v1/admin/health` — authenticated detailed component health.

## Concurrency

Mutable resources include `revision` or ETag. Updates with stale versions return `409 CONFLICT` and a safe diff or recovery instruction.

## Rate limits

At minimum:

- authentication;
- integration tests;
- repository snapshot creation;
- imports;
- composition preview bursts;
- artifact generation.

Self-hosted administrators can tune limits, but disabling all safeguards should require explicit configuration.