API Reference

Human-readable reference for the current web API. Schema source of truth: packages/api-contract/src/index.ts.

Authentication

Method	Used by	Notes
Session cookie	Web app	Magic-link authentication
`Authorization: Bearer <api-key>`	Integrations and repo-local CLI workflows	Accepted on generation and download routes

API-key management and billing routes require a user session.

Generation

`GET /v1/artifacts`

Lists active artifact definitions from the default registry.

Current expected result in this repo: a single itk-batch entry.

`POST /v1/generations`

Creates a synchronous generation, persists the result, and returns generated files plus metadata.

Request body:

{
  "prompt": "Export released parts to CSV",
  "requestId": "req_123",
  "projectContext": {
    "tcVersion": "14.3",
    "compiler": "gcc",
    "codePrefix": "PNX"
  },
  "options": {
    "explicitType": "itk-batch",
    "explicitPattern": "query-export",
    "dryRun": false
  }
}

Response fields include:

files
summary
artifactType
pattern
usage
engineVersion
diagnostics
optional buildManifest

`POST /v1/generations/stream`

Starts the same generation flow over server-sent events.

Event types:

stage
result
usage
error

Current stage names:

planning
selecting-pattern
loading-kb
generating
validating
packaging

`GET /v1/generations`

Lists recent generations for the authenticated org.

`GET /v1/generations/:id`

Returns the persisted generation record for the authenticated org, including parsed files and diagnostics. If a manifest file is present in stored output, the route also exposes buildManifest.

`GET /v1/generations/:id/download`

Returns a ZIP of generated files. Supports session or Bearer API-key auth.

`GET /v1/generations/:id/archive`

Legacy alias for ZIP download. Keep it for compatibility; use /download in current docs and clients.

API Keys

`GET /v1/keys`

Lists API keys for the current org.

`POST /v1/keys`

Creates a new API key. The plaintext key is returned once at creation time.

`DELETE /v1/keys/:id`

Revokes a key by marking it inactive.

Billing

`POST /v1/checkout`

Creates a Stripe Checkout session for an allowed price id.

`POST /v1/billing-portal`

Creates a Stripe Billing Portal session for an org with an active Stripe customer id.

Request Notes

projectContext.tcVersion is required.
projectContext.compiler must be msvc or gcc.
options.explicitType and options.explicitPattern are optional hints.
options.explicitType is a string hint; options.explicitPattern must match an active itk-batch pattern.
The current registry only exposes itk-batch, so other enum values in the schema should be treated as reserved.

Rate Limits And Quotas

Generation routes enforce both:

quota checks by org tier
rate limiting by org

Rate-limit responses include:

x-ratelimit-remaining
x-ratelimit-reset
retry-after on 429

Error Semantics

400: invalid payload or missing required field
401: authentication required
403: quota or trial restriction
404: record not found
429: rate limit exceeded
500: internal generation, persistence, or provider failure