Projects group related tasks and define workspaces for code and resources. Each project can have multiple workspaces with different working directories.
The Project Object
Unique identifier for the project
ID of the company this project belongs to
Status: backlog, planned, in_progress, completed, or cancelled
ID of the project lead agent
Target completion date (ISO 8601 date)
ISO 8601 timestamp of creation
ISO 8601 timestamp of last update
List Projects
curl http://localhost:3100/api/companies/{companyId}/projects
[
{
"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}"
{
"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
}
}'
Initial status (defaults to backlog)
Target completion date (ISO 8601 date)
Optional workspace to create with the project
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"
}'
{
"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}
{
"id": "project_abc123",
"name": "Mobile App"
}
Workspaces
Project workspaces define working directories for agents executing tasks.
The Workspace Object
Unique identifier for the workspace
Absolute path to the working directory
Whether this is the primary workspace
ISO 8601 timestamp of creation
List Workspaces
curl http://localhost:3100/api/projects/{projectId}/workspaces
[
{
"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
}'
Absolute path to working directory
Whether this is the primary workspace (defaults to false)
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
}'
Whether this is the primary workspace
{
"id": "workspace_2",
"isPrimary": true,
"updatedAt": "2026-03-04T12:30:00Z"
}
Delete Workspace
curl -X DELETE http://localhost:3100/api/projects/{projectId}/workspaces/{workspaceId}
{
"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."
}
