Operations

Overview

Operations endpoints sit at the site root rather than under /api/v1. /health answers whether the Phoenix application is alive, /ready checks PostgreSQL, migrations, and configured Oban queues, and production /metrics requires its own dedicated bearer token.

Liveness and readiness answer different questions

A 200 from /health means the web process can answer. /ready additionally queries the repository, checks for down migrations, and verifies every configured Oban queue is active with positive concurrency; unhealthy dependencies make it return 503.

Metrics has a separate trust boundary

The metrics token is neither an agk_ workspace key nor an operator session. Production requires metrics auth and refuses startup without a nonblank configured token; invalid scrapes return 401 with a Bearer challenge.

Probe responses are not cached

Health, readiness, and metrics responses set no-cache/no-store controls so monitors observe current process state. The JSON timestamps are probe times, not deployment-version markers.

How it works

1. Route liveness conservatively

   Use GET /health for process restart decisions. Do not make database or worker incidents cause liveness restarts; those dependencies belong to readiness.

2. Gate traffic and deploys on readiness

   Use GET /ready before adding an instance to service and after migrations. Parse checks.repo, checks.migrations, and checks.oban to identify the failing dependency.

3. Scrape metrics with the dedicated secret

   Send Authorization: Bearer $METRICS_BEARER_TOKEN to /metrics, store the token in the monitoring platform's secret facility, and never substitute a workspace API key.

Examples

These examples are illustrative. Replace the sample values with your own. Keep credentials in environment variables or a secret manager, never in client-side code.

export AGENTOPS_BASE_URL="https://robotscenter.net"
export METRICS_BEARER_TOKEN="metrics_secret_from_monitoring_store"

curl --fail-with-body --silent --show-error \
  "$AGENTOPS_BASE_URL/health" | jq .

curl --fail-with-body --silent --show-error \
  "$AGENTOPS_BASE_URL/ready" | jq '{status, checks, timestamp}'

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $METRICS_BEARER_TOKEN" \
  "$AGENTOPS_BASE_URL/metrics" | sed -n '1,20p'

Troubleshooting

Health is 200 while readiness is 503

The process is alive but PostgreSQL, migration state, or an Oban queue is unhealthy. Use the readiness checks object; restarting solely because of dependency failure can amplify an outage.

Readiness reports migrations pending

Apply the release migrations before routing traffic. A pending migration is not considered degraded or healthy by this endpoint.

Metrics returns 401

Use the dedicated configured metrics bearer exactly, without an agk_ prefix assumption. Check for the WWW-Authenticate: Bearer realm="metrics" response and secret drift between app and scraper.

Endpoint reference

Ready to integrate? Open an endpoint for its required permissions, request fields, response format, and status codes. The examples above explain the workflow; these details define each individual request.