Publish or update a public API

First call (no publicApiId) creates a new public API. Subsequent calls with the same publicApiId update the existing one. Each call records an immutable version snapshot keyed on version.

Authorization

BearerAuth

AuthorizationBearer <token>

Bearer token. Either a Personal Access Token (pat_...) or a Service Account Token (sat_...). Issued via the Spec0 dashboard or /me/personal-access-tokens.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

publicApiId?string

Omit on first publish; required when updating a known API

Formatuuid

apiSlug?string

Required on first publish; URL-safe kebab-case

title?string

Required on first publish

description?string

visibility?Visibility

Value in"DRAFT" | "PUBLISHED" | "UNLISTED"

version?string

Explicit version tag for this publish. Accepts arbitrary strings — semver, sha-prefixed tags (e.g. "staging-abc1234"), calendar tags (e.g. "v2026-Q3"), UUIDs, etc. The registry stores what you pass; uniqueness is enforced per API. When set together with semver, version wins.

semver?boolean

If true and the previous stored version is a valid semver, increment the PATCH component atomically (1.2.3 → 1.2.4). If the previous version is not a valid semver, or this is the first publish, falls through to the resolution order — info.version from the spec, then 0.1.0. No spec parsing, no oasdiff classification — see ADR-0026.

Defaultfalse

versionBump?stringDeprecated

Deprecated. Pass semver: true instead. The server ignores this field since ADR-0026 unified version-bump semantics; it is kept in the schema so old clients sending versionBump=PATCH|MINOR continue to parse cleanly. New code should not set it.

Value in"MINOR" | "PATCH"

openapiSpec*string

Full OpenAPI spec content (YAML or JSON)

gitSha?string

Optional provenance — git commit SHA for the spec source

releaseNotes?string

Human-readable summary of changes in this version

clientName?string

Optional caller identifier — surfaced on the published version to help tell apart publishes from CI vs. local CLI vs. third-party tooling. Free-form string (e.g. "github-actions/public-api-ci", "spec0-cli/0.1.4"). Ignored when omitted; intended for observability rather than authorization.

source?string

Provenance of this public API. AUTHORED — the publishing org owns the contract. MIRRORED — an official third-party spec republished by the showcase mirror pipeline; carries origin attribution and is admission-gated by lint score at publish time. Immutable after create (differing source → 409). Omitted = keep the existing value (AUTHORED on create).

Value in"AUTHORED" | "MIRRORED"

originUrl?string

MIRRORED only — URL of the official spec document this API mirrors

originOwner?string

MIRRORED only — the company/organisation that owns the API

originLicense?string

MIRRORED only — SPDX id of the origin spec's license

originDocsUrl?string

MIRRORED only — the producer's official developer docs URL

Response Body

`application/json`

curl -X POST "https://app.spec0.io/api/v1/public/apis" \  -H "Content-Type: application/json" \  -d '{    "openapiSpec": "string"  }'

{
  "publicApiId": "6cdb160e-37b9-4802-86c1-ee5fed60dba5",
  "apiSlug": "string",
  "orgSlug": "string",
  "version": "string",
  "visibility": "string",
  "created": true,
  "versionCreated": true,
  "publicUrl": "string",
  "lintScore": 0
}

{
  "status": 0,
  "title": "string",
  "detail": "string",
  "type": "string",
  "instance": "string"
}

{
  "error": "string",
  "message": "string"
}

{
  "status": 0,
  "title": "string",
  "detail": "string",
  "type": "string",
  "instance": "string"
}

{
  "status": 0,
  "title": "string",
  "detail": "string",
  "type": "string",
  "instance": "string"
}

{
  "status": 0,
  "title": "string",
  "detail": "string",
  "type": "string",
  "instance": "string"
}

Publish or update a public API

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

402application/json

403application/json

409application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`