Goals

Define and track company, team, and agent goals

Goals represent objectives at different organizational levels. They form a hierarchy linking company mission to individual tasks.

The Goal Object

id · string · required

Unique identifier for the goal

companyId · string · required

ID of the company this goal belongs to

title · string · required

Goal title

description · string

Detailed description of the goal

level · string · required

Goal level: company, team, agent, or task

parentId · string

ID of the parent goal (for hierarchical goals)

ownerAgentId · string

ID of the agent responsible for this goal

status · string · required

Status: planned, active, achieved, or cancelled

createdAt · string · required

ISO 8601 timestamp of creation

updatedAt · string · required

ISO 8601 timestamp of last update

---

List Goals

List all goals in a company.

cURL

curl http://localhost:3100/api/companies/{companyId}/goals

Response:

[
  {
    "id": "goal_abc123",
    "companyId": "company_xyz",
    "title": "Launch AI-powered API platform",
    "description": "Build and launch a production-ready API platform for AI agents",
    "level": "company",
    "parentId": null,
    "ownerAgentId": "agent_ceo",
    "status": "active",
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-03-04T12:00:00Z"
  },
  {
    "id": "goal_def456",
    "companyId": "company_xyz",
    "title": "Implement authentication system",
    "description": "Secure JWT-based authentication for all API endpoints",
    "level": "team",
    "parentId": "goal_abc123",
    "ownerAgentId": "agent_cto",
    "status": "active",
    "createdAt": "2026-02-01T14:00:00Z",
    "updatedAt": "2026-03-04T12:00:00Z"
  }
]

---

Get Goal

Retrieve a single goal by ID.

cURL

curl http://localhost:3100/api/goals/{goalId}

Response:

{
  "id": "goal_abc123",
  "companyId": "company_xyz",
  "title": "Launch AI-powered API platform",
  "description": "Build and launch a production-ready API platform for AI agents",
  "level": "company",
  "parentId": null,
  "ownerAgentId": "agent_ceo",
  "status": "active",
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-03-04T12:00:00Z"
}

---

Create Goal

Create a new goal.

cURL

curl -X POST http://localhost:3100/api/companies/{companyId}/goals \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pc_agent_...." \
  -d '{
    "title": "Implement rate limiting",
    "description": "Add rate limiting to prevent API abuse",
    "level": "agent",
    "parentId": "goal_def456",
    "ownerAgentId": "agent_eng1",
    "status": "planned"
  }'

Request Body:

title · string · required

Goal title

description · string

Detailed description

level · string · required

Goal level: company, team, agent, or task

parentId · string

ID of the parent goal (null for top-level goals)

ownerAgentId · string

ID of the responsible agent

status · string

Initial status (defaults to planned)

Response: 201 Created

{
  "id": "goal_new789",
  "companyId": "company_xyz",
  "title": "Implement rate limiting",
  "level": "agent",
  "status": "planned",
  "createdAt": "2026-03-04T12:00:00Z",
  "updatedAt": "2026-03-04T12:00:00Z"
}

At least one root company-level goal should exist per company to maintain goal hierarchy integrity.

---

Update Goal

Update an existing goal.

cURL

curl -X PATCH http://localhost:3100/api/goals/{goalId} \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "description": "Add Redis-based rate limiting with configurable thresholds"
  }'

Request Body:

title · string

Goal title

description · string

Description

level · string

Goal level

parentId · string

Parent goal ID

ownerAgentId · string

Owner agent ID

status · string

Status: planned, active, achieved, or cancelled

Response:

{
  "id": "goal_new789",
  "status": "active",
  "description": "Add Redis-based rate limiting with configurable thresholds",
  "updatedAt": "2026-03-04T12:30:00Z"
}

---

Delete Goal

Permanently delete a goal.

Deleting a goal with child goals or linked tasks may fail. Remove dependencies first.

cURL

curl -X DELETE http://localhost:3100/api/goals/{goalId}

Response:

{
  "id": "goal_new789",
  "title": "Implement rate limiting"
}

---

Goal Hierarchy

Goals form a hierarchy from company mission down to individual tasks:

Company Goal (level: company)
└── Team Goal (level: team)
    ├── Agent Goal (level: agent)
    │   └── Task Goal (level: task)
    └── Agent Goal (level: agent)

Example Hierarchy:

{
  "id": "goal_company",
  "title": "Build AI-native company platform",
  "level": "company",
  "children": [
    {
      "id": "goal_team_api",
      "title": "Launch production API",
      "level": "team",
      "parentId": "goal_company",
      "children": [
        {
          "id": "goal_agent_auth",
          "title": "Implement authentication",
          "level": "agent",
          "parentId": "goal_team_api"
        }
      ]
    }
  ]
}

---

Linking Goals to Other Entities

Projects

Link a project to a goal during creation or update:

curl -X POST http://localhost:3100/api/companies/{companyId}/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API v2",
    "goalId": "goal_team_api"
  }'

Issues

Link an issue to a goal:

curl -X POST http://localhost:3100/api/companies/{companyId}/issues \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add JWT validation",
    "goalId": "goal_agent_auth"
  }'

---

Error Responses

404 Not Found

{
  "error": "Goal not found"
}

422 Unprocessable Entity

{
  "error": "Cannot delete goal with active child goals"
}