# Publishing a Specification

Services publish their API specification to SelfDocHub with one HTTP call, usually from a CI pipeline. This page explains the request, the token, branches and what happens to a published document.

## Prerequisites

- A registered service and its upload token. An administrator creates the service in the UI (see [Services and Groups](/documentation/services-and-groups)) or with `--register-service` (see [CLI Reference](/documentation/cli-reference)). The raw token is shown exactly once, at creation or rotation. Only a salted hash is stored.

## The request

Send the document itself as the request body, not wrapped in any envelope:

```bash
curl -X POST https://docs.example.com/api/v1/services/billing-api/spec \
  -H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @openapi.json
```

> **Warning:** Use `--data-binary`, not `-d`. When reading from a file, `-d` strips newlines and silently corrupts a multi-line YAML or GraphQL body into one invalid line.

The service token authenticates the call. It is separate from user sessions and cannot be used to sign in. A token can be rotated by an administrator, and the old one stops working.

## Supported formats

The format is detected from the document itself and accepted as JSON or YAML where applicable:

| Format | Detected by |
|--------|-------------|
| OpenAPI 3 / Swagger 2 | root `openapi` or `swagger` field |
| OpenRPC | root `openrpc` field |
| AsyncAPI | root `asyncapi` field |
| GraphQL | SDL text, or JSON with a top-level `__schema` |

The format is locked from the service's first published version. Publishing a different format to the same service later is rejected with `400`. See also [GraphQL Schemas](/documentation/graphql-schemas), [OpenRPC](/documentation/openrpc) and [AsyncAPI](/documentation/asyncapi).

## Service name and description

`info.title` is required. The service display name is taken from `info.title` only while the service has no name. A name set at creation or edited by an administrator is never overwritten by a publish. The description, by contrast, follows `info.description` of every publish.

## Branches

An optional `branch` query parameter names the documentation branch of the version:

```bash
curl -X POST "https://docs.example.com/api/v1/services/billing-api/spec?branch=feature-x" \
  -H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
  --data-binary @openapi.json
```

It defaults to `main`. A version becomes the service's current one automatically only when its branch equals the service's **main branch** setting (itself defaulting to `main`, editable in the service dialog). Publishing to another branch never changes what everyone else sees. See [Versions and Branches](/documentation/versions-and-branches).

## What happens on publish

1. The token is validated and the document gets a basic shape check.
2. An immutable copy of the document is stored as a new version.
3. For the main branch, SelfDocHub computes the [Change Log](/documentation/change-log) against the previous version and makes the new version current.
4. The merged documents and navigation are rebuilt.
5. A [notification](/documentation/notifications) is sent if a rule matches.

Re-publishing identical content on the main branch answers `200 OK` and creates no new version. On any other branch every publish creates a new version. Old versions beyond `history_depth` are removed (`10` per branch by default).

## Limits

- The document size is limited by `max_spec_bytes` (10 MiB by default). If you use Nginx, raise `client_max_body_size` accordingly.
- The license may limit the number of operations, methods or fields per service. A publish over the limit is rejected before anything is saved. See [License and Tiers](/documentation/license).

## Next steps

- [Importing Versions](/documentation/importing-versions)
- [Versions and Branches](/documentation/versions-and-branches)
- [API Reference](/documentation/api-reference)

---
Source: https://selfdochub.com/documentation/publishing-specifications
