Objectives

List, read, create, update and delete the Objectives that measure each Goal.

An Objective measures progress toward a Goal. It usually sits directly under a Goal (parentGoalId) or under another Objective as a sub-Objective (parentObjectiveId). To record a new value, use a check-in.

Related: GET /objectives/{objectiveId}/actions, check-ins and Objective comments.

The JavaScript examples assume a headers object holding your key:

const headers = {
  'X-API-Key': process.env.GPS_API_KEY_ID,
  'X-API-Secret': process.env.GPS_API_SECRET,
};

The Objective object#

List Objectives#

GET /objectives

Returns the organization's Objectives that aren't archived, in GPS order (by sortOrder, then oldest first).

Scope: objectives:read

Query parameters

curl "https://plan.empiraa.app/api/v1/objectives?goalId=a1f3c5e7-2b4d-4f6a-8c9e-0b1d3f5a7c9e&status=off_track" \
  -H "X-API-Key: $GPS_API_KEY_ID" \
  -H "X-API-Secret: $GPS_API_SECRET"

const params = new URLSearchParams({ goalId: 'a1f3c5e7-2b4d-4f6a-8c9e-0b1d3f5a7c9e', status: 'off_track' });
const res = await fetch(`https://plan.empiraa.app/api/v1/objectives?${params}`, { headers });
const { data: objectives, meta } = await res.json();

Response 200

{
  "data": [
    {
      "id": "c7e9a1b3-4d5f-4a6b-9c8d-1e2f3a4b5c6d",
      "title": "Reach $120k monthly recurring revenue",
      "description": null,
      "type": "KPI",
      "measurementType": "$",
      "aggregationType": null,
      "progress": "45",
      "status": "off_track",
      "startDate": "2026-07-01T00:00:00.000Z",
      "dueDate": "2027-06-30T00:00:00.000Z",
      "completedDate": null,
      "targetValue": 120000,
      "currentValue": 54000,
      "unit": null,
      "assignedTo": ["5d7f9b1d-3e5a-4c7e-9f1a-2b3c4d5e6f70"],
      "isPrivate": false,
      "invitedUsers": [],
      "parentGoalId": "a1f3c5e7-2b4d-4f6a-8c9e-0b1d3f5a7c9e",
      "parentObjectiveId": null,
      "checkinFrequency": "monthly",
      "checkinDay": 1,
      "trackingPeriod": "total",
      "lastResetDate": null,
      "lastPeriodProgress": null,
      "archived": false,
      "priority": "High",
      "headerImageUrl": null,
      "headerColor": "#1e293b",
      "calculationMode": "manual",
      "isRollupLocked": false,
      "aggregatedProgress": null,
      "integrationFormula": null,
      "lastIntegrationSync": null,
      "integrationSyncStatus": null,
      "autoSyncEnabled": false,
      "sortOrder": 0,
      "weight": null,
      "createdBy": "5d7f9b1d-3e5a-4c7e-9f1a-2b3c4d5e6f70",
      "organizationId": "9b2f4e1a-6c3d-4e8f-a1b2-c3d4e5f6a7b8",
      "sourceMeetingId": null,
      "createdAt": "2026-06-24T01:10:00.000Z",
      "updatedAt": "2026-11-01T00:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}

Errors: 400 INVALID_STATUS_QUERY for an unknown status; 422 VALIDATION_ERROR for a bad limit or offset.

List a Goal's Objectives#

GET /goals/{goalId}/objectives

Returns the Objectives directly under a Goal (not their sub-Objectives). Unlike GET /objectives, this list can include archived Objectives, so check archived. Order isn't guaranteed.

Scope: objectives:read

curl https://plan.empiraa.app/api/v1/goals/a1f3c5e7-2b4d-4f6a-8c9e-0b1d3f5a7c9e/objectives \
  -H "X-API-Key: $GPS_API_KEY_ID" \
  -H "X-API-Secret: $GPS_API_SECRET"

const res = await fetch(
  'https://plan.empiraa.app/api/v1/goals/a1f3c5e7-2b4d-4f6a-8c9e-0b1d3f5a7c9e/objectives',
  { headers },
);
const { data: objectives, meta } = await res.json();

Response 200: a list of Objective objects with meta, as in List Objectives.

Errors: 404 NOT_FOUND if the Goal doesn't exist, is in another organization or is archived; 400 INVALID_STATUS_QUERY; 422 VALIDATION_ERROR for a bad limit or offset.

Get an Objective#

GET /objectives/{id}

Scope: objectives:read

curl https://plan.empiraa.app/api/v1/objectives/c7e9a1b3-4d5f-4a6b-9c8d-1e2f3a4b5c6d \
  -H "X-API-Key: $GPS_API_KEY_ID" \
  -H "X-API-Secret: $GPS_API_SECRET"

const res = await fetch('https://plan.empiraa.app/api/v1/objectives/c7e9a1b3-4d5f-4a6b-9c8d-1e2f3a4b5c6d', { headers });
const { data: objective } = await res.json();

Response 200: { "data": <Objective> }, with the same fields as the item in List Objectives.

Errors: 404 NOT_FOUND if the Objective doesn't exist, is in another organization, or is archived.

Create an Objective#

POST /objectives

Neither parent is required, but an Objective can't have both a parentGoalId and a parentObjectiveId.

progress isn't calculated from currentValue when you create an Objective. To set a value and have GPS work out progress from the target, create the Objective, then record a check-in.

Scope: objectives:write · Webhook: objective.created, with the new Objective as data.

Request body

curl -X POST https://plan.empiraa.app/api/v1/objectives \
  -H "X-API-Key: $GPS_API_KEY_ID" \
  -H "X-API-Secret: $GPS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Reach $120k monthly recurring revenue",
    "parentGoalId": "a1f3c5e7-2b4d-4f6a-8c9e-0b1d3f5a7c9e",
    "type": "KPI",
    "measurementType": "currency",
    "targetValue": 120000,
    "checkinFrequency": "monthly",
    "checkinDay": 1,
    "assignedTo": ["5d7f9b1d-3e5a-4c7e-9f1a-2b3c4d5e6f70"]
  }'

const res = await fetch('https://plan.empiraa.app/api/v1/objectives', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Reach $120k monthly recurring revenue',
    parentGoalId: 'a1f3c5e7-2b4d-4f6a-8c9e-0b1d3f5a7c9e',
    type: 'KPI',
    measurementType: 'currency',
    targetValue: 120000,
    checkinFrequency: 'monthly',
    checkinDay: 1,
    assignedTo: ['5d7f9b1d-3e5a-4c7e-9f1a-2b3c4d5e6f70'],
  }),
});
const { data: objective } = await res.json();

Response 201

{
  "data": {
    "id": "c7e9a1b3-4d5f-4a6b-9c8d-1e2f3a4b5c6d",
    "title": "Reach $120k monthly recurring revenue",
    "description": null,
    "type": "KPI",
    "measurementType": "$",
    "aggregationType": null,
    "progress": "0",
    "status": "not_started",
    "startDate": null,
    "dueDate": null,
    "completedDate": null,
    "targetValue": 120000,
    "currentValue": null,
    "unit": null,
    "assignedTo": ["5d7f9b1d-3e5a-4c7e-9f1a-2b3c4d5e6f70"],
    "isPrivate": false,
    "invitedUsers": [],
    "parentGoalId": "a1f3c5e7-2b4d-4f6a-8c9e-0b1d3f5a7c9e",
    "parentObjectiveId": null,
    "checkinFrequency": "monthly",
    "checkinDay": 1,
    "trackingPeriod": "total",
    "lastResetDate": null,
    "lastPeriodProgress": null,
    "archived": false,
    "priority": null,
    "headerImageUrl": null,
    "headerColor": "#1e293b",
    "calculationMode": "manual",
    "isRollupLocked": false,
    "aggregatedProgress": null,
    "integrationFormula": null,
    "lastIntegrationSync": null,
    "integrationSyncStatus": null,
    "autoSyncEnabled": false,
    "sortOrder": 0,
    "weight": null,
    "createdBy": "5d7f9b1d-3e5a-4c7e-9f1a-2b3c4d5e6f70",
    "organizationId": "9b2f4e1a-6c3d-4e8f-a1b2-c3d4e5f6a7b8",
    "sourceMeetingId": null,
    "createdAt": "2026-11-12T03:16:05.300Z",
    "updatedAt": "2026-11-12T03:16:05.300Z"
  }
}

Errors

Update an Objective#

PATCH /objectives/{id}

Changes only the fields you send. A body with no recognized fields changes nothing, returns the Objective as it is, and fires no webhook.

Changing currentValue here doesn't recalculate progress. To record a new value with its progress, use a check-in.

Scope: objectives:write · Webhook: objective.updated, with the updated Objective as data.

Request body: any field from Create an Objective except onBehalfOf, with the same rules. Also:

• Set parentGoalId or parentObjectiveId to null to detach the Objective from that parent.
• assignedTo and invitedUsers replace the whole list.
• measurementType is stored exactly as you send it on update; the common words listed under Create aren't converted.

curl -X PATCH https://plan.empiraa.app/api/v1/objectives/c7e9a1b3-4d5f-4a6b-9c8d-1e2f3a4b5c6d \
  -H "X-API-Key: $GPS_API_KEY_ID" \
  -H "X-API-Secret: $GPS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "status": "on_track", "dueDate": "2027-03-31" }'

const res = await fetch('https://plan.empiraa.app/api/v1/objectives/c7e9a1b3-4d5f-4a6b-9c8d-1e2f3a4b5c6d', {
  method: 'PATCH',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({ status: 'on_track', dueDate: '2027-03-31' }),
});
const { data: objective } = await res.json();

Response 200: { "data": <Objective> } with the changes applied, for example "status": "on_track" and "dueDate": "2027-03-31T00:00:00.000Z". Every other field is as in List Objectives.

Errors: 404 NOT_FOUND if the Objective doesn't exist, is in another organization or is archived; otherwise the same 422 errors as Create an Objective.

Delete an Objective#

DELETE /objectives/{id}

Permanently deletes the Objective and everything under it: its sub-Objectives, its Actions, its check-in history and its comments.

Scope: objectives:write · Webhook: objective.deleted, with data set to { "id": "<objective id>" }. Sub-Objectives and Actions removed with it don't fire their own events.

curl -X DELETE https://plan.empiraa.app/api/v1/objectives/c7e9a1b3-4d5f-4a6b-9c8d-1e2f3a4b5c6d \
  -H "X-API-Key: $GPS_API_KEY_ID" \
  -H "X-API-Secret: $GPS_API_SECRET"

const res = await fetch('https://plan.empiraa.app/api/v1/objectives/c7e9a1b3-4d5f-4a6b-9c8d-1e2f3a4b5c6d', {
  method: 'DELETE',
  headers,
});
console.log(res.status); // 204

Response 204: no body.

Errors: 404 NOT_FOUND if the Objective doesn't exist, is in another organization, or is archived.