Service and Schema Publication Operations

Reference the request, response, and failure contracts for this operation family.

Use the configured POLICY_API base and protected POLICY_AUTH_HEADER file from authentication. All paths below are relative to that base. Examples read the bearer header from that file. Keep request payloads and logs free of credentials. Consult your deployed /doc document for complete nested schemas. Response examples illustrate relevant fields rather than every optional property.

These application programming interface (API) reads return direct payloads. Most reads return 200. Readiness and liveness return empty 204 responses. Gateway access rules can still return 401 or 403. Backend health reads do not independently certify target activation or worker completion.

GET /version

Retrieve runtime API version.

Path parameters: None.
Request body: None.
Request parameters: None.

Sample request:

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/version"

Response: Version object.

Sample response:

{
  "version": "1.1",
  "buildVersion": "1.1.0"
}

Error codes:

Possible error codes are 401, 403, and 500.

GET /doc

Retrieve OpenAPI specification as YAML. OpenAPI describes request and response schemas. YAML is the document format returned by this route.

Path parameters: None.
Request body: None.
Request parameters: None.

Sample request:

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/doc"

Response: OpenAPI YAML document.

Sample response:

openapi: 3.1.0
info:
  title: Policy Compiler API

Error codes:

Possible error codes are 401, 403, and 500.

GET /log

Retrieve current runtime log level. This operation returns the configured level, not log entries or diagnostic records.

Path parameters: None.
Request body: None.
Request parameters: None.

Sample request:

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/log"

Response: Current log level.

Sample response:

{
  "level": "info"
}

Error codes:

Possible error codes are 401, 403, and 500.

POST /log

Update runtime log level. Require policy:system-configure. This change applies to the serving process, not persistent cluster configuration.

Path parameters: None.
Request body: JSON with desired log level.
Request parameters: None.

Sample request:

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  -d '{"level":"debug"}' \
  "${POLICY_API}/log"

Response: Updated log level.

Sample response:

{
  "level": "debug"
}

Error codes:

Possible error codes are 400, 401, 403, and 500.

PUT /log

Use the compatibility method for the same process-local log update. Require policy:system-configure. Accept no path or query parameters. Send an application/json object with the required string level. Supported values include debug, info, warn, and error. The server also accepts legacy uppercase forms.

curl --fail-with-body -X PUT \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  --data '{"level":"info"}' \
  "${POLICY_API}/log"

Return 200 with {"level":"info"}. Return 400 for invalid levels, 401 or 403 for identity or capability failures, or 500 for server failures. Neither log-update method requires If-Match or an idempotency key.

GET /health

Retrieve service health status.

Path parameters: None.
Request body: None.
Request parameters: None.

Sample request:

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/health"

Response: Health status object with component checks.

Sample response:

{
  "isHealthy": true,
  "checks": [
    {
      "passed": true,
      "output": "Catalog loaded successfully",
      "componentType": "catalog",
      "componentName": "catalog"
    }
  ]
}

Error codes:

Possible error codes are 401, 403, and 503.

GET /ready

Readiness probe endpoint.

Path parameters: None.
Request body: None.
Request parameters: None.

Sample request:

curl --fail-with-body -i -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/ready"

Response: Empty body with readiness status code.

Sample response:

HTTP/1.1 204 No Content

Error codes:

Possible error codes are 401, 403, and 503.

GET /live

Liveness probe endpoint.

Path parameters: None.
Request body: None.
Request parameters: None.

Sample request:

curl --fail-with-body -i -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/live"

Response: Empty body with liveness status code.

Sample response:

HTTP/1.1 204 No Content

Error codes:

Gateway authentication or authorization failures return 401 or 403. Liveness failures return 503.

GET /openapi.json

Retrieve the generated OpenAPI schema as JavaScript Object Notation (JSON). Accept no body, path parameters, or query parameters. Apply gateway authentication as your deployment requires. Return 200 with the schema document. Gateway failures can return 401 or 403. Server failures can return 500. This automatic schema route does not appear as an operation inside its own document.

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/openapi.json"

GET /swagger

Open the browser reference for the deployed schema. Accept no body or parameters. Return 200 with Hypertext Markup Language (HTML). The page loads its schema and initializer from the same API root. Gateway failures can return 401 or 403. Rendering failures can return 500.

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/swagger"

GET /swagger/init.js

Serve the Swagger browser initializer. Accept no body or parameters. Return 200 with JavaScript. This auxiliary route supports the browser reference, not policy mutation. Gateway failures can return 401 or 403. Server failures can return 500.

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/swagger/init.js"

GET /favicon.ico

Serve the browser reference’s empty icon response. Accept no body or parameters. Return 200 with the image/x-icon media type. This auxiliary route carries no policy or health evidence. Gateway failures can return 401 or 403.

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/favicon.ico"

GET /metrics

Read service metrics in Prometheus exposition format. Require policy:observability. Accept no body or parameters. Return 200 with metric text, not a JSON response. Return 401 or 403 for identity or observability failures. Metrics collection can also encounter server failures. This route does not appear in the generated operation schema.

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/metrics"

Use metrics with operation history and automatic recompilation observations. Check authenticated catalog access separately. A successful health probe does not test every integration operation. For a failed probe, retain the status, timestamp, and safe health-check output when available. Ask the platform operator to investigate readiness or dependency failures. Wait for the operator to restore service before repeating an authoring request.

Last modified : November 03, 2026

Feedback

Was this page helpful?