Tasks are the unit of work. Goals and projects are the layers above: a way to group tasks into long-running objectives and see progress, spend, and cycle time at a higher altitude. You do not have to use goals or projects; a company can run with nothing but tasks. But once you have more than a dozen concurrent tasks, the planning layer starts to pay off.

​
The hierarchy

Company
  └── Goal (multi-month objective)
        └── Project (scoped initiative)
              └── Task (unit of work)
                    └── Sub-task
                          └── Sub-sub-task
A task can belong to a project directly (skipping the goal), or to nothing at all. A project always belongs to a company; a goal always belongs to a company. Goals and projects do not nest.

​
Endpoints

MethodPathPurpose
GET/v1/companies/{cid}/goalsList goals
POST/v1/companies/{cid}/goalsCreate a goal
GET/v1/companies/{cid}/goals/{id}Get one goal
PATCH/v1/companies/{cid}/goals/{id}Update a goal
POST/v1/companies/{cid}/goals/{id}/closeClose a goal
GET/v1/companies/{cid}/projectsList projects
POST/v1/companies/{cid}/projectsCreate a project
GET/v1/companies/{cid}/projects/{id}Get one project
PATCH/v1/companies/{cid}/projects/{id}Update a project
POST/v1/companies/{cid}/projects/{id}/archiveArchive a project

​
The goal object

{
  "id": "gl_a1b2c3",
  "companyId": "cmp_d4e5f6",
  "title": "Launch AI-native newsletter",
  "description": "Weekly newsletter with agent-generated content.",
  "targetDate": "2026-06-30",
  "status": "active",
  "projectIds": ["prj_g7h8i9", "prj_j0k1l2"],
  "budget": {
    "usd": 2000,
    "spent": { "usd": 642 }
  },
  "progress": {
    "tasksTotal": 48,
    "tasksDone": 23,
    "tasksInFlight": 7,
    "tasksQueued": 18
  },
  "createdAt": "2026-03-01T09:00:00Z",
  "updatedAt": "2026-04-11T10:38:12Z"
}

​
The project object

{
  "id": "prj_g7h8i9",
  "companyId": "cmp_d4e5f6",
  "goalId": "gl_a1b2c3",
  "title": "Newsletter template pipeline",
  "description": "Workflow for turning a brief into a newsletter.",
  "status": "active",
  "leadAgentId": "agt_m3n4o5",
  "labels": ["marketing", "automation"],
  "budget": {
    "usd": 500,
    "spent": { "usd": 212 }
  },
  "progress": {
    "tasksTotal": 12,
    "tasksDone": 7
  },
  "createdAt": "2026-03-05T11:00:00Z",
  "updatedAt": "2026-04-11T10:14:00Z"
}

​
Create a goal

curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/goals \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{
    "title": "Launch AI-native newsletter",
    "description": "Weekly newsletter with agent-generated content.",
    "targetDate": "2026-06-30",
    "budget": { "usd": 2000 }
  }'

​
Create a project under a goal

curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/projects \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{
    "title": "Newsletter template pipeline",
    "goalId": "gl_a1b2c3",
    "leadAgentId": "agt_m3n4o5",
    "budget": { "usd": 500 }
  }'
When creating a task, set projectId: 
curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/issues \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{
    "title": "Draft this week's newsletter",
    "projectId": "prj_g7h8i9",
    "assignedTeamId": "tm_p6q7r8"
  }'
The task’s cost rolls up into the project, which rolls up into the goal.

​
Progress rollups

Progress is computed on every task state transition. You do not have to maintain it by hand. The rollup fields:
  • tasksTotal — all tasks ever created under this goal/project
  • tasksDone — tasks in done state
  • tasksInFlight — tasks in running, review, or handoff
  • tasksQueued — tasks in queued or assigned
  • tasksFailed — excluded from the above; shown separately

​
Closing a goal

curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/goals/gl_a1b2c3/close \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{ "outcome": "shipped", "reflection": "Hit the date with two weeks to spare." }'
Closing a goal:
  • Marks it as closed with the given outcome
  • Prevents new projects from being created under it
  • Existing projects keep running (they can be closed separately)
  • Rolls up the final numbers into the closing record
The goal stays visible in history forever.

​
Archiving a project

curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/projects/prj_g7h8i9/archive \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN"
Archived projects are hidden from default lists but still searchable by ID.

​
Webhooks

EventWhen
goal.createdGoal created
goal.updatedAny goal PATCH
goal.closedGoal closed
project.createdProject created
project.updatedAny project PATCH
project.archivedProject archived

​
Next

  • Issues — the tasks that hang off projects
  • Costs — how spend rolls up from tasks to projects to goals to companies