# OrgOrg API v1 — Goals — instructions for AI agents

This document describes the Goals endpoints of the OrgOrg v1 REST API. Fetch it from https://orgorg.com/docs/api/v1/goals/agents.md. The full API is documented at https://orgorg.com/docs/api/v1/agents.md.

## Basics

- Base URL: `https://orgorg.com`. All endpoint paths below are relative to it.
- Every request requires an `Authorization: Bearer <token>` header.
- `GET` endpoints take parameters in the URL query string. `POST` endpoints take a JSON body with a `Content-Type: application/json` header.
- All responses are JSON. A non-2xx status means the request failed; the body describes the problem.
- Endpoints are stable, but new response fields may be added without notice — ignore fields you do not recognize.

## Getting a token

Tokens are created by a signed-in user at https://orgorg.com/docs/credentials and inherit that user's permissions in their organization. If you do not have a token, ask your user to create one there. Verify a token works with:

```sh
curl "https://orgorg.com/api/v1/auth/test" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

A valid token returns `{ "ok": true, ... }`.

## Goals

Read goals and their key results, create and update key results, and record progress check-ins. Human-readable docs: https://orgorg.com/docs/api/v1/goals

### 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).

Parameters:

- `status` (`ACTIVE` | `PUBLISHED` | `DRAFT` | `ARCHIVE`, optional) — Only goals with this status.

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/goals/list" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  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.

Parameters:

- `name` (string, required) — Name of the goal.
- `description` (string, optional) — What this goal is about.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/goals/create" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 revenue",
    "description": "Grow revenue this quarter"
  }'
```

Response shape:

```ts
{
  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.

Parameters:

- `id` (string, required) — Goal id.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/goals/delete" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "GOAL_ID"
  }'
```

Response shape:

```ts
{
  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).

Parameters:

- `goalId` (string, required) — Goal id (from /api/v1/goals/list).

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/key-results/list?goalId=GOAL_ID" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  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).

Parameters:

- `id` (string, required) — Key result id.

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/key-results/get?id=KEY_RESULT_ID" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  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.

Parameters:

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

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/key-results/create" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goalId": "GOAL_ID",
    "description": "Grow ARR to $2M",
    "metricName": "ARR",
    "baseline": "1.2M",
    "target": "2M"
  }'
```

Response shape:

```ts
{
  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.

Parameters:

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

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/key-results/update" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "KEY_RESULT_ID",
    "current": "1.4M"
  }'
```

Response shape:

```ts
{
  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.

Parameters:

- `id` (string, required) — Key result id.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/key-results/delete" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "KEY_RESULT_ID"
  }'
```

Response shape:

```ts
{
  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.

Parameters:

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

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/key-results/check-in" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keyResultId": "KEY_RESULT_ID",
    "current": "1.5M",
    "status": "green"
  }'
```

Response shape:

```ts
{
  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.

Parameters:

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

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/key-results/check-in/update" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "CHECK_IN_ID",
    "current": "1.6M"
  }'
```

Response shape:

```ts
{
  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.

Parameters:

- `id` (string, required) — Check-in id.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/key-results/check-in/delete" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "CHECK_IN_ID"
  }'
```

Response shape:

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