# Create API docs with the REST API

Each API on [Skmtc Hub](https://skmtc.dev) has a docs page. This page tells
you how to make an API from an OpenAPI document with one request. The
response gives the address of the docs page. You do not choose an account or
a slug.

## Create a token [#create-a-token]

1. Open [Settings → Access tokens](https://skmtc.dev/settings/tokens).
2. Make a new token. Give it a name and an expiration, and select
   `publish:schemas`.
3. Copy the secret. Skmtc shows it one time only.
4. Put the secret in `SKMTC_HUB_TOKEN` in your shell.

## Send a file [#send-a-file]

Send the raw OpenAPI JSON or YAML document to `POST /v1/apis/publish`:

```sh
curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $SKMTC_HUB_TOKEN" \
  --header 'Content-Type: application/octet-stream' \
  --data-binary @openapi.yaml \
  'https://api.skmtc.dev/v1/apis/publish?visibility=private&filename=openapi.yaml'
```

The file can be up to 50 MB.

## Send a URL [#send-a-url]

When the document is on the web, send its URL to `POST /v1/apis/publish/import`.
Skmtc gets the document from that URL:

```sh
curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $SKMTC_HUB_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://example.com/openapi.json", "visibility": "private"}' \
  'https://api.skmtc.dev/v1/apis/publish/import'
```

The URL can be a direct link to the document, or a file on GitHub or GitLab.
When you send the same URL again and the document has changed, Skmtc adds a
revision to the API that it made from that URL. When the document has not
changed, the response has that API with `deduped: true`.

## Open the docs page [#open-the-docs-page]

The response has `docsUrl`, the address of the docs page of the API:

```json
{
  "api": { "slug": "billing", "visibility": "private" },
  "isNewApi": true,
  "deduped": false,
  "docsUrl": "https://skmtc.dev/ada/apis/billing"
}
```

The example shows only some of the fields of the response.

## What Skmtc chooses for you [#what-skmtc-chooses-for-you]

- **Account.** The API goes in your own account. To put it in an
  organization that you are a member of, add `owner` with the handle of the
  organization.
- **Slug.** Skmtc makes the slug from the `info.title` of the document. When
  you already have an API with that slug, Skmtc adds a number, for example
  `billing-2`. To choose the slug, add `slug`.
- **Visibility.** You must send `visibility`. Send `private` to make an API
  that only you, or the members of the organization, can see. Send `public`
  to show it to all readers.

When you send a file that has the same bytes as one of your APIs, Skmtc makes
no new API. The response has that API, with `deduped: true`. The `visibility`
that you send must be the visibility of that API. If it is not, the response
is `409`.

When you send a URL that one of your APIs already has, the response has that
API, whatever `visibility` you send. Skmtc uses `visibility` only for a new
API.

To add a revision to an API that exists, name it with `owner` and `slug`. See
[Publish an API](/docs/getting-started/publish-api).