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 on-demand. Computes change entropy, DDL detection, description risk phrases, and size signals from the provided metadata.

curl -X POST https://api.koalr.com/api/v1/pr-risk/score \
  -H "Authorization: Bearer koalr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "acme/api-service",
    "prNumber": 842,
    "headBranch": "feat/auth-rework",
    "title": "Add JWT authentication",
    "body": "Implements session management. Quick fix for login flow.",
    "authorLogin": "jsmith",
    "additions": 280,
    "deletions": 45,
    "changedFiles": 14,
    "fileNames": ["src/auth/login.ts", "prisma/migrations/20260315_add_sessions.sql"],
    "hasApproval": false,
    "ciPassed": true
  }'

Request fields:

Field	Type	Required	Description
`repo`	string	Yes	Full repo name: `"owner/repo"`
`prNumber`	number	Yes	PR number
`headBranch`	string	Yes	Head branch name
`title`	string	Yes	PR title (used for description risk analysis)
`body`	string	No	PR description (used for risk phrase detection)
`authorLogin`	string	Yes	GitHub login of the PR author
`additions`	number	Yes	Lines added
`deletions`	number	Yes	Lines deleted
`changedFiles`	number	Yes	Number of files changed
`fileNames`	string[]	No	Changed file paths — enables DDL detection and entropy scoring
`hasApproval`	boolean	No	Whether the PR has an approving review
`ciPassed`	boolean	No	Whether CI checks passed on the head commit

{
  "riskScore": 82,
  "level": "critical",
  "hasDdl": true,
  "factors": [
    {
      "name": "DDL Migration",
      "score": 80,
      "description": "DDL migration detected in: prisma/migrations/20260315_add_sessions.sql"
    },
    {
      "name": "Description Risk Phrases",
      "score": 55,
      "description": "Matched phrases: quick fix"
    },
    {
      "name": "Review Coverage",
      "score": 15,
      "description": "No approving review"
    }
  ],
  "metadata": {
    "repo": "acme/api-service",
    "prNumber": 842,
    "headBranch": "feat/auth-rework",
    "author": "jsmith"
  }
}

Risk levels: low (0–29) · medium (30–59) · high (60–79) · critical (80–100)

hasDdl: true means a DDL migration file was detected — score is floored at 80 regardless of other signals.

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

Coverage Correlation

GET /coverage/correlation — scope: read:coverage

Returns the Pearson correlation coefficient between coverage % and incident rate per repository, computed over a rolling window.

Query params: days (default: 90)

{
  "correlations": [
    {
      "repo": "acme/api-service",
      "pearsonR": 0.73,
      "interpretation": "strong_positive",
      "dataPoints": 12,
      "coverageTrend": "declining",
      "incidentTrend": "increasing"
    }
  ],
  "windowDays": 90,
  "computedAt": "2026-03-23T08:00:00Z"
}

Incident PR Autopsies

GET /incidents/autopsies — scope: read:incidents

Returns incidents with their linked PR autopsy data — PRs merged in the pre-incident window.

Query params: limit (default: 10, max: 50)

GET /incidents/:id/autopsy — scope: read:incidents

Returns the full PR autopsy for a single incident, including culprit scoring and AI root-cause hypothesis.

Reviewer Gaps

GET /reviewer-gaps — scope: read:review

Returns reviewer expertise gaps — cases where PRs were reviewed by engineers without prior context in the changed files.

Query params: days (default: 90)

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).