openapi — OpenAPI 3 spec and discovery endpoints

cyoda-go version 0.6.2

openapi

NAME

openapi — OpenAPI 3.1 specification and discovery endpoints for the cyoda-go REST API.

SYNOPSIS

GET /openapi.json
GET /docs
GET {CYODA_CONTEXT_PATH}/help
GET {CYODA_CONTEXT_PATH}/help/{topic}

Discovery endpoints are served at the root of the HTTP listener (port CYODA_HTTP_PORT, default 8080). They are mounted outside CYODA_CONTEXT_PATH — no prefix is applied.

DESCRIPTION

cyoda-go generates its OpenAPI 3.1 specification from the embedded api/openapi.yaml file compiled into the binary at build time. The spec is served at /openapi.json with runtime-patched server URLs. The Scalar API Reference UI is served at /docs and loads the spec from /openapi.json.

The /openapi.json and /docs endpoints require no authentication. The help endpoints (/help, /help/{topic}) also require no authentication.

DISCOVERY ENDPOINTS

GET /openapi.json

Returns the OpenAPI 3.1 specification as JSON. The servers array is overridden at request time to reflect the actual runtime host and CYODA_CONTEXT_PATH. The scheme (http or https) is derived from whether the incoming connection is TLS.

Response: 200 OK, application/json.

The spec itself sets info.version to "1.0" (a fixed spec version, not the binary version). The binary version is reported separately in the GET /help payload under the version field.

GET /docs

Returns an HTML page embedding the Scalar API Reference UI. The UI loads the spec from /openapi.json and provides an interactive browser. No JavaScript execution is required on the server side — the HTML page references the Scalar CDN script.

Response: 200 OK, text/html; charset=utf-8.

GET {CYODA_CONTEXT_PATH}/help

Returns the full help topic tree as JSON. The response includes the binary version string and an array of all topic descriptors.

Response: 200 OK, application/json:

{
  "schema": 1,
  "version": "dev",
  "topics": [
    {
      "topic": "quickstart",
      "title": "cyoda quickstart — minimum invocations",
      "stability": "stable",
      "tagline": "minimum commands to run a cyoda-go server.",
      "see_also": ["cli", "config"]
    }
  ]
}

GET {CYODA_CONTEXT_PATH}/help/{topic}

Returns a single help topic descriptor by dotted path. The topic path segment uses dots as separators (e.g. config.database, errors.MODEL_NOT_FOUND). Topics are resolved via the embedded help tree.

Response: 200 OK, application/json — same shape as a single element of the topics array above, with the addition of a body field containing the full Markdown content.

404 HELP_TOPIC_NOT_FOUND when the topic path does not exist. 400 BAD_REQUEST when the topic path contains disallowed characters (only A-Za-z0-9, ., _, - are allowed; no leading/trailing dots or hyphens).

SPEC SHAPE

The spec covers 67 paths across these tag groups:

Entity Management — create, update, delete, transition, and stats endpoints under /entity/
Entity Model — model import, export, lock, unlock, delete, changeLevel, and workflow under /model/
Search — snapshot and direct search under /search/
User, Account — account info and subscriptions under /account/
User, Machine — M2M client management under /clients/
Entity, Audit — audit log retrieval under /audit/
Messaging — message CRUD under /message/
IAM — OAuth token, key management, OIDC providers under /oauth/
SQL Schema — SQL schema generation and management under /sql/schema/
Platform API — stream-data operations under /platform-api/stream-data/

All paths in the spec are relative to the servers[0].url, which is set at runtime to {scheme}://{host}{CYODA_CONTEXT_PATH}. The default context path is /api, so GET /entity/{entityId} is served at http://localhost:8080/api/entity/{entityId}.

AUTHENTICATION

The spec declares one security scheme:

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authorization header: `Bearer <access_token>`

Global security is applied to all operations: security: [{bearerAuth: []}]. Discovery endpoints (/openapi.json, /docs) and help endpoints are not part of the spec and carry no security requirement.

When CYODA_IAM_MODE=mock, the server accepts requests without a token. When CYODA_IAM_MODE=jwt, a valid JWT Bearer token is required on all protected endpoints.

CONTEXT PATH

CYODA_CONTEXT_PATH (default /api) is the prefix applied to all API routes. It affects:

The servers[0].url field in the served /openapi.json response.
All route registrations for entity, model, search, audit, messaging, OAuth, and SQL endpoints.
The help route prefix ({CYODA_CONTEXT_PATH}/help and {CYODA_CONTEXT_PATH}/help/{topic}).

The discovery routes /openapi.json and /docs are always at the root — CYODA_CONTEXT_PATH does not prefix them.

Setting CYODA_CONTEXT_PATH= (empty string) mounts all routes at root with no prefix.

VERSIONING

The spec info.version field is "1.0" — a fixed spec format version. It does not track the binary version.

The binary version is injected at build time via -ldflags and reported in:

The startup banner printed to stderr.
The GET {CYODA_CONTEXT_PATH}/help JSON payload’s version field.

ERRORS

The REST API uses application/problem+json (RFC 9457 Problem Details) error responses. See errors for the canonical shape and the full error code catalogue.

Error response shape (4xx example):

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "MODEL_NOT_FOUND: model nobel-prize:1 not found",
  "instance": "/api/model/nobel-prize/1",
  "properties": {
    "errorCode": "MODEL_NOT_FOUND",
    "retryable": false
  }
}

Error response shape (5xx example):

{
  "type": "about:blank",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "SERVER_ERROR: internal error [ticket: 3fa85f64-5717-4562-b3fc-2c963f66afa6]",
  "instance": "/api/entity/abc",
  "ticket": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "properties": {
    "errorCode": "SERVER_ERROR"
  }
}

CYODA_ERROR_RESPONSE_MODE=sanitized (default) suppresses internal detail from 5xx detail fields. CYODA_ERROR_RESPONSE_MODE=verbose includes full error detail — for development environments only.

EXAMPLES

Fetch the OpenAPI spec:

curl -s http://localhost:8080/openapi.json | jq '.info'

Fetch with custom context path:

CYODA_CONTEXT_PATH=/v1 \
curl -s http://localhost:8080/openapi.json | jq '.servers'

Response:

[{"url": "http://localhost:8080/v1"}]

Open the interactive UI:

curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/docs

Fetch the full help topic tree:

curl -s http://localhost:8080/api/help | jq '.topics[].topic'

Fetch a specific help topic:

curl -s http://localhost:8080/api/help/models | jq '.title'

Fetch the spec from a Docker container:

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -e CYODA_STORAGE_BACKEND=memory \
  ghcr.io/cyoda-platform/cyoda:latest &
sleep 2
curl -s http://localhost:8080/openapi.json | jq '.paths | keys | length'

ACTION DETAILS

cyoda help openapi json — emit the embedded OpenAPI spec as JSON to stdout
cyoda help openapi yaml — emit the embedded OpenAPI spec as YAML to stdout
cyoda help openapi tags — list every tag in the spec as <slug> <canonical name> pairs (tabular, sorted by slug)
cyoda help openapi <slug> — emit a standalone OpenAPI 3.1 document scoped to the named tag; paths filtered to operations carrying that tag, components pruned to only the transitively-referenced members. Pass --format=yaml to emit YAML instead of the default JSON. Discover valid slugs via cyoda help openapi tags. Unknown slugs exit 2 with the full valid-slug list in the error.

The emitted spec is the binary’s compile-time baseline. The servers array reflects whatever is embedded at build time; the running server’s HTTP endpoint (GET /openapi.json) rewrites servers per request, but the CLI does not.

Per-tag filtering is useful for AI agents and downstream tooling that only need the slice of the API corresponding to one concern (e.g. just entity-management or just search) — the pruned spec is typically 3-5× smaller than the full spec and is still a valid standalone OpenAPI 3.1 document (every $ref resolves within its own components).

Raw formats

/help/openapi.json — full descriptor (matches GET /help/{topic} envelope)
/help/openapi.md — body only