Sauron API Server
Sauron API Server lets customers inspect and update selected Sauron configuration through REST APIs. Open the Sauron API Server Swagger Docs for the complete request and response shape for your Sauron.
| Component or API area | Role in this page |
|---|---|
| Sauron API Server | Provides Swagger-backed REST APIs for supported Sauron status and configuration operations. |
| Prometheus and Alertmanager APIs | Read or update configs, rules, templates, auxiliary files, and version history. |
| Security APIs | Create supported users, reset passwords, and generate Bearer tokens. |
| Thanos, Grafana, backup, PushProx, and self-alerting APIs | Manage the supported API areas listed below. |
Make your first API check
If you are new to the Sauron API, start with a read-only API before making any configuration changes.
- Open https://api.stage.apatil.developers.oracledx.com.
- Sign in with an account that has access to the API endpoint.
- Use a
GETAPI to inspect current configuration or status. - Confirm the response is for the Sauron you intended to manage.
- Review the request and response shape before using
PUT,POST, orDELETEoperations.
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.
If you have a Sauron provisioned already, please refer to Sauron API Server Swagger Docs for more details. If you are yet to get your Sauron provisioned, please reach out to Sauron team for more information.
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 or enable SSO | SSO status and global SSO actions: /v1/sso/status and /v1/global/sso/actions |
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, install, or remove Grafana plugins | Grafana plugin APIs: /v1/grafana/plugins |
Create Grafana Dashboards |
| 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 |
Sending Metrics |
| Enable or disable PushProx | PushProx lifecycle actions: /v1/pushprox/actions |
Shuttleproxy/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 a redacted copy of the current config or rule file before replacing it.
- Treat
202 Acceptedas "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. |
Self-check before escalation
Most questions for this topic can be resolved with the Swagger docs and a read-only API check. For API access, lock, or update issues, check and collect:
- Sauron API URL.
- Component or endpoint.
- API operation and path, for example
GET /v1/sso/status. - Authentication method: SSO or Bearer token.
- Exact error/status or response body.
- Start time.
- Recent config, credential, entitlement, or lock-related changes.
- Checks completed, including whether a read-only
GETAPI works. - Redacted config diff or payload shape, if the issue is tied to a write call.
- Validation output, if the API returned validation details.
- Production impact, if any.
Do not paste passwords, bearer tokens, private keys, or other secrets in Slack.