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.

Creating a new public API counts against the plan's max_public_apis limit; publishing a new version of an existing one never does. At the limit, a create returns 402 with the limit, the current count and the plan.

Requires scope write:public-apis.

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

originCommitSha?string

MIRRORED only — the upstream commit this snapshot was taken from. Distinct from gitSha, which is a SHA-256 of the spec file's bytes and exists in no repository.

originCommitUrl?string

MIRRORED only — web URL for originCommitSha. Supplied by the publisher rather than derived, so the registry invents no per-host URL rules.

vendorSlug?string

Reserved for the Spec0 mirror pipeline, which republishes third-party specifications under their own vendor's slug (/registry/{vendorSlug}/{apiSlug}). Publishing into an organisation you are not a member of needs a scope that customer tokens cannot be issued with, so a token from the dashboard is refused with 403. Documented because it appears on the wire, not because it is a field to set.

vendorName?string

Display name for the vendor organisation, used only when that organisation is first created. Same reservation as vendorSlug.

vendorWebsiteUrl?string

The vendor's own website, shown on their registry organisation page. Same reservation as vendorSlug.

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,
  "lintErrorCount": 0,
  "lintWarningCount": 0
}

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

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

{
  "type": "https://spec0.io/problems/plan-limit-exceeded",
  "title": "Plan limit reached",
  "status": 402,
  "detail": "Your organisation has reached its limit of 3 mock servers.",
  "instance": "string",
  "feature": "max_mock_servers",
  "limit": 3,
  "used": 3,
  "plan": "FREE"
}

{
  "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`