Public API Reference

The Koalr REST API lets you query your engineering metrics from CI pipelines, dashboards, or custom tooling.

Base URL: https://api.koalr.com/api/v1

Rate limit: 60 requests per minute per API key.

Authentication

Include your API key as a Bearer token in every request:

curl https://api.koalr.com/api/v1/metrics/dora \
  -H "Authorization: Bearer koalr_your_api_key_here"

Create API keys at Settings → API Keys. Each key has scopes that control which endpoints it can access.

Endpoints

DORA Metrics

GET /metrics/dora — scope: read:dora

Returns DORA metrics summary for the specified time window.

Query params: from (ISO 8601), to (ISO 8601)

curl "https://api.koalr.com/api/v1/metrics/dora?from=2026-01-01&to=2026-03-01" \
  -H "Authorization: Bearer koalr_..."

{
  "deploymentFrequency": { "perDay": 4.2, "tier": "Elite" },
  "leadTime": { "medianMinutes": 420, "tier": "High" },
  "changeFailureRate": { "pct": 2.1, "tier": "Elite" },
  "mttr": { "medianMinutes": 35, "tier": "Elite" }
}

---

Deploy Risk Score

POST /pr-risk/score — scope: read:deploy-risk

Score any pull request for deployment risk without any database state — stateless and fast.

curl -X POST https://api.koalr.com/api/v1/pr-risk/score \
  -H "Authorization: Bearer koalr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "files": ["src/auth/login.ts", "prisma/migrations/add_users.sql"],
    "additions": 280,
    "deletions": 45,
    "title": "Add user authentication",
    "body": "Implements JWT login and session management"
  }'

{
  "score": 78,
  "label": "High Risk",
  "requiresHardGate": true,
  "factors": [
    { "factor": "DDL Migration", "score": 95, "weight": 0.08 },
    { "factor": "Change Size", "score": 72, "weight": 0.10 },
    { "factor": "Change Entropy", "score": 35, "weight": 0.09 }
  ]
}

---

Pull Requests

GET /pull-requests — scope: read:prs

Query params: from, to, state (OPEN | MERGED | CLOSED), page

---

Deployments

GET /deployments — scope: read:deployments

Query params: from, to

---

Incidents

GET /incidents — scope: read:incidents

Query params: from, to

---

Flow Metrics

GET /flow — scope: read:flow

Returns cycle time, throughput, and WIP.

Query params: from, to, teamId

{
  "cycleTime": { "p50Minutes": 420, "p75Minutes": 840 },
  "throughput": { "mergedPerWeek": 12.3 },
  "wip": { "openPrs": 8, "avgAgeHours": 18 }
}

---

Code Review Metrics

GET /review-metrics — scope: read:review

Query params: from, to, teamId

---

Value Stream

GET /value-stream — scope: read:value-stream

GET /value-stream/trend — scope: read:value-stream

Query params: from, to, teamId, weeks (trend only)

---

Forecasting

GET /forecast/delivery — scope: read:forecasting

Monte Carlo delivery forecast for N work items.

Query params: targetItems, teamId

GET /forecast/backlog — scope: read:forecasting

Forecast when the current open PR backlog will clear.

Query params: teamId

---

Teams

GET /teams — scope: read:teams

---

GitHub Copilot

GET /copilot — scope: read:copilot

---

Custom Metrics

GET /custom-metrics/:slug/query — scope: read:custom-metrics

Run a saved custom metric definition by its slug.

Query params: any parameters defined in the metric formula

---

Error responses

Status	Meaning
401	Missing or invalid API key
403	API key lacks required scope
404	Resource not found
429	Rate limit exceeded (60 req/min)

All errors return { "statusCode": N, "message": "..." }.

Webhooks (outbound)

Koalr can push events to your systems via outbound webhooks. Configure at Settings → Webhooks.

Available events: deployment.created, incident.opened, incident.resolved, pr.merged, risk_score.high (score > 75).