> ## Documentation Index
> Fetch the complete documentation index at: https://docs.katalo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI reference

> Use the canonical machine-readable API contract.

The human docs explain how to integrate. The OpenAPI YAML is the canonical machine-readable contract.

<CardGroup cols={2}>
  <Card title="Local spec" icon="file-code">
    The repository copy lives at `docs/external-api-v1.openapi.yaml`.
  </Card>

  <Card title="Public download" icon="download" href="https://katalo.ai/api/v1/openapi">
    Download the currently deployed API contract.
  </Card>
</CardGroup>

## Current public endpoints

| Path                                      | Purpose                                      |
| ----------------------------------------- | -------------------------------------------- |
| `/api/v1/source-assets`                   | Create a source asset ingest job.            |
| `/api/v1/source-assets/{ingest_id}`       | Read a source asset ingest job.              |
| `/api/v1/generations`                     | Create a generation job.                     |
| `/api/v1/generations/{job_id}`            | Read a generation job.                       |
| `/api/v1/generations/{job_id}/regenerate` | Create a new job from the same source asset. |
| `/api/v1/usage/summary`                   | Read the current billing-period summary.     |
| `/api/v1/billing/events`                  | Read the API billing ledger.                 |
| `/api/v1/openapi`                         | Download the YAML spec.                      |

## Keep docs aligned

If the request or response model changes, update `docs/external-api-v1.openapi.yaml` first, then update the human guide pages that explain the integration flow.