Sauron API Server

Use Sauron API Server to inspect or change supported settings. The Sauron API reference gives request and response details for your instance.

Make your first API check

If you are new to the Sauron API, start with a read-only API before making any configuration changes.

  1. Open the Sauron API reference.
  2. Sign in with an account that has access to the API endpoint.
  3. Use a GET API to inspect current configuration or status.
  4. Confirm the response is for the Sauron you intended to manage.
  5. Review the request and response shape before using PUT, POST, or DELETE operations.

Good first read-only checks:

Check API path Use it to confirm
API health GET /healthcheck The API endpoint is reachable.
Contact email GET /v1/contactemail The Sauron contact email value is visible.
SSO status GET /v1/sso/status SSO status is visible for Sauron endpoints.
Ingress CIDRs GET /v1/ingressCidrs Which source CIDRs customers should allow for Sauron Prometheus scraping.
Prometheus config history GET /prometheus/config/versions Saved Prometheus config versions are visible.
Alertmanager config history GET /alertmanager/config/versions Saved Alertmanager config versions are visible.

If an API returns 403 Access Denied, confirm that your SSO entitlement or Bearer token has the required role for that operation.

For Sauron API automation, prefer OAuth 2.0 Bearer token access. Some examples in the help use Basic Authentication for short admin setup flows, including token creation and password-based admin actions.

Which API area should I use?

Task Public API area Related page
Update Prometheus scrape configuration Prometheus config: /prometheus/config Sending Metrics
Create or update Prometheus alert rules Prometheus rules: /prometheus/rules and /prometheus/rules/{name} Defining Alerts
Manage Prometheus TLS certificates Prometheus TLS certificates: /v1/prometheus/tlscertificates and /v1/prometheus/tlscertificate/{name} Sending Metrics
Manage Prometheus auxiliary files Prometheus auxiliary files: /v1/prometheus/auxiliaryfiles Sending Metrics
Update Alertmanager routing Alertmanager config: /alertmanager/config Defining Alerts
Manage Alertmanager templates Alertmanager templates: /v1/alertmanager/templates and /v1/alertmanager/template/{name} Defining Alerts
Manage Alertmanager auxiliary files Alertmanager auxiliary files: /v1/alertmanager/auxiliaryfiles Defining Alerts
View or update the Sauron contact email Contact email: /v1/contactemail FAQ
Check SSO status SSO status: /v1/sso/status User Access
Create users, reset passwords, or generate Bearer tokens Security APIs: /v1/user/create, /v1/user/password, and /v1/oauth2/token User Access
Get recent component pod logs Logs API: /v1/log Troubleshooting
Find network allowlist CIDRs Security CIDRs: /v1/ingressCidrs, /v1/egressCidrs, and /v1/cidrs Sending Metrics
Update Sauron self-alerting Self-alerting APIs: /v1/selfalerting Sauron Self-Alerting
Configure Grafana email alerts Grafana email alert APIs: /v1/grafana/email/alerts/config and /v1/grafana/email/alerts/template Defining Alerts
List Grafana plugins; get approval before installation Grafana plugin APIs: /v1/grafana/plugins Plugin approval
Enable or disable the Console chatbot Chatbot lifecycle actions: /v1/chatbot/actions Sauron Console
View available backup lists Backup list APIs: /v1/backup/grafana, /v1/backup/prometheus, and /v1/backup/elasticsearch FAQ
Manage Thanos additional stores Thanos additional stores: /v1/thanos/additionalstores Federated Metric Views with Thanos
Manage Thanos rule files Thanos rule files: /v1/thanos/rulefilenames Defining Alerts
Update Thanos rule evaluation interval Thanos rule eval interval: /v1/thanos/rule/evalinterval Defining Alerts
Manage Thanos server-side certificate Thanos server certs: /v1/thanos/servercerts Thanos certificates
Enable or disable PushProx PushProx lifecycle actions: /v1/pushprox/actions PushProx

Use Swagger for exact parameters, payload formats, and response examples before making changes.

Before you make a write call

Read the current state first. For config and rule files, many API areas provide GET endpoints and version-history endpoints so you can inspect the current value before replacing it.

For PUT, POST, and DELETE calls:

  • Confirm the API URL and Sauron name before changing configuration.
  • Keep the original config or rule file securely for rollback. Redact only copies shared for support.
  • Treat 202 Accepted as "the API accepted the change." Downstream components may still need time to reload the updated configuration.
  • If the Sauron is locked, write calls can return 409 Conflict.
  • Config and rule updates can be rejected by validation checks such as YAML parsing, Prometheus rule validation, Alertmanager config validation, or Thanos rule validation.
  • Do not paste passwords, bearer tokens, TLS private keys, generated OAuth tokens, or other secrets in Slack.

Common responses

Response Meaning What to check next
200 OK The read or completed operation succeeded. Verify the returned value is for the intended Sauron and component.
202 Accepted The API accepted the change and the component may apply it asynchronously. Wait for the component to reload, then verify through the relevant UI or GET API.
400 Bad Request The request was invalid or failed validation. Check required parameters, payload format, YAML syntax, and validation output.
403 Access Denied The caller does not have the required access for the operation. Check SSO entitlement, Bearer token role, and the operation being attempted.
404 Not Found The requested file, store, endpoint, or resource was not found. Check the path, filename, store name, and whether the feature exists on this Sauron.
409 Conflict The change conflicts with current state, such as a locked Sauron or an already-created resource. Check whether the Sauron is locked and whether the resource already exists.
500 Internal Server Error The API hit a backend, Kubernetes, validation-tool, or dependency error. Collect the request details and response body before escalating.

Tips and checks

  • Tips: Start with a read-only request. Keep a secure copy of shared configuration before editing it; redact only copies shared with others.
  • Check: Inspect the HTTP status and response, then read the configuration back to confirm a change. For errors, compare the method, path, and request body with the documented operation.