> ## Documentation Index
> Fetch the complete documentation index at: https://cofounder.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Goals

> CRUD for the north-star targets your co-founder prioritizes toward and tracks pace against.

```
GET    /v1/cofounder/goals
POST   /v1/cofounder/goals
PATCH  /v1/cofounder/goals/:goalId
DELETE /v1/cofounder/goals/:goalId
```

Goals are per-owner targets (a metric + a deadline). See the [Goals & OKRs capability](../capabilities/goals-okr) for how the agent uses them. All endpoints filter by your `owner_email`.

## GET — list goals

Optional `appId` and `status` (`active` | `achieved` | `missed` | `archived`) filters.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/cofounder/goals?status=active" -H "X-API-Key: $KEY"
```

Each goal includes a **computed `pace`** object (authoritative — do not recompute client-side):

```jsonc theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "goals": [
      {
        "id": "uuid",
        "ownerEmail": "you@example.com",
        "scope": "app",
        "appId": "6479581124",
        "label": "Q3 MRR",
        "metric": "mrr",
        "targetValue": 10000,
        "baselineValue": 3200,
        "currentValue": 5100,
        "deadline": "2026-09-30",
        "status": "active",
        "offTrack": false,
        "lastProgressAt": "2026-07-19T08:00:00Z",
        "createdAt": "2026-06-01T00:00:00Z",
        "updatedAt": "2026-07-19T08:00:00Z",
        "pace": {
          "progressFraction": 0.28,
          "timeFraction": 0.42,
          "projectedValue": 7600,
          "onTrack": false,
          "daysToDeadline": 72,
          "projectedMissDays": 34
        }
      }
    ]
  }
}
```

## POST — create a goal

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/cofounder/goals \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "scope": "app",
    "appId": "6479581124",
    "label": "Q3 MRR",
    "metric": "mrr",
    "targetValue": 10000,
    "baselineValue": 3200,
    "deadline": "2026-09-30"
  }'
```

| Field           | Required        | Notes                                                     |
| --------------- | --------------- | --------------------------------------------------------- |
| `scope`         | –               | `app` (default) or `portfolio`                            |
| `appId`         | for `app` scope | The app the goal belongs to                               |
| `metric`        | ✓               | `mrr`, `revenue`, `downloads`, `dau`, `ltv_cac`, `custom` |
| `targetValue`   | ✓               | Must be a finite number                                   |
| `deadline`      | ✓               | `YYYY-MM-DD`                                              |
| `baselineValue` | –               | Starting value; defaults to `0`                           |
| `label`         | –               | ≤120 chars                                                |

Returns `{ "data": { "goal": {...} } }` with `201`. A duplicate active goal returns `409`.

## PATCH — update a goal

Send only the fields you want to change:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH https://api.appeeky.com/v1/cofounder/goals/<goalId> \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{ "currentValue": 5100 }'
```

Accepted keys: `label`, `targetValue`, `baselineValue`, `currentValue`, `deadline`, `status`. Setting `currentValue` is how you update pace for manual metrics (`mrr`, `dau`, `ltv_cac`, `custom`). Returns the updated `{ goal }`, or `404` if not found.

## DELETE — archive a goal

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X DELETE https://api.appeeky.com/v1/cofounder/goals/<goalId> -H "X-API-Key: $KEY"
```

Archives (never hard-deletes) — progress history in `cofounder_goal_progress` is preserved.

```jsonc theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "data": { "id": "uuid", "status": "archived" } }
```

## Auto-updated metrics

`downloads` and `revenue` app-scoped goals update automatically from each run's report (`health.downloadsLast7d` / `health.revenueLast7d`). When a goal crosses into off-track, a [`goal_offtrack` signal](../concepts/signals) fires once on the transition.