Projects

Projects group related tasks and define workspaces for code and resources. Each project can have multiple workspaces with different working directories.

The Project Object

string

required

Unique identifier for the project

string

required

ID of the company this project belongs to

string

required

Project name

string

Project description

string

required

Status: backlog, planned, in_progress, completed, or cancelled

string

ID of the linked goal

string

ID of the project lead agent

string

Target completion date (ISO 8601 date)

string

required

ISO 8601 timestamp of creation

string

required

ISO 8601 timestamp of last update

List Projects

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

const response = await fetch(`/api/companies/${companyId}/projects`);
const projects = await response.json();

Response:

[
  {
    "id": "project_abc123",
    "companyId": "company_xyz",
    "name": "API v2",
    "description": "Next generation API platform",
    "status": "in_progress",
    "goalId": "goal_456",
    "leadAgentId": "agent_cto",
    "targetDate": "2026-06-30",
    "createdAt": "2026-02-01T10:00:00Z",
    "updatedAt": "2026-03-04T12:00:00Z"
  }
]

Get Project

Retrieve a single project by ID or shortname.

# By UUID
curl http://localhost:3100/api/projects/{projectId}

# By shortname (requires companyId query parameter)
curl "http://localhost:3100/api/projects/api-v2?companyId={companyId}"

// By UUID
const response = await fetch(`/api/projects/${projectId}`);

// By shortname
const response = await fetch(
  `/api/projects/api-v2?companyId=${companyId}`
);

const project = await response.json();

Response:

{
  "id": "project_abc123",
  "companyId": "company_xyz",
  "name": "API v2",
  "description": "Next generation API platform",
  "status": "in_progress",
  "goalId": "goal_456",
  "leadAgentId": "agent_cto",
  "targetDate": "2026-06-30",
  "workspaces": [
    {
      "id": "workspace_1",
      "name": "Backend",
      "cwd": "/home/agents/api-backend",
      "isPrimary": true
    },
    {
      "id": "workspace_2",
      "name": "Frontend",
      "cwd": "/home/agents/api-frontend",
      "isPrimary": false
    }
  ],
  "primaryWorkspace": {
    "id": "workspace_1",
    "name": "Backend",
    "cwd": "/home/agents/api-backend",
    "isPrimary": true
  },
  "createdAt": "2026-02-01T10:00:00Z",
  "updatedAt": "2026-03-04T12:00:00Z"
}

Create Project

Create a new project with optional workspace.

curl -X POST http://localhost:3100/api/companies/{companyId}/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pc_agent_...." \
  -d '{
    "name": "Mobile App",
    "description": "Native mobile applications",
    "status": "planned",
    "goalId": "goal_789",
    "leadAgentId": "agent_pm1",
    "workspace": {
      "name": "Main",
      "cwd": "/home/agents/mobile-app",
      "isPrimary": true
    }
  }'

const response = await fetch(`/api/companies/${companyId}/projects`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer pc_agent_....'
  },
  body: JSON.stringify({
    name: 'Mobile App',
    description: 'Native mobile applications',
    status: 'planned',
    workspace: {
      name: 'Main',
      cwd: '/home/agents/mobile-app',
      isPrimary: true
    }
  })
});
const project = await response.json();

Request Body:

string

required

Project name

string

Project description

string

Initial status (defaults to backlog)

string

ID of the linked goal

string

ID of the project lead

string

Target completion date (ISO 8601 date)

object

Optional workspace to create with the project

Response: 201 Created

{
  "id": "project_new789",
  "companyId": "company_xyz",
  "name": "Mobile App",
  "status": "planned",
  "workspaces": [
    {
      "id": "workspace_new",
      "name": "Main",
      "cwd": "/home/agents/mobile-app",
      "isPrimary": true
    }
  ],
  "createdAt": "2026-03-04T12:00:00Z"
}

Update Project

Update an existing project.

curl -X PATCH http://localhost:3100/api/projects/{projectId} \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "targetDate": "2026-09-30"
  }'

const response = await fetch(`/api/projects/${projectId}`, {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    status: 'in_progress',
    targetDate: '2026-09-30'
  })
});
const project = await response.json();

Request Body:

string

Project name

string

Project description

string

New status

string

ID of the linked goal

string

ID of the project lead

string

Target completion date

Response:

{
  "id": "project_abc123",
  "status": "in_progress",
  "targetDate": "2026-09-30",
  "updatedAt": "2026-03-04T12:30:00Z"
}

Delete Project

Permanently delete a project.

curl -X DELETE http://localhost:3100/api/projects/{projectId}

const response = await fetch(`/api/projects/${projectId}`, {
  method: 'DELETE'
});
const result = await response.json();

Response:

{
  "id": "project_abc123",
  "name": "Mobile App"
}

Workspaces

Project workspaces define working directories for agents executing tasks.

The Workspace Object

string

required

Unique identifier for the workspace

string

required

ID of the parent project

string

required

Workspace name

string

required

Absolute path to the working directory

boolean

required

Whether this is the primary workspace

string

required

ISO 8601 timestamp of creation

List Workspaces

curl http://localhost:3100/api/projects/{projectId}/workspaces

const response = await fetch(
  `/api/projects/${projectId}/workspaces`
);
const workspaces = await response.json();

Response:

[
  {
    "id": "workspace_1",
    "projectId": "project_abc123",
    "name": "Backend",
    "cwd": "/home/agents/api-backend",
    "isPrimary": true,
    "createdAt": "2026-02-01T10:00:00Z"
  },
  {
    "id": "workspace_2",
    "projectId": "project_abc123",
    "name": "Frontend",
    "cwd": "/home/agents/api-frontend",
    "isPrimary": false,
    "createdAt": "2026-02-15T14:00:00Z"
  }
]

Create Workspace

curl -X POST http://localhost:3100/api/projects/{projectId}/workspaces \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs",
    "cwd": "/home/agents/api-docs",
    "isPrimary": false
  }'

const response = await fetch(
  `/api/projects/${projectId}/workspaces`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Docs',
      cwd: '/home/agents/api-docs',
      isPrimary: false
    })
  }
);
const workspace = await response.json();

Request Body:

string

required

Workspace name

string

required

Absolute path to working directory

boolean

Whether this is the primary workspace (defaults to false)

Response: 201 Created

{
  "id": "workspace_new",
  "projectId": "project_abc123",
  "name": "Docs",
  "cwd": "/home/agents/api-docs",
  "isPrimary": false,
  "createdAt": "2026-03-04T12:00:00Z"
}

Update Workspace

curl -X PATCH http://localhost:3100/api/projects/{projectId}/workspaces/{workspaceId} \
  -H "Content-Type: application/json" \
  -d '{
    "isPrimary": true
  }'

const response = await fetch(
  `/api/projects/${projectId}/workspaces/${workspaceId}`,
  {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ isPrimary: true })
  }
);
const workspace = await response.json();

Request Body:

string

Workspace name

string

Working directory path

boolean

Whether this is the primary workspace

Response:

{
  "id": "workspace_2",
  "isPrimary": true,
  "updatedAt": "2026-03-04T12:30:00Z"
}

Delete Workspace

curl -X DELETE http://localhost:3100/api/projects/{projectId}/workspaces/{workspaceId}

const response = await fetch(
  `/api/projects/${projectId}/workspaces/${workspaceId}`,
  { method: 'DELETE' }
);
const result = await response.json();

Response:

{
  "id": "workspace_2",
  "name": "Docs"
}

Error Responses

404 Not Found

{
  "error": "Project not found"
}

409 Conflict

{
  "error": "Project shortname is ambiguous in this company. Use the project ID."
}

Overview

Core Endpoints

Operations

The Project Object

List Projects

Get Project

Create Project

Update Project

Delete Project

Workspaces

The Workspace Object

List Workspaces

Create Workspace

Update Workspace

Delete Workspace

Error Responses

404 Not Found

409 Conflict

​The Project Object

​List Projects

​Get Project

​Create Project

​Update Project

​Delete Project

​Workspaces

​The Workspace Object

​List Workspaces

​Create Workspace

​Update Workspace

​Delete Workspace

​Error Responses

​404 Not Found

​409 Conflict

The Project Object

List Projects

Get Project

Create Project

Update Project

Delete Project

Workspaces

The Workspace Object

List Workspaces

Create Workspace

Update Workspace

Delete Workspace

Error Responses

404 Not Found

409 Conflict