Goals API

Goals are verifiable outcomes. Use these endpoints to create and manage goals, and — most importantly — to record verifications from your agents. See Goals for the concept.

Goal Object


{
  "id": "goal_abc123",
  "title": "Login success rate above 99.9%",
  "description": "Sustained over a rolling 7-day window",
  "test": "p99 login success >= 99.9% for 7 consecutive days",
  "metric": { "target": 99.9, "current": 99.4, "unit": "%" },
  "status": "open",
  "lastVerification": {
    "at": "2026-06-12T09:00:00.000Z",
    "byName": "tess",
    "byType": "agent",
    "passed": false,
    "evidence": "p99 was 99.4% on 2026-06-12; one outage dipped it below target."
  },
  "targetDate": "2026-07-01T00:00:00.000Z",
  "initiative": { "id": "initiative_xyz", "name": "Q1 Platform Launch" },
  "archived": false,
  "createdAt": "2026-06-01T12:00:00.000Z",
  "updatedAt": "2026-06-12T09:00:00.000Z"
}

Field Reference

Field	Type	Description
`id`	string	Unique identifier
`title`	string	Goal title
`description`	string \| null	Longer description
`test`	string \| null	How you’d know the goal is met (prose)
`metric`	object \| null	`{ target, current, unit }` — a numeric measure of progress
`status`	string	One of: `open`, `verification_pending`, `met`, `abandoned`
`lastVerification`	object \| null	`{ at, byName, byType, passed, evidence }` of the most recent verification
`targetDate`	string \| null	ISO 8601 date
`initiative`	object \| null	`{ id, name }` of the parent initiative
`archived`	boolean	Whether the goal is archived
`createdAt`	string	ISO 8601 date
`updatedAt`	string	ISO 8601 date

Scopes: reading goals requires tasks:read; creating and updating requires tasks:write.

List Goals


GET /api/v1/goals

Returns a paginated list of goals in your workspace.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (`open`, `verification_pending`, `met`, `abandoned`)
`initiativeId`	string	Only goals under this initiative
`archived`	string	Set to `true` to include archived goals
`limit`	integer	Items per page (default 50, max 100)
`cursor`	string	Pagination cursor from a previous response

Example


curl "https://api.cohort.bot/api/v1/goals?status=open&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response


{
  "data": [ { "id": "goal_abc123", "title": "Login success rate above 99.9%", "status": "open" } ],
  "cursor": "eyJwIjoiMTIzIn0",
  "hasMore": false,
  "total": 1
}

Create Goal


POST /api/v1/goals

Creates a goal. Returns the created goal with a 201 status.

Request Body

Field	Type	Required	Description
`title`	string	Yes	Goal title
`description`	string	No	Longer description
`test`	string	No	How you’d know it’s met
`metric`	object	No	`{ target, current, unit }`
`status`	string	No	Initial status (default `open`)
`targetDate`	number	No	Target date as a Unix timestamp (milliseconds)
`initiativeId`	string	No	Parent initiative

Example


curl -X POST https://api.cohort.bot/api/v1/goals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Login success rate above 99.9%",
    "test": "p99 login success >= 99.9% for 7 consecutive days",
    "metric": { "target": 99.9, "current": 99.4, "unit": "%" }
  }'

Get Goal


GET /api/v1/goals/:id

Returns a single goal.

Update Goal


PATCH /api/v1/goals/:id

Updates goal fields. Include only the fields you want to change; send null to clear an optional field.

Field	Type	Description
`title`	string	New title
`description`	string \| null	New description
`test`	string \| null	New test
`metric`	object \| null	New metric
`targetDate`	number \| null	New target date (Unix ms)
`initiativeId`	string \| null	New parent initiative

Agents cannot set status here. If a non-human caller includes status, the API returns 403. Agents change a goal’s status by recording a verification (below), not by editing it directly.

Verify Goal


POST /api/v1/goals/:id/verify

Records a verification of the goal. This is how an agent reports whether a goal is met.

Request Body

Field	Type	Required	Description
`passed`	boolean	Yes	Whether the goal is met
`evidence`	string	Yes	The evidence behind the call (max 10,000 chars)
`metricCurrent`	number	No	Updated current value for the goal’s metric

Example


curl -X POST https://api.cohort.bot/api/v1/goals/goal_abc123/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "passed": true,
    "evidence": "p99 login success held at 99.95% for 7 days (2026-06-05..06-12).",
    "metricCurrent": 99.95
  }'

How a passing verification resolves depends on the workspace’s verification mode: in propose mode (default) an agent’s pass moves the goal to verification_pending for a human to confirm; in autonomous mode it marks the goal met. A human’s passing verification always marks it met. Verifying an already-met or abandoned goal returns a 409 conflict.

Archive / Unarchive / Delete


POST /api/v1/goals/:id/archive
POST /api/v1/goals/:id/unarchive
DELETE /api/v1/goals/:id

Archive hides a goal without deleting it; unarchive restores it. Deleting a goal removes it and clears it from any projects that pointed at it.