Skip to content
Argus
Start free

API

The web app reads everything through an HTTP API at https://app.argusadr.dev/api/v1, read-only apart from recording approvals. This page is an overview; a full reference is coming soon.

Authentication

  • Every request needs a signed-in session: the session cookie set when you sign in with GitHub. Without one, the API answers 401.
  • GET /api/v1/healthz and GET /api/v1/openapi.json need no sign-in.
  • API tokens for scripts and CI: not available yet; to be confirmed. Agent tokens open only the MCP server, never /api/v1.

What you see

Only your organisations’ repositories, components and findings, in every list, detail, count and total. Another organisation’s item answers 404.

Conventions

  • Read-only, apart from POST /approvals and the admins’ settings: only GET. Any other method answers 405 (or 403 when it comes from another site or without the session’s CSRF token).
  • JSON with snake_case fields; times are ISO 8601 in UTC.
  • Every response has meta: when it was generated, when the data was last refreshed (data_as_of), and the model’s version.
  • Lists return { "items": [...], "next_cursor": "…" | null, "meta": {...} }. limit defaults to 50, up to 500; pass cursor to get the next page.
  • Filters: a repeated filter means OR, different filters mean AND. For example, ?severity=critical&severity=high&project=shop is critical or high findings in shop.
  • Errors: { "error": { "code": "not_found", "message": "…" } }, with 400, 401, 403, 404 or 500.
  • Caching: each response carries an ETag and Cache-Control: private, max-age=60.

Endpoints

Path Returns
/overview one entry per repository, plus totals
/trend daily open-finding counts
/findings, /findings/{id} findings, filtered; one finding with its history
/rules, /rules/{id} the rule catalogue; one rule with its counts
/repositories the repositories
/prs, /prs/{owner}/{repo}/{number} pull requests; one with its files, components and impact
/agents, /agents/sessions, /agents/sessions/{id} the per-agent summary; sessions agents reported
/approvals what waits for a decision, the decisions made on GitHub, and approval records; POST records an approval made in the app by a signed-in person, never by an agent
/audit the append-only audit log: who changed what, when and from where, for your organisations
/components, /components/{id}, /components/{id}/impact components; one component; what changing it reaches
/contracts, /contracts/{id} contracts and their consumers
/adrs, /docs, /changelog decisions, documents, and what changed in the model by week
/coupling components that change together, and hotspots
/environments what runs where, compared with the default branch
/standards, /initiatives scorecards and initiatives
/insights, /metrics key numbers and charts; the architecture metrics

The machine-readable contract is GET /api/v1/openapi.json.