Documentation

REST API

Authenticate and use the CroCode dashboard REST API.

On this page

Authentication and errors

The Rust API listens on port 8080. Send a GitHub App user access token as a bearer token. The dashboard calls the API from the server only.

Authorization: Bearer <github user access token>

The API checks accessible installations with GitHub and caches access for 60 seconds. It does not store user tokens in Postgres.

{ "error": "message" }

Errors use 401 for a missing or invalid token, 403 for no access, 404 for an unknown ID, and 422 for invalid input.

Endpoints

Method	Path	Result
GET	`/healthz`	No authentication. Returns ok.
GET	`/api/v1/me`	Signed-in user ID and login.
GET	`/api/v1/agents`	Enabled agents, server default, detected models, and harness health.
GET	`/api/v1/installations`	Accessible installations that exist in the database.
GET	`/api/v1/installations/{id}`	One accessible installation.
PATCH	`/api/v1/installations/{id}/settings`	Update settings. Requires can_admin.
GET	`/api/v1/installations/{id}/reviews`	Review history, newest first. Filter by repo and pr.
GET	`/api/v1/installations/{id}/stats`	Review totals for the last 30 days.
GET	`/api/v1/installations/{id}/pulls`	Open pull requests with their newest review.
GET	`/api/v1/reviews/{id}`	One review with its summary and findings.
GET	`/api/v1/reviews/{id}/pull`	Live pull request details from GitHub.
POST	`/api/v1/reviews/{id}/retry`	Queue the newest failed or cancelled review again. Requires can_admin.
POST	`/api/v1/reviews/{id}/cancel`	Cancel a queued or running review. Requires can_admin.

Installations and settings

{
  "id": 123,
  "account_login": "acme",
  "account_type": "Organization",
  "repository_selection": "selected",
  "suspended": false,
  "created_at": "2026-11-01T10:00:00Z",
  "settings": { "enabled": true, "agent": "claude", "model": null },
  "digest": { "enabled": false, "webhook_host": null, "sent_at": null, "attempted_at": null, "error": null },
  "can_admin": true
}

can_admin is true for the account owner or an organization admin. A null agent uses the server default. A null model uses the selected agent’s default.

All fields in the settings PATCH body are optional. The response is the updated installation. Set digest_webhook_url to an HTTPS URL to turn on the weekly security digest, or to null to turn it off. The API never returns the URL.

{ "enabled": true, "agent": "claude", "model": null }

Review history

Use limit from 1 to 100. The default is 50. Supply an RFC 3339 timestamp as before for older reviews. Add repo and pr together to list the reviews of one pull request.

/api/v1/installations/123/reviews?limit=50&before=2026-11-01T10:00:00Z

[
  {
    "id": "6f1c0b9e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "installation_id": 123,
    "repo_full_name": "acme/api",
    "pr_number": 42,
    "pr_title": "Add login",
    "head_sha": "abc123...",
    "status": "succeeded",
    "agent": "claude",
    "model": null,
    "attempts": 1,
    "finding_count": 3,
    "error": null,
    "created_at": "2026-11-01T10:00:00Z",
    "finished_at": "2026-11-01T10:03:00Z",
    "agent_duration_ms": 95000,
    "input_tokens": 24388,
    "cached_input_tokens": 12288,
    "output_tokens": 512
  }
]

Status is queued, running, succeeded, failed, cancelled, or skipped. The agent is null until a worker selects one. Token fields are null when the agent CLI reports no usage.

Review details and findings

The detail response has review, summary, and findings fields. The review uses the same shape as a history item. Each finding uses this shape:

{
  "id": "finding-id",
  "path": "src/auth.rs",
  "start_line": null,
  "line": 120,
  "severity": "high",
  "category": "security",
  "title": "Token compared with ==",
  "body": "Explanation",
  "suggestion": null,
  "published": true
}

Severity is critical, high, medium, low, or info. Suggestions contain replacement code or null.

The API contract in the repository is the source reference for clients.