Observability settings API reference

These routes read and write the observability settings of a CosmicAC deployment. The settings hold the base URLs of the Prometheus and Loki that CosmicAC queries. Each route lists its request, response, and errors.

In every path, <cosmicac-url> is the base URL of your deployment. Caddy serves these routes under /api and proxies them to cosmicac-app-node.

To set the same values from the web interface, see Connect CosmicAC to your Prometheus and Loki.

Endpoints

Authentication

Every route requires an administrator account. CosmicAC reads the session token from the ttr-token header.

ttr-token: <session-token>

CosmicAC binds a token to the IP address that requested it, and rejects that token from any other host.

Get observability settings

Returns the Prometheus and Loki URLs the deployment stores.

HTTP request

GET <cosmicac-url>/api/v1/observability-settings

Response

{
  "prometheus_url": "http://prometheus:9090",
  "loki_url": "http://loki:3100"
}

A field that you clear with an empty string returns "" rather than null.

Errors

Failed requests return the status text and a message.

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "ERR_PERMISSION_REQUIRED"
}

The route returns these status codes.

Update observability settings

Sets the Prometheus URL, the Loki URL, or both. CosmicAC stores the values, then pushes both settings to cosmicac-wrk-monitor.

HTTP request

PUT <cosmicac-url>/api/v1/observability-settings

Request body

{
  "prometheus_url": "http://prometheus:9090",
  "loki_url": "http://loki:3100"
}

The body must contain at least one of the two fields, and each value must be a valid URI. CosmicAC writes only the fields in the request, so an omitted field keeps its stored value. An empty string clears the field that carries it, and a null fails validation.

Response

Returns the full settings after the write.

{
  "prometheus_url": "http://prometheus:9090",
  "loki_url": "http://loki:3100"
}

A 200 confirms only that CosmicAC stored the values, not that cosmicac-wrk-monitor received them. The push to the monitor runs separately and never changes the response, so it can fail without an error. CosmicAC skips the push when the deployment omits monitorService.rpcPublicKey.

Errors

A request that fails validation returns the field that CosmicAC rejected.

{
  "error": "Validation failed",
  "details": [
    {
      "field": "prometheus_url",
      "message": "\"prometheus_url\" must be a valid uri"
    }
  ]
}

Every other failure returns the status text and a message.

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "ERR_PERMISSION_REQUIRED"
}

The route returns these status codes.

Clear observability settings

Clears both URLs. CosmicAC stores the change, then pushes both settings to cosmicac-wrk-monitor.

HTTP request

DELETE <cosmicac-url>/api/v1/observability-settings

Response

{
  "prometheus_url": null,
  "loki_url": null
}

The route is idempotent. Clearing settings that CosmicAC never stored returns 200 with both fields null.

Clearing loki_url stops CosmicAC from pushing log lines to Loki. Clearing prometheus_url stops CosmicAC from querying Prometheus for job metrics. Neither change stops your Prometheus from scraping CosmicAC, because you configure that scrape in Prometheus.

Errors

Failed requests return the status text and a message.

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "ERR_PERMISSION_REQUIRED"
}

The route returns these status codes.

What's next

• Connect CosmicAC to your Prometheus and Loki
• Monitor API reference
• Deployment configuration