---
title: "OKRs API reference"
canonical_url: https://zentrik.ai/docs/api/okrs
markdown_url: https://zentrik.ai/docs/api/okrs.md
last_reviewed: 2026-09-03
---

# OKRs API reference

OKRs describe measurable product outcomes for a workspace. Use these endpoints to keep objectives, key results, product links, and project links synchronized with external planning systems.

- Human reference: https://zentrik.ai/docs/api/okrs
- Complete Markdown index: https://zentrik.ai/docs/api/index.md
- Base URL: `https://zentrik.ai/api`
- Authentication: `Authorization: Bearer YOUR_API_KEY`
- Shared pagination and rate limits: https://zentrik.ai/docs/api/index.md#shared-conventions

## GET /external/v1/okrs — List all OKRs

Operation ID: `list-okrs`

List OKRs in the current workspace. Results include product ids and key-result project ids.

Required API key scopes: `okrs:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | No | Maximum number of OKRs to return. |
| `offset` | number | No | Number of OKRs to skip. |

### Example request

```curl
curl -X GET 'https://zentrik.ai/api/external/v1/okrs?limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | OKRs were successfully retrieved. | Array<OKR> |

### Example response

```json
[
  {
    "id": "okr-uuid",
    "objective": "Increase activation for self-serve teams",
    "priority": 1,
    "workspaceId": "workspace-uuid",
    "productIds": [
      "product-uuid"
    ],
    "keyResults": [
      {
        "id": "key-result-uuid",
        "name": "Lift week-one activation from 42% to 55%",
        "projectIds": [
          "project-uuid"
        ],
        "createdAt": "2026-05-14T10:00:00Z",
        "updatedAt": "2026-05-14T10:00:00Z"
      }
    ],
    "createdAt": "2026-05-14T10:00:00Z",
    "updatedAt": "2026-05-14T10:00:00Z"
  }
]
```

---

## GET /external/v1/okrs/:id — Get one OKR

Operation ID: `get-okr`

Retrieve one OKR from the current workspace.

Required API key scopes: `okrs:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | The OKR UUID. |

### Example request

```curl
curl -X GET https://zentrik.ai/api/external/v1/okrs/okr-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The OKR was successfully retrieved. | OKR |
| 404 | Not Found | No OKR found with the provided id. | — |

### Example response

```json
{
  "id": "okr-uuid",
  "objective": "Increase activation for self-serve teams",
  "priority": 1,
  "workspaceId": "workspace-uuid",
  "productIds": [
    "product-uuid"
  ],
  "keyResults": [
    {
      "id": "key-result-uuid",
      "name": "Lift week-one activation from 42% to 55%",
      "projectIds": [
        "project-uuid"
      ],
      "createdAt": "2026-05-14T10:00:00Z",
      "updatedAt": "2026-05-14T10:00:00Z"
    }
  ],
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}
```

---

## POST /external/v1/okrs — Create an OKR

Operation ID: `create-okr`

Create an OKR. Product and project ids must belong to the API key workspace.

Required API key scopes: `okrs:write`

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `objective` | string | Yes | Outcome-oriented objective. |
| `priority` | number | Yes | Numeric priority used by planning surfaces. |
| `productIds` | uuid[] | No | Products this OKR supports. |
| `keyResults` | object[] | Yes | Array of { name, projectIds? } key results. |

### Example request

```json
{
  "objective": "Increase activation for self-serve teams",
  "priority": 1,
  "productIds": [
    "product-uuid"
  ],
  "keyResults": [
    {
      "name": "Lift week-one activation from 42% to 55%",
      "projectIds": [
        "project-uuid"
      ]
    }
  ]
}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Created | The OKR was successfully created. | OKR |

### Example response

```json
{
  "id": "okr-uuid",
  "objective": "Increase activation for self-serve teams",
  "priority": 1,
  "workspaceId": "workspace-uuid",
  "productIds": [
    "product-uuid"
  ],
  "keyResults": [
    {
      "id": "key-result-uuid",
      "name": "Lift week-one activation from 42% to 55%",
      "projectIds": [
        "project-uuid"
      ],
      "createdAt": "2026-05-14T10:00:00Z",
      "updatedAt": "2026-05-14T10:00:00Z"
    }
  ],
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}
```

---

## PATCH /external/v1/okrs/:id — Update an OKR

Operation ID: `update-okr`

Update an OKR. When keyResults is supplied, it is treated as the full replacement list.

Required API key scopes: `okrs:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | The OKR UUID. |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `objective` | string | No | Updated objective. |
| `priority` | number | No | Updated priority. |
| `productIds` | uuid[] | No | Replacement product links. |
| `keyResults` | object[] | No | Replacement key-result list. Existing key results include id. |

### Example request

```curl
curl -X PATCH https://zentrik.ai/api/external/v1/okrs/okr-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"priority":2}'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Updated | The OKR was successfully updated. | OKR |

---

## DELETE /external/v1/okrs/:id — Delete an OKR

Operation ID: `delete-okr`

Delete an OKR and its key results from the current workspace.

Required API key scopes: `okrs:delete`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | The OKR UUID. |

### Example request

```curl
curl -X DELETE https://zentrik.ai/api/external/v1/okrs/okr-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Deleted | The OKR was successfully deleted. | — |