---
title: GPS REST API
description: Read and write your organization's Goals, Objectives, Actions, check-ins, Meetings and more from your own code.
product: gps
section: api
order: 1
---

# GPS REST API

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](webhooks.md).

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:

```bash
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.

```bash
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

```bash
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"
```

```js
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:

```bash
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.

```bash
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" }'
```

```js
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:

```json
{
  "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](authentication.md): keys, headers, scopes, rotation and revocation
- [Conventions](conventions.md): responses, IDs, dates, pagination, filtering, attribution, errors and rate limits
- [Webhooks](webhooks.md): events, payloads and signature verification
- API reference:
  - [API info and organization](reference/organization.md)
  - [Goals](reference/goals.md)
  - [Objectives](reference/objectives.md)
  - [Check-ins](reference/check-ins.md)
  - [Actions](reference/actions.md)
  - [Meetings](reference/meetings.md)
  - [Ideas](reference/ideas.md)
  - [Comments](reference/comments.md)
  - [Members](reference/members.md)
- [OpenAPI specification](openapi.json) (OpenAPI 3.0) for code generators and API tools