Developer API

Koalr Public API

Integrate engineering metrics into your own tools, dashboards, and workflows. RESTful API with API key authentication and a stable versioned base URL.

Generate API key Browse endpoints

Quick start

Fetch your DORA metrics in one curl command. Replace YOUR_API_KEY with a key from Settings → API Keys.

bash

curl -s \
  -H "X-Koalr-Key: YOUR_API_KEY" \
  "https://api.koalr.com/api/v1/metrics/dora?days=30"

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

Authentication

All requests must include your API key in the X-Koalr-Key header. API keys are scoped to your organisation and inherit your seat permissions.

Header name

X-Koalr-Key

Key format

klr_live_••••••••

Rate limit

60 req / min

bash

curl -s \
  -H "X-Koalr-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.koalr.com/api/v1/teams"

Keep your key secret. Never expose it in client-side JavaScript or public repositories. Rotate compromised keys immediately in Settings → API Keys.

Endpoints

All endpoints are versioned under /api/v1/. Responses are JSON. Timestamps use ISO 8601 UTC.

Metrics

GET/api/v1/metrics/dora

DORA metrics summary for your organisation.

Query parameters

days

number

Rolling window in days (default 30)

Example response

json

{
  "deployFrequency": 4.2,
  "leadTime": 18.5,
  "changeFailureRate": 0.04,
  "mttr": 42,
  "tier": "elite"
}

GET/api/v1/flow

Flow metrics: cycle time, throughput, WIP, and flow efficiency.

Query parameters

days	number	Rolling window in days (default 30)
teamId	string	Filter by team ID

Example response

json

{
  "cycleTime": 2.4,
  "throughput": 18,
  "wipCount": 6,
  "flowEfficiency": 0.61
}

GET/api/v1/review-metrics

Code review metrics including average cycle time and first response time.

Query parameters

days	number	Rolling window in days (default 30)
teamId	string	Filter by team ID

Example response

json

{
  "avgReviewCycleTime": 6.1,
  "avgFirstResponseTime": 1.8,
  "totalReviewed": 94
}

GET/api/v1/copilot

GitHub Copilot usage metrics: adoption rate, acceptance rate, and estimated hours saved.

Query parameters

days

number

Rolling window in days (default 30)

Example response

json

{
  "adoptionRate": 0.74,
  "acceptanceRate": 0.38,
  "estimatedHoursSaved": 312
}

GET/api/v1/value-stream

End-to-end value stream metrics across the software delivery lifecycle.

Query parameters

days

number

Rolling window in days (default 30)

Example response

json

{
  "ideaToCommit": 3.2,
  "commitToMerge": 1.1,
  "mergeToDeploy": 0.4,
  "totalLeadTime": 4.7
}

GET/api/v1/custom-metrics/:slug/query

Run a saved custom metric by its slug. Returns the computed result for the current period.

Query parameters

slugrequired	string	Custom metric slug (path parameter)
days	number	Rolling window in days (default 30)

Example response

json

{
  "slug": "p95-cycle-time",
  "label": "P95 Cycle Time",
  "value": 8.4,
  "unit": "hours",
  "period": "last_30_days"
}

Deployments & Pull Requests

GET/api/v1/deployments

List deployments within a rolling window, optionally filtered by team.

Query parameters

days	number	Rolling window in days (default 30)
teamId	string	Filter by team ID

Example response

json

{
  "data": [
    {
      "id": "dep_01j8x",
      "repo": "acme/api",
      "env": "production",
      "status": "success",
      "deployedAt": "2026-03-14T18:22:00Z",
      "leadTimeSecs": 67200
    }
  ],
  "total": 42,
  "page": 1
}

GET/api/v1/pull-requests

List pull requests within a rolling window with pagination support.

Query parameters

days	number	Rolling window in days (default 30)
teamId	string	Filter by team ID
page	number	Page number (default 1)
pageSize	number	Results per page (default 25, max 100)

Example response

json

{
  "data": [
    {
      "id": "pr_a1b2c3",
      "number": 1847,
      "title": "feat: add retries to webhook processor",
      "repo": "acme/api",
      "author": "jsmith",
      "mergedAt": "2026-03-14T14:11:00Z",
      "cycleTimeSecs": 86400,
      "riskScore": 42
    }
  ],
  "total": 184,
  "page": 1,
  "pageSize": 25
}

GET/api/v1/incidents

List incidents sourced from PagerDuty, Opsgenie, or incident webhooks.

Query parameters

days

number

Rolling window in days (default 30)

Example response

json

{
  "data": [
    {
      "id": "inc_9z2k",
      "title": "API p99 latency spike",
      "severity": "sev2",
      "status": "resolved",
      "startedAt": "2026-03-10T03:14:00Z",
      "resolvedAt": "2026-03-10T04:02:00Z",
      "mttrSecs": 2880
    }
  ],
  "total": 7
}

Teams

GET/api/v1/teams

List all teams in your organisation.

Example response

json

{
  "data": [
    {
      "id": "team_abc123",
      "name": "Platform",
      "memberCount": 8,
      "createdAt": "2025-11-01T00:00:00Z"
    },
    {
      "id": "team_def456",
      "name": "Growth",
      "memberCount": 5,
      "createdAt": "2025-11-01T00:00:00Z"
    }
  ],
  "total": 2
}

Forecasting

GET/api/v1/forecast/delivery

Monte Carlo delivery forecast. Given a number of items, returns P50/P85/P95 completion dates.

Query parameters

itemsrequired	number	Number of backlog items to forecast
teamId	string	Scope forecast to a specific team

Example response

json

{
  "items": 20,
  "teamId": "team_abc123",
  "p50": "2026-04-11",
  "p85": "2026-04-25",
  "p95": "2026-05-09",
  "simulations": 10000
}

GET/api/v1/forecast/backlog

Backlog throughput forecast using historical velocity.

Query parameters

teamId

string

Filter by team ID

Example response

json

{
  "weeklyThroughputP50": 7,
  "weeklyThroughputP85": 12,
  "backlogSize": 68,
  "weeksToEmpty": {
    "p50": 10,
    "p85": 16
  }
}

AI & Risk

POST/api/v1/pr-risk/score

Score a pull request for deployment risk using Koalr's 32-signal model. Returns a risk score 0–100 with a breakdown by signal category.

Request body

prNumberrequired	number	Pull request number
reporequired	string	Repository name (e.g. "api")
ownerrequired	string	GitHub organisation or user (e.g. "acme")

Example response

json

{
  "prNumber": 1847,
  "repo": "acme/api",
  "riskScore": 71,
  "tier": "high",
  "signals": {
    "changeEntropy": 0.82,
    "coverageDelta": -0.06,
    "authorFileExpertise": 0.44,
    "codeownersCompliance": true,
    "aiAuthoredRatio": 0.31
  },
  "recommendation": "Review carefully — high change entropy and coverage regression detected."
}

POST requests

POST endpoints accept a JSON body. Set Content-Type: application/json.

bash

curl -s -X POST \
  -H "X-Koalr-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prNumber": 1847, "repo": "api", "owner": "acme"}' \
  "https://api.koalr.com/api/v1/pr-risk/score"

Rate limits

Plan	Requests / minute	Notes
All plans	60	Per API key, sliding window
Burst	Up to 120	30-second burst allowance

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A 429 response means you have exceeded the limit — retry after the reset timestamp.

Error codes

Status	Meaning
200	Success
400	Bad request — invalid parameters
401	Missing or invalid X-Koalr-Key header
403	Valid key but insufficient permissions
404	Resource not found
429	Rate limit exceeded
500	Internal server error — contact support

SDKs & examples

Official SDKs are coming soon. In the meantime, the REST API works with any HTTP client.

🐍

Python SDK

Coming soon

⬡

Node.js SDK

Coming soon

🦫

Go SDK

Coming soon

Want to contribute an SDK or see a language prioritised? Let us know.

Ready to integrate?

Generate an API key in Settings and start pulling live engineering metrics into your own workflows in minutes.

Generate API key Contact support