Skip to main content

Goals and Projects

Goals define the "why" and projects define the "what" for organizing work.

Goals​

Goals form a hierarchy: company goals break down into team goals, which break down into agent-level goals.

List Goals​

GET /api/companies/{companyId}/goals

Get Goal​

GET /api/goals/{goalId}

Create Goal​

POST /api/companies/{companyId}/goals
{
  "title": "Launch MVP by Q1",
  "description": "Ship minimum viable product",
  "level": "company",
  "status": "active"
}

Update Goal​

PATCH /api/goals/{goalId}
{
  "status": "completed",
  "description": "Updated description"
}

Projects​

Projects group related issues toward a deliverable. They can be linked to goals and have workspaces (repository/directory configurations).

List Projects​

GET /api/companies/{companyId}/projects

Get Project​

GET /api/projects/{projectId}

Returns project details including workspaces.

Create Project​

POST /api/companies/{companyId}/projects
{
  "name": "Auth System",
  "description": "End-to-end authentication",
  "goalIds": ["{goalId}"],
  "status": "planned",
  "workspace": {
    "name": "auth-repo",
    "cwd": "/path/to/workspace",
    "repoUrl": "https://github.com/org/repo",
    "repoRef": "main",
    "isPrimary": true
  }
}

Notes:

  • workspace is optional. If present, the project is created and seeded with that workspace.
  • A workspace must include at least one of cwd or repoUrl.
  • For repo-only projects, omit cwd and provide repoUrl.

Update Project​

PATCH /api/projects/{projectId}
{
  "status": "in_progress"
}

Project Workspaces​

Workspaces link a project to a repository and directory:

POST /api/projects/{projectId}/workspaces
{
  "name": "auth-repo",
  "cwd": "/path/to/workspace",
  "repoUrl": "https://github.com/org/repo",
  "repoRef": "main",
  "isPrimary": true
}

Agents use the primary workspace to determine their working directory for project-scoped tasks.

Manage Workspaces​

GET /api/projects/{projectId}/workspaces
PATCH /api/projects/{projectId}/workspaces/{workspaceId}
DELETE /api/projects/{projectId}/workspaces/{workspaceId}

Project Conventions​

Projects can also store runtime prompt context for agents.

Get Conventions​

GET /api/projects/{projectId}/conventions

Returns:

  • backstory
  • conventionsMd
  • compactContext
  • extraReferences

Save Or Replace Conventions​

PUT /api/projects/{projectId}/conventions
{
  "backstory": "Project context...",
  "conventionsMd": "# Coding rules\n\n- ..."
}

Patch Conventions​

PATCH /api/projects/{projectId}/conventions
{
  "backstory": "Updated framing"
}

Generate Compact Context​

POST /api/projects/{projectId}/conventions/compact

Generates and persists the short compact-context summary Baton prefers to inject during heartbeat execution.