API Reference — OKRs Tool

Introduction

Getting started

The OKRs Tool API gives you read and write access to your workspace's OKRs, KPIs, and review summaries. Use it to wire up Slack bots, scheduled jobs, BI dashboards, or anything else that needs your team's progress data.

The API is JSON over HTTPS. Every endpoint is scoped to the organisation that owns the API key — you cannot access another workspace's data.

Base URL

https://go.okrstool.com/api/v1

All requests must be authenticated with a Bearer API key.
All responses are JSON, UTF-8 encoded.
Timestamps use ISO 8601 in UTC.
Each key is rate-limited to 60 requests per minute.

Quick start

curl https://go.okrstool.com/api/v1/okrs \
  -H "Authorization: Bearer okrt_your_api_key_here"

Security

Authentication

All requests must include an API key in the Authorization header as a Bearer token. Keys start with the okrt_ prefix and are tied to a single workspace.

Generate keys from Settings → API Keys. The full key is shown only once at creation — copy it immediately and store it somewhere safe (a password manager, a secrets vault, or your CI environment).

Keep keys server-side. Never commit them to git, never paste them into client-side JavaScript, and never share them in chat. Compromised keys can be revoked instantly from the Settings page.

Available scopes

Scope	Allows
`okrs:read`	List OKRs with progress, status, and health.
`kpis:read`	List KPIs with current value, target, and status.
`kpis:write`	Submit new KPI value updates.
`okr-checkins:write`	Submit Key Result check-ins.
`reviews:read`	Read review cycles and shared review answers.

Any workspace admin can create keys and grant any combination of scopes.

Authorization header

Authorization: Bearer okrt_your_api_key_here

Limits

Rate limits

Each API key is allowed 60 requests per minute. Limits reset at the start of every minute (UTC).

When you exceed the limit, the API returns a 429 response with a Retry-After header (in seconds) telling you when to try again.

Header	Description
`Retry-After`	Seconds until the next request will be accepted. Returned only on `429`.

For higher limits, batch your requests where possible (e.g. a single GET /okrs already returns up to 500 records) or open an issue describing your use case.

429 Response

{
  "error": "rate_limit_exceeded",
  "retry_after_seconds": 30
}

Error handling

Errors

All errors follow the same JSON shape so they're easy to handle in client code.

Status	Code	Meaning
400	`bad_request`	The request body or parameters are malformed.
401	`unauthorized`	Missing or invalid API key.
403	`forbidden`	The key does not have the required scope.
404	`not_found`	The resource does not exist or is not accessible to this key.
429	`rate_limit_exceeded`	You exceeded 60 requests in the current minute.
500	`server_error`	Something went wrong on our end. Safe to retry.

Standard error shape

{
  "error": "forbidden",
  "message": "This key does not have kpis:write permission"
}

Resources

OKRs

Read your organisation's OKRs and submit Key Result check-ins.

GET/api/v1/okrsrequiresokrs:read

Returns the most recent 500 OKRs in your workspace, with computed progress, status, and a 0–100 health score derived from check-in recency, velocity, and progress gap.

Possible errors

401Invalid or missing API key.
403Key is missing the okrs:read scope.

Request

curl https://go.okrstool.com/api/v1/okrs \
  -H "Authorization: Bearer okrt_your_api_key_here"

Response · 200 OK

[
  {
    "id": "f4b1a2c8-…",
    "title": "Improve onboarding conversion",
    "type": "org",
    "owner": "Alice Nguyen",
    "progress": 0.65,
    "status": "on_track",
    "health_score": 82,
    "cycle": "Q2 2026"
  }
]

POST/api/v1/okrs/:id/checkinsrequiresokr-checkins:write

Records a Key Result check-in. The :id in the URL is the Key Result UUID. Status is one of on_track, at_risk, or off_track.

Possible errors

400value is missing or not a number.
404Key Result does not exist in this workspace.

Request

curl -X POST https://go.okrstool.com/api/v1/okrs/KR_ID/checkins \
  -H "Authorization: Bearer okrt_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 70,
    "comment": "New flow shipped",
    "status": "on_track"
  }'

Response · 200 OK

{
  "id": "9e2b…",
  "kr_id": "KR_ID",
  "value": 70,
  "status": "on_track",
  "created_at": "2026-04-19T12:00:00Z"
}

Resources

KPIs

Read tracked KPIs and post new measurement values.

GET/api/v1/kpisrequireskpis:read

Returns up to 500 KPIs with their current value, target, unit, and computed status.

Possible errors

401Invalid or missing API key.
403Key is missing the kpis:read scope.

Request

curl https://go.okrstool.com/api/v1/kpis \
  -H "Authorization: Bearer okrt_your_api_key_here"

Response · 200 OK

[
  {
    "id": "a812…",
    "name": "Weekly Active Users",
    "current": 3721,
    "target": 4500,
    "unit": "users",
    "status": "at_risk",
    "last_updated": "2026-04-01T09:30:00Z"
  }
]

POST/api/v1/kpis/:id/updatesrequireskpis:write

Records a new KPI measurement. The previous value is captured automatically for trend tracking.

Possible errors

400value is missing or not a number.
404KPI does not exist in this workspace.

Request

curl -X POST https://go.okrstool.com/api/v1/kpis/KPI_ID/updates \
  -H "Authorization: Bearer okrt_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 3810,
    "comment": "Small uptick after release"
  }'

Response · 200 OK

{
  "id": "u-7c2…",
  "kpi_id": "KPI_ID",
  "previous_value": 3721,
  "new_value": 3810,
  "created_at": "2026-04-19T12:00:00Z"
}

Resources

Reviews

Read review cycles and the raw answers from shared reviews.

GET/api/v1/review-cyclesrequiresreviews:read

Lists all review cycles in the workspace with the count of distinct reviewees.

Possible errors

403Key is missing the reviews:read scope.

Request

curl https://go.okrstool.com/api/v1/review-cycles \
  -H "Authorization: Bearer okrt_your_api_key_here"

Response · 200 OK

[
  {
    "id": "rc-2c8…",
    "name": "Q2 2026 Mid-Year Review",
    "status": "active",
    "due_date": "2026-05-03",
    "reviewee_count": 2
  }
]

GET/api/v1/reviews/:id/summaryrequiresreviews:read

Returns the raw question/answer pairs from a shared review. Only reviews that have been shared (status: shared) are accessible — drafts return 404. We intentionally return raw answers rather than a curated summary so you can run your own AI summarisation downstream.

Possible errors

404Review does not exist or has not been shared yet.

Request

curl https://go.okrstool.com/api/v1/reviews/REVIEW_ID/summary \
  -H "Authorization: Bearer okrt_your_api_key_here"

Response · 200 OK

{
  "review_id": "REVIEW_ID",
  "employee": "Sarah Chen",
  "cycle": "Q2 2026 Mid-Year Review",
  "type": "self",
  "status": "shared",
  "answers": [
    {
      "question": "What went well this cycle?",
      "answer": "Shipped the onboarding redesign on time"
    },
    {
      "question": "What are your growth areas?",
      "answer": "Delegation and prioritisation"
    }
  ],
  "shared_at": "2026-04-19T12:00:00Z"
}