Skip to content
turbodog

POST /api/onprem/publish

Summary

Publishes an on-premises API documentation package by accepting repository metadata and generated documentation artifacts, returning a hosted pages URL and a unique publish ID.

Intent

Enables on-premises CI/CD pipelines to push generated API documentation artifacts (OpenAPI spec, LLM text files, MCP JSON) to a hosted documentation platform without requiring GitHub integration, supporting self-hosted or air-gapped environments.

Parameters

NameTypeRequiredDescription
repoNamestringYesThe name of the repository being published (e.g. ‘acme/my-api’).
commitShastringYesThe full or short commit SHA associated with this publish event.
llmsTxtstringYesThe contents of the llms.txt documentation file as a string.
llmsFullTxtstringYesThe contents of the full llms.txt documentation file as a string.
openApiJsonobjectYesThe OpenAPI specification as a JSON object.
mcpJsonobjectYesThe MCP (Model Context Protocol) descriptor as a JSON object.

Request example

Terminal window
curl -X POST https://maps.google.com/api/onprem/publish \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repoName": "acme/my-api",
    "commitSha": "a1b2c3d4e5f6",
    "llmsTxt": "# My API\n\nBase URL: https://api.acme.com\n",
    "llmsFullTxt": "# My API — Full Reference\n\nBase URL: https://api.acme.com\n\n## GET /users\nReturns all users.\n",
    "openApiJson": {
      "openapi": "3.0.0",
      "info": { "title": "My API", "version": "1.0.0" },
      "paths": {}
    },
    "mcpJson": {
      "name": "my-api",
      "version": "1.0.0",
      "tools": []
    }
  }'

Response example

{
  "ok": true,
  "pagesUrl": "https://acme.pages.dev/my-api",
  "publishId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Error cases

  • 401 — Authorization header is missing, not a Bearer token, or the token is not in the list of valid API keys.
  • 400 — repoName field is missing or not a string.
  • 400 — commitSha field is missing or not a string.
  • 400 — llmsTxt field is missing or not a string.
  • 400 — llmsFullTxt field is missing or not a string.
  • 400 — openApiJson field is missing or not an object.
  • 400 — mcpJson field is missing or not an object.
  • 500 — The internal publish function throws an unexpected error (e.g. storage failure, network error).

Gotchas

  • All six body fields are required — omitting any single field, even llmsTxt or llmsFullTxt as empty strings, will result in a 400 error. Empty strings are valid; missing keys are not.
  • openApiJson and mcpJson must be JSON objects (not strings). Sending them as serialized strings will trigger a 400 validation error.
  • The Bearer token is validated against a server-side allowlist (validApiKeys). Generating or rotating tokens must be done out-of-band; there is no token-issuance endpoint exposed here.
  • The publishId returned is a randomly generated UUID per request — it is not deterministic and cannot be predicted or reused to reference a previous publish.
  • A 500 response body contains the raw Error message from the internal publish function, which may expose internal implementation details; handle it defensively in client code.
  • llmsTxt and llmsFullTxt accept empty strings ("") as valid values — the check is typeof !== ‘string’, not a truthiness check — so callers must still include both keys even when content is empty.