API Endpoint Reference

Everything the web UI does goes through the same HTTP API the CLI and the AI chat tools use, so you can script RootCoz from CI, from a shell, or from your own tooling. This page groups the endpoints by what they do, states the minimum role each one needs, and points at the live OpenAPI schema for exact field-level detail.

Prerequisites

• A running RootCoz server. The examples use http://localhost:8000; see Quickstart.
• An API key. Register or log in in the web UI, or send Authorization: Bearer <API_KEY> with any request.
• The role your call needs: viewer, reviewer, operator, or admin. See Managing Users and Server Settings.

Quick Example

curl -H "Authorization: Bearer $ROOTCOZ_API_KEY" \
  http://localhost:8000/results/JOB_ID

That single authenticated GET returns the stored analysis for one job, including failures, classifications, patterns, classification overrides, tracker links, capabilities, and child jobs. It does not include the comment thread — call GET /results/{job_id}/comments separately for that.

Step-by-Step

1. Authenticate.

Send your API key as a bearer token. The rootcoz_session cookie set at login works too, and X-Forwarded-User works when the server runs behind a trusted proxy with TRUST_PROXY_HEADERS=true.

bash curl -H "Authorization: Bearer $ROOTCOZ_API_KEY" \ http://localhost:8000/api/auth/me

GET /api/auth/me is the cheapest way to confirm your identity, role, and reports access. Send OPTIONS requests freely — CORS preflight bypasses authentication everywhere.

1. Discover the schema instead of guessing field names.

These three are public so an integrator can read the contract without credentials. Every route in the schema sets an explicit camelCase operation_id derived from the handler name, so generated clients get stable method names such as getJobResult and analyzeSubmittedJob.

Note: This page is a curated map of the endpoints people actually call. The live schema at /openapi.json is the exhaustive list.

1. Know the role ladder before you script anything.

can_view_reports is a separate flag from role. Admins always have it; anyone else needs an admin to grant it. Most calls that create or modify data also run against the ALLOWED_USERS allow list, which is empty (open) by default and always bypassed for admins. The check is per-handler, not global, so it is enforced on data-modifying routes rather than as a middleware boundary; tests/test_allow_list_coverage.py enumerates the mutating routes and fails if one that can write data is added without the check. The exemptions are listed exactly in that test: the authentication routes, the read-only Jira and token-validation lookups, the metadata rules preview, and DELETE /api/user/ai-credentials/{provider} — revoking your own key stays possible even if you are off the list, otherwise being removed would leave you holding a credential you cannot remove.

Warning: A role you do not hold returns 403, not 404. 403 Admin access required, 403 Reviewer access required, and 403 Operator access required name the exact gate you hit.

Public and unauthenticated routes

Authentication and your account

Registration returns the raw API key exactly once and sends Cache-Control: no-store. Store it before you navigate away.

Submitting and driving analyses

All of these continue in the background and return 202 Accepted, except POST /results/{job_id}/abort, which returns 200 OK. POST /submit ingests only and stops before cloning or AI work; POST /analyze runs the full pipeline.

The shared body accepts the server defaults as per-request overrides:

Note: Resolution order for provider, model, timeout, concurrency, peers, and additional repos is request → .rootcoz/settings.json in the cloned tests repo → server setting → environment variable. See Configuring Analysis Context.

Reading results

fields returns full values for allowlisted paths only and is never truncated. Unknown paths return 400, so fetch /api/results/fields first when you build against it.

Review, classification, and job maintenance

Classification values are CODE ISSUE, PRODUCT BUG, and INFRASTRUCTURE. Pattern values are NEW, REGRESSION, FLAKY, INTERMITTENT, KNOWN_BUG, and PERSISTENT. These are the exact API values; the UI renders KNOWN_BUG as Known Bug and spaces the words for readability.

Note: This table lists the role each route actually enforces. One route marked "Known gap" enforces no role beyond authentication — viewer is therefore its effective minimum, even though the documented model reserves it for reviewer: POST /api/auth/rotate-key, tracked in #289. Treat it as a bug, not as a supported way to operate. PUT /results/{job_id}/reviewed and PUT /results/{job_id}/tags were previously gaps as well and now require reviewer. Review state is tracked per test; classification and pattern changes apply across the whole same-error group.

Comments and mentions

Trackers, issues, and exporters

Note: All four issue preview and create endpoints call _require_reviewer, so a viewer receives 403 before the allow list is consulted. They additionally require valid tracker credentials and the matching ENABLE_GITHUB_ISSUES or ENABLE_JIRA_ISSUES toggle.

History and classification lookup

Send source="ai" to attribute the classification to the reserved rootcoz-ai identity. The backend blocks AI callers from overriding classifications a human has already set.

Chat

Server-Sent Events streams

Use /api/stream when you want one connection instead of six. It accepts up to 50 comma-separated topics; token-usage and settings are delivered only to admins.

Reports and analytics

Date bounds use the from and to query names. Without the flag you get 403 Reports access required.

Metadata assignment

Notifications and AI discovery

Admin

See Configuration Reference for the full environment variable surface behind these admin settings.

Advanced Usage

Prefer the CLI when you can. Most endpoints above have a rootcoz command counterpart. SSE streams have none, because the CLI is a one-shot tool, and the user-token endpoints (GET/PUT /api/user/tokens) have client methods but no registered CLI command either. See CLI Command Reference and Automating Common Tasks with the CLI.

A three-call integration that skips the UI entirely:

KEY="$ROOTCOZ_API_KEY"
BASE=http://localhost:8000

JOB=$(curl -s -X POST "$BASE/analyze" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"type":"file","raw_xml":"<testsuite>...</testsuite>","labels":["nightly"]}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["job_id"])')

curl -s -H "Authorization: Bearer $KEY" "$BASE/results/$JOB" | jq '.status'

curl -s -H "Authorization: Bearer $KEY" \
  "$BASE/results/$JOB?fields=status,result.summary"

For long-lived integrations, open /api/stream?topics=navbar,results:$JOB once instead of polling the result endpoint.

Troubleshooting

• 403 Authentication required or a 401 on a supposedly public path.
  The path is not in the public allow list. Use POST /api/auth/login for a session cookie or send Authorization: Bearer <API_KEY>.

• 403 Admin access required on /api/admin/*.
  Your account is not admin. The bootstrap admin superuser is created from ADMIN_KEY; see Managing Users and Server Settings.

• 403 Reports access required from /api/reports/*.
  You need the can_view_reports flag, which is independent of role. Admins always have it.

• 400 from GET /results/{job_id}?fields=....
  One path is not on the allowlist. Fetch GET /api/results/fields and use an exact path.

• 404 on /api/results/{job_id}/tests for tests you expect.
  A 404 here means the job ID does not exist — the endpoint checks that before applying any filter, so no amount of child_job_name or child_build_number will help. An existing job that simply has no matching entries returns 200 with an empty entries list; to narrow or widen that, confirm the status filter matches passed, skipped, or failed, and add child_job_name and child_build_number when the tests live under a child job.

• 403 on POST /analyze right after registering.
  Your default role is viewer or the account is still pending approval. Check GET /api/auth/me, then ask an admin to raise your role or approve the account.

Related Pages

• Configuration Reference
• CLI Command Reference
• Automating Common Tasks with the CLI
• Submitting Analyses
• Reviewing and Classifying Failures
• Using Server Chat for Cross-Job Analysis
• Exploring History and Reports
• Managing Users and Server Settings