Goals

A goal is a target for one metric over a period, such as "12 weeks with a clean pipeline by 31 December", owned by a person and usually a team. Harmony reads the metric from Harmony itself, from a Loop that reports it, or from people's check-ins, and works out how far along the goal is and whether it is keeping pace. Work counts toward a goal when it is linked to it.

Anyone's key can read active goals. Creating, editing, checking in, linking and archiving need an admin's key: one created by an organization owner or admin.

The Goal object

{
  "id": "goal_pipeline",
  "object": "goal",
  "title": "A clean pipeline every Monday",
  "description": "Every open opportunity has an owner, a next step and a close date by Monday morning.",
  "owner": "usr_sam",
  "team": "team_gtm",
  "metric": { "label": "Weeks with a clean pipeline", "unit": null, "direction": "increase" },
  "target": 12,
  "baseline": 0,
  "period_start": 1759276800,
  "period_end": 1767139200,
  "source": { "kind": "connector", "metric": null, "loop": "loop_pipeline_hygiene", "outcome_label": "Clean pipeline" },
  "status": "active",
  "progress": 0.17,
  "on_track": false,
  "latest": { "day": "2026-10-26", "value": 2, "source": "connector" },
  "links": [
    { "kind": "loop", "id": "loop_pipeline_hygiene", "name": "Pipeline hygiene", "linked": 1760918400 }
  ],
  "blocked_by": [],
  "suggestion": null,
  "confirmed": 1759320000
}

The Harmony metrics a goal can read are tasks_closed, loop_runs_completed, accepted_outcomes, reports_delivered and hours_returned.

List goals

Returns active goals, newest first. An admin's key can pass status=all to include archived ones.

GET /v1/goals

Scope: goals:read

curl https://api.gonimbus.ai/v1/goals \
  -H "Authorization: Bearer $HARMONY_API_KEY"

Retrieve a goal

GET /v1/goals/{goal}

Scope: goals:read. Returns a Goal.

Create a goal

Creates a goal that is active at once. Needs an admin's key. Send an Idempotency-Key header to retry safely; see Idempotent requests.

POST /v1/goals

Scope: goals:write

::: code-group

curl https://api.gonimbus.ai/v1/goals \
  -H "Authorization: Bearer $HARMONY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "title": "Close 40 support tasks a week",
    "team": "team_support",
    "metric": { "label": "Tasks closed", "direction": "increase" },
    "target": 40,
    "period_start": "2026-11-01",
    "period_end": "2026-11-30",
    "source": { "kind": "harmony", "metric": "tasks_closed" }
  }'

const goal = await fetch('https://api.gonimbus.ai/v1/goals', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HARMONY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    title: 'Close 40 support tasks a week',
    team: 'team_support',
    metric: { label: 'Tasks closed', direction: 'increase' },
    target: 40,
    period_start: '2026-11-01',
    period_end: '2026-11-30',
    source: { kind: 'harmony', metric: 'tasks_closed' },
  }),
}).then((r) => r.json())

:::

Returns the new Goal with status 201.

Update a goal

Changes only the fields you send. Takes the same fields as creating one. Needs an admin's key.

PATCH /v1/goals/{goal}

Scope: goals:write

Check in on a goal

Records a reading of the goal's metric for a day: today in UTC when day is left out. A second check-in for the same day replaces the first. Needs an admin's key.

POST /v1/goals/{goal}/check_ins

Scope: goals:write

curl https://api.gonimbus.ai/v1/goals/goal_pipeline/check_ins \
  -H "Authorization: Bearer $HARMONY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": 3, "note": "Two stale deals closed out on Friday." }'

Returns the updated Goal with status 201.

List a goal's check-ins

Returns the goal's readings, newest first: those Harmony took and those people checked in. Each has goal, day, value, source (harmony, connector or manual), note and recorded_by.

GET /v1/goals/{goal}/check_ins

Scope: goals:read. Takes limit and cursor.

Link work to a goal

Links a Loop, a workstream, a Marketplace install or another goal. Linking another goal (kind: "goal") means this goal is blocked by that one; two goals can't block each other. Needs an admin's key.

POST /v1/goals/{goal}/links

Scope: goals:write

To remove a link:

DELETE /v1/goals/{goal}/links/{kind}/{id}

Both return the updated Goal.

See what blocks a goal

Returns the goals this one waits for (blocked_by) and the active goals that wait for it (blocking), as full Goal objects.

GET /v1/goals/{goal}/dependencies

Scope: goals:read

Archive a goal

Archives the goal. Needs an admin's key.

POST /v1/goals/{goal}/archive

Scope: goals:write

Suggested goals

Harmony suggests goals from what it knows about your teams' work. A suggestion has status: "suggested" and a suggestion explaining why, and waits for an admin.

Errors

FAQs

Who can see a goal? Every key in the organization can read active goals. Archived goals and suggestions are for admins' keys.

How often does a Harmony-sourced goal update? Harmony takes a reading once a day. Connector goals update when their Loop runs; manual goals when someone checks in.

Where do people see goals in the app? On the Outcomes page. See Outcomes and goals.