Skip to main content
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 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 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 -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 -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 -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"
}