Publish an API

Start with Getting started for a complete hello world example. This page covers the publishing contract and Claude Code MCP setup.

Choose the destinationCopy Anchor Link

Before publishing, show and confirm these three values:

Account:    ada
API slug:   billing
Visibility: private

Use your personal account handle, or an organization handle if you are a member. The slug must be a lowercase URL slug. Set visibility to private or public explicitly on every publish. If the API already exists, visibility must match its current setting. Publishing cannot change an API's visibility; use an authorized metadata update for that.

Create a publishing tokenCopy Anchor Link

In Settings → Access tokens, select Generate new token, name it, set an expiration, and select publish:schemas. Copy the secret immediately; it will not be shown again. The token lets its owner publish schemas and read APIs, but does not grant metadata updates or bulk catalog import. Keep it out of source control and rotate or revoke it from Settings when needed.

For an organization destination, create or join the organization under Settings → Organizations first.

Publish with RESTCopy Anchor Link

Set SKMTC_TOKEN in your shell or CI secret store. Send the raw OpenAPI JSON or YAML document:

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

Replace ada, billing, and the filename with your own values. Successful publishing creates an API or a new revision. Repeating identical content does not create a duplicate revision. If the same document belongs to a different slug under that account, the request returns a conflict.

POST /v1/apis/publish requires owner, slug, and visibility every time. The older /v1/apis/upload endpoint is for catalog ingestion and still defaults a new API to public if visibility is omitted. Use /publish for your own schemas. The REST endpoint accepts files up to 50 MB.

Publish from Claude CodeCopy Anchor Link

The MCP endpoint is https://mcp.skmtc.dev/mcp. Set SKMTC_TOKEN in Claude Code's environment. Claude Code supports HTTP MCP headers and environment variable expansion; add this entry to your personal or project MCP configuration:

{
  "mcpServers": {
    "skmtc": {
      "type": "http",
      "url": "https://mcp.skmtc.dev/mcp",
      "headers": { "Authorization": "Bearer ${SKMTC_TOKEN}" }
    }
  }
}

The publish_schema tool creates an API or publishes a revision. The publish_revision tool checks that an existing API has the visibility you specified. Both require the account, slug, visibility, complete schema text, and confirm: true. Ask Claude to show you the destination and get your approval before using either tool. MCP accepts schema text up to 1 MB; use REST for larger files.

The confirm field does not independently prove human approval. Use Claude Code's tool permissions to require interactive approval for publishing. MCP publishing currently uses personal access tokens; OAuth sign-in is not yet available. Keep the literal token out of MCP configuration files and source control.

For automated publishing, see Publish from CI.