OpenAPI specification

The v1 REST API ships with an OpenAPI 3.1 document. Generators, documentation tools, and validators can consume it without an API key.

Where to find it#

Pin the spec repository. It is the versioned artifact (JSON and YAML), updated automatically when the API on main changes:

• https://github.com/edgaze-ai/edgaze-openapi

curl -L https://raw.githubusercontent.com/edgaze-ai/edgaze-openapi/main/openapi.json \
  -o edgaze-openapi.json

Production also serves the same JSON without a key:

• https://api.edgaze.ai/v1/openapi (production, dedicated host)
• https://www.edgaze.ai/api/v1/openapi
• https://www.edgaze.ai/openapi.json

What is in the document#

• openapi: "3.1.0" and info.version: "1.0.0".
• servers points at https://api.edgaze.ai/v1.
• securitySchemes.bearerAuth is HTTP bearer. Every non-webhook operation declares security: [{ bearerAuth: [] }] and carries x-required-scopes for programmatic scope checks.
• Stable operationId values for client generation.
• Response headers include Cache-Control and Vary on every authenticated response. createRun adds rate-limit headers on 429. streamRun declares the SSE headers.
• createRun documents the Idempotency-Key header (max 255 chars) and the 409 idempotency_conflict conflict response.
• streamRun documents the Last-Event-ID resume header.
• A webhooks section describes run.completed, run.failed, run.cancelled, and webhook.test, each with the edgaze-signature HMAC verification contract.

Version resolution#

The public v1 API resolves every run to a workflow version. Different callers may use different versions of the same workflow based on their access.

POST /runs resolves the version in this order:

1. Explicit version in the request body. The caller must have access to that version. Sending an unknown or forbidden version returns 403 forbidden.
2. Pinned access. When version is omitted and the caller's access is pinned, the run uses that version. A newer release does not silently upgrade the caller.
3. Current version. When version is omitted and the caller is not pinned, the run uses the current active version.

GET /workflows/{id} surfaces three related fields so integrators can detect and reason about drift without polling every run:

• pinnedVersionId: the version this caller is pinned to via a prior purchase, or null when they follow the active version.
• activeVersionId: the workflow's current active version.
• updateAvailable: true when the caller is pinned to an older version than the active one.

Cache these values per workflow. When updateAvailable becomes true, inspect newly required inputs or output shapes before the next run. Buyers who want to use the newest version can call POST /workflows/{id}/accept-update (requires workflow:write).