> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Objectives

> Read and write objectives and key-result progress over the Platform API.

The Objectives API reads and writes goals and their key-result progress. Reads use the `objectives:read` scope and require that permission at the deployment root. Writes use the `objectives:manage` scope together with `objectives:read`, because every write answers the objective or key result it wrote, and require both permissions at the deployment root, the same permission and home the Console's objective writes use. A tenant-only grant receives `403 permission_denied`. The built-in apps never receive `objectives:manage`.

Objective responses include status, parent, dates and owner kind. For every `worker` owner, `ownerRefId` is `null` because the stored identifier cannot distinguish a person from an agent. A machine writes only `company` or `orgUnit` owners.

## Operations

* [List objectives](https://docs.gloo.com/forge/reference/http-api/objectives/list.md) — filters and cursor paging, up to 100 rows per page
* [Get objective](https://docs.gloo.com/forge/reference/http-api/objectives/get.md) — one objective by id
* [List key results](https://docs.gloo.com/forge/reference/http-api/objectives/listKeyResults.md) — an objective's key results, up to 200 per page, continued with `meta.nextCursor`

## Write operations

* [Create objective](https://docs.gloo.com/forge/reference/http-api/objectives/create.md) — a `DRAFT` objective owned by the company or an org unit
* [Update objective](https://docs.gloo.com/forge/reference/http-api/objectives/update.md) — title, description, owner, status or target date
* [Archive objective](https://docs.gloo.com/forge/reference/http-api/objectives/archive.md) — status `CANCELLED`; nothing is deleted
* [Add key result](https://docs.gloo.com/forge/reference/http-api/objectives/addKeyResult.md) — starts at `currentValue: 0` and `ON_TRACK`
* [Update key result](https://docs.gloo.com/forge/reference/http-api/objectives/updateKeyResult.md) — title, target, progress, unit or status
* [Remove key result](https://docs.gloo.com/forge/reference/http-api/objectives/removeKeyResult.md) — a permanent delete

Every write accepts an optional `Idempotency-Key`. A same-key retry within 24 hours returns the recorded result only while the caller still holds `objectives:read` and `objectives:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. A successful write records no audit event, as the Console's objective writes record none; a refused write records a denial.

List cursors are bound to the filters that created them. Reusing one with different filters returns `400 bad_request`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.