GPS REST API

Read and write your organization's Goals, Objectives, Actions, check-ins, Meetings and more from your own code.

The Empiraa GPS REST API lets your own code, scripts and automation tools (Zapier, Make, n8n, Power Automate and so on) read and change the strategy your organization keeps in GPS:

• Goals, the Objectives that measure them, and the Actions that move them forward
• Check-ins that record an Objective's latest value and progress
• Meetings, Improvement Ideas and comments on all of them
• Members of your organization, and its profile (name, vision, industry, website)

GPS can also call your systems when Goals, Objectives or Actions change. See Webhooks.

The API doesn't cover myPortal or meeting check-ins today.

Base URL#

https://plan.empiraa.app/api/v1

Every path in these docs is relative to that base URL. All requests use HTTPS and JSON.

Five-minute quickstart#

You need the Owner, Super Admin or Admin role in your GPS organization to create a key.

1. Create an API key#

1. In GPS, open Settings → Developer → Keys & Webhooks.
2. Under API Keys, select New API Key.
3. Give it a name, and select the scopes goals:read, objectives:read and progress:write.
4. Select Create Key, then copy both the API key (it starts with emp_) and the secret. The secret is shown only once.

Keep both values on your server, for example as environment variables:

export GPS_API_KEY_ID="emp_..."
export GPS_API_SECRET="..."

2. Check the key works#

GET /api/v1 tells you which organization and scopes the key has.

curl https://plan.empiraa.app/api/v1 \
  -H "X-API-Key: $GPS_API_KEY_ID" \
  -H "X-API-Secret: $GPS_API_SECRET"

3. List your Goals#

curl "https://plan.empiraa.app/api/v1/goals?status=on_track&limit=10" \
  -H "X-API-Key: $GPS_API_KEY_ID" \
  -H "X-API-Secret: $GPS_API_SECRET"

const BASE = 'https://plan.empiraa.app/api/v1';
const headers = {
  'X-API-Key': process.env.GPS_API_KEY_ID,
  'X-API-Secret': process.env.GPS_API_SECRET,
};

const res = await fetch(`${BASE}/goals?status=on_track&limit=10`, { headers });
const { data: goals, meta } = await res.json();
console.log(`${meta.total} goals on track`, goals.map((g) => g.title));

Then list the Objectives under one of them:

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"

4. Record a check-in on an Objective#

Send the Objective's latest value. GPS works out the new progress from the Objective's target.

curl -X POST "https://plan.empiraa.app/api/v1/objectives/c7e9a1b3-4d5f-4a6b-9c8d-1e2f3a4b5c6d/progress" \
  -H "X-API-Key: $GPS_API_KEY_ID" \
  -H "X-API-Secret: $GPS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "value": 60000, "notes": "Two new annual contracts signed" }'

const res = await fetch(`${BASE}/objectives/c7e9a1b3-4d5f-4a6b-9c8d-1e2f3a4b5c6d/progress`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({ value: 60000, notes: 'Two new annual contracts signed' }),
});
const { data: checkIn } = await res.json();
console.log(`Progress moved from ${checkIn.previousProgress}% to ${checkIn.newProgress}%`);

The response is the new check-in:

{
  "data": {
    "id": "4b6d8f0b-2c3e-4f5a-b6c7-8d9e0f1a2b3c",
    "objectiveId": "c7e9a1b3-4d5f-4a6b-9c8d-1e2f3a4b5c6d",
    "notes": "Two new annual contracts signed",
    "updatedBy": "5d7f9b1d-3e5a-4c7e-9f1a-2b3c4d5e6f70",
    "value": 60000,
    "previousProgress": 45,
    "newProgress": 50,
    "progressChange": 5,
    "previousValue": 54000,
    "newValue": 60000,
    "createdAt": "2026-11-12T03:15:42.118Z"
  }
}

Where to next#

• Authentication: keys, headers, scopes, rotation and revocation
• Conventions: responses, IDs, dates, pagination, filtering, attribution, errors and rate limits
• Webhooks: events, payloads and signature verification
• API reference:
  • API info and organization
  • Goals
  • Objectives
  • Check-ins
  • Actions
  • Meetings
  • Ideas
  • Comments
  • Members
• OpenAPI specification (OpenAPI 3.0) for code generators and API tools