Documentation

API v1

Goals

Read goals and their key results, create and update key results, and record progress check-ins.

Working with an AI agent?or point it at the Goals markdown or the full-API markdown.

List goals

GET

/api/v1/goals/list

List goals in your display order. By default returns the active set (ACTIVE and PUBLISHED); pass status to see drafts or archives. Requires goals:read (or :write).

Parameter	Type	Description
status	ACTIVE \| PUBLISHED \| DRAFT \| ARCHIVE optional	Only goals with this status.

Response:

{
  data: {
    id: string;
    name: string | null;
    description: string | null;
    status: 'ACTIVE' | 'PUBLISHED' | 'DRAFT' | 'ARCHIVE';
    statusType: 'Stoplight' | 'Percentage' | 'OKR' | 'Task';
    cadence: string | null;
    startDate: number;
    endDate: number | null;
    createdAt: number;
    updatedAt: number;
  }[]
}

Create goal

POST

/api/v1/goals/create

Create a goal, owned by the token owner. Created as a DRAFT — publish it from the app when ready. Requires goals:write.

Parameter	Type	Description
name	string required	Name of the goal.
description	string optional	What this goal is about.

Response:

{
  data: {
    id: string;
    name: string | null;
    description: string | null;
    status: 'ACTIVE' | 'PUBLISHED' | 'DRAFT' | 'ARCHIVE';
    statusType: 'Stoplight' | 'Percentage' | 'OKR' | 'Task';
    cadence: string | null;
    startDate: number;
    endDate: number | null;
    createdAt: number;
    updatedAt: number;
  };
  created: true;
}

Delete goal

POST

/api/v1/goals/delete

Delete a goal by id. Soft-deleted: its details are preserved in history. Requires goals:write.

Parameter	Type	Description
id	string required	Goal id.

Response:

{
  data: { id: string };
  deleted: true;
}

List key results

GET

/api/v1/key-results/list

All key results in one goal, in the goal's display order. Requires goals:read (or :write).

Parameter	Type	Description
goalId	string required	Goal id (from /api/v1/goals/list).

Response:

{
  data: KeyResult[];
}

Get key result

GET

/api/v1/key-results/get

One key result by id, with its check-in history (most recent first). Requires goals:read (or :write).

Parameter	Type	Description
id	string required	Key result id.

Response:

{
  data: {
    id: string;
    goalId: string | null;
    description: string;
    status: string | null; // meaning depends on the goal's statusType
    note: string | null;
    metricName: string | null;
    baseline: string | null;
    target: string | null;
    current: string | null;
    due: number | null;
    goalMode: 'Metric' | 'Development' | null;
    source: string | null;
    createdAt: number;
    updatedAt: number;
    checkIns: {
      id: string;
      keyResultId: string;
      goalId: string;
      checkIn: number;
      current: string | null;
      note: string | null;
      status: string | null;
      createdAt: number;
    }[];
  }
}

Create key result

POST

/api/v1/key-results/create

Create a key result in a goal, owned by the token owner. Metric fields let integrations seed a measurable key result in one call. Requires goals:write.

Parameter	Type	Description
goalId	string required	Goal to create the key result in.
description	string required	What the key result is.
note	string optional	Free-form note.
metricName	string optional	Name of the metric being tracked, for example 'ARR'.
baseline	string optional	Starting value of the metric.
target	string optional	Target value of the metric.
current	string optional	Current value of the metric.

Response:

{
  data: KeyResult;
  created: true;
}

Update key result

POST

/api/v1/key-results/update

Update a key result by id. Only the fields you send change. To record progress over time, prefer the check-in endpoint. Requires goals:write.

Parameter	Type	Description
id	string required	Key result id.
description	string optional	What the key result is.
note	string optional	Free-form note.
metricName	string optional	Name of the metric being tracked.
baseline	string optional	Starting value of the metric.
target	string optional	Target value of the metric.
current	string optional	Current value of the metric.

Response:

{
  data: KeyResult;
  updated: true;
}

Delete key result

POST

/api/v1/key-results/delete

Delete a key result by id. Its details are preserved in the goal's history. Requires goals:write.

Parameter	Type	Description
id	string required	Key result id.

Response:

{
  data: { id: string };
  deleted: true;
}

Create check-in

POST

/api/v1/key-results/check-in

Record a check-in on a key result: a point-in-time progress update with the current metric value, a status, and/or a note. Status values follow the goal's statusType (Stoplight: '', 'red', 'yellow', 'green'; Percentage: '0'..'100'). This is the endpoint for automations that push progress from external systems. Requires goals:write.

Parameter	Type	Description
keyResultId	string required	Key result to check in on.
current	string optional	Current value of the metric.
status	string optional	Status value matching the tracker's statusType, for example 'green'.
note	string optional	Free-form progress note.
checkIn	number optional	Timestamp the check-in covers, epoch milliseconds. Defaults to now.

Response:

{
  data: {
    id: string;
    keyResultId: string;
    goalId: string;
    checkIn: number;
    current: string | null;
    note: string | null;
    status: string | null;
    createdAt: number;
  };
  created: true;
}

Update check-in

POST

/api/v1/key-results/check-in/update

Update an existing check-in by id. Only the fields you send change. Requires goals:write.

Parameter	Type	Description
id	string required	Check-in id (from a key result's checkIns).
current	string optional	Current value of the metric.
status	string optional	Status value matching the goal's statusType.
note	string optional	Free-form progress note.

Response:

{
  data: {
    id: string;
    keyResultId: string;
    goalId: string;
    checkIn: number;
    current: string | null;
    note: string | null;
    status: string | null;
    createdAt: number;
  };
  updated: true;
}

Delete check-in

POST

/api/v1/key-results/check-in/delete

Delete a check-in by id. Its details are preserved in the goal's history. Requires goals:write.

Parameter	Type	Description
id	string required	Check-in id.

Response:

{
  data: { id: string };
  deleted: true;
}