Publish or update a team-scoped private API

Publishes a design-time OpenAPI spec to a team-scoped private API. Distinct from POST /api/v1/public/apis, which writes to the org-level customer-facing public registry. This endpoint is what the spec0 push CLI command targets.

If apiId is provided: update that API's metadata/spec and publish a new version.
If apiId is omitted: upsert by (org, name); create a new API when none exists.
team accepts a UUID or slug; when omitted the API lands in the org's "Unassigned APIs" team.

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.

apiId?string

Existing API id. Optional — slug-based upsert by (org, name) is preferred.

Formatuuid

name?string

API name (kebab-case). If omitted, derived from the basename of specFilePath (e.g. api/payment-api.yaml → payment-api).

Match^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$

team?string

Team UUID OR slug. When omitted, the API is placed in the org's "Unassigned APIs" team.

Match^([0-9a-fA-F-]{36}|[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)$

version?string

Explicit version tag for this publish. Accepts arbitrary strings — semver ("1.2.3"), sha-prefixed tags ("staging-abc1234"), calendar tags ("v2026-Q3"), UUIDs, etc. If omitted and semver is not set, falls through to info.version from the spec, then the 0.1.0 default. When set together with semver, version wins. See ADR-0026.

openapiSpec*string

OpenAPI document content (YAML or JSON).

environment?string

Optional target environment name (ADR-0037). When provided and a config row already exists for this API in that environment, the environment's current-version pointer is advanced to the version published by this request. When omitted, no environment pointer is touched (the API's latest spec still moves) — the default, unchanged behaviour. Publishing to an environment that has no config row yet is a no-op for the pointer.

gitSha?string

Git commit SHA of the spec file. Used as the primary change detector. If unchanged since last publish, the request is treated as a no-op.

githubRepo?string

githubBranch?string

specFilePath?string

Path to the spec file in the repository. Used to derive API name when name is omitted.

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 — version flag, then info.version from the spec, then 0.1.0. No spec parsing, no oasdiff — see ADR-0026.

Defaultfalse

releaseNotes?string

Operator-supplied changelog prose for this version. When non-blank, becomes the version's changelog_text with changelogSource = MANUAL and the async AI listener skips generation. Powers the dashboard's Edit-API form (title + description combined) and the future spec0 push --release-notes flag.

Response Body

`application/json`

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

{
  "apiId": "2500ac85-f71b-4d01-b32c-62f3af3fe2c5",
  "specRecordId": "f0de8374-0665-454e-81ee-9d4898be7f8b",
  "version": "string",
  "created": true,
  "versionCreated": true,
  "noChanges": true,
  "versionUnchanged": true,
  "versionUnchangedHint": "string",
  "apiName": "string",
  "teamName": "string",
  "orgSlug": "string",
  "registryUrl": "string",
  "governanceWarnings": [
    {
      "section": "string",
      "message": "string"
    }
  ]
}

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

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

Publish or update a team-scoped private API

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`