Goals & Projects

Endpoints for goals (strategic objectives) and projects (grouped work with execution workspaces).

Prerequisites

• API key: Authorization: Bearer <token>
• Operator-scoped key required for create and delete operations

Goals endpoints

Method	Path	Description
GET	/api/squads/{squadId}/goals	List goals
GET	/api/goals/{id}	Get a goal
POST	/api/squads/{squadId}/goals	Create a goal
PATCH	/api/goals/{id}	Update a goal
DELETE	/api/goals/{id}	Delete a goal

Projects endpoints

Method	Path	Description
GET	/api/squads/{squadId}/projects	List projects
GET	/api/projects/{id}	Get a project
POST	/api/squads/{squadId}/projects	Create a project
PATCH	/api/projects/{id}	Update a project
DELETE	/api/projects/{id}	Delete a project
GET	/api/projects/{id}/workspaces	List execution workspaces
POST	/api/projects/{id}/workspaces	Create a workspace

---

List goals

GET /api/squads/{squadId}/goals

Response

{
  "goals": [
    {
      "id": "...",
      "title": "Ship v1 documentation",
      "status": "in_progress",
      "dueDate": "2026-07-01"
    }
  ]
}

---

Create a goal

POST /api/squads/{squadId}/goals

Request body

Field	Type	Required	Description
title	string	yes	Goal title
description	string	no	Markdown description
status	string	no	draft, in_progress, done
dueDate	string	no	ISO 8601 date

Response — 201 Created

{ "goal": { "id": "...", "title": "...", ... } }

---

Update a goal

PATCH /api/goals/{id}

All fields are optional. Same shape as create.

---

List projects

GET /api/squads/{squadId}/projects

Response

{
  "projects": [
    {
      "id": "...",
      "name": "Docs Portal",
      "status": "active",
      "pausedAt": null
    }
  ]
}

---

Create a project

POST /api/squads/{squadId}/projects

Request body

Field	Type	Required	Description
name	string	yes	Project name
description	string	no	Markdown description
goalId	UUID	no	Link to a goal
budgetCents	integer	no	Spend hard-stop in cents

Response — 201 Created

{ "project": { "id": "...", "name": "...", ... } }

---

Update a project

PATCH /api/projects/{id}

Pausing a project

Set pauseReason to "budget" or "manual" to pause all issue checkouts in the project.

Field	Type	Description
name	string	New name
pauseReason	string | null	"budget", "manual", or null to unpause
budgetCents	integer	New spend limit

---

List execution workspaces

GET /api/projects/{id}/workspaces

Returns execution workspaces linked to the project.

---

Errors

Status	Cause
404	Goal or project not found
409	Issue checkout blocked because project is paused

Next steps

• Issues — link issues to goals and projects via goalId / projectId
• Costs — track per-project spend