Projects API

The Projects API lets you create automation projects, generate execution plans, approve or cancel runs, and inspect task progress. All endpoints are relative to the base path /api/projects.

Tip

For project management, use the Projects page in the Snippbot UI.

Endpoints

Method	Path	Description
GET	/api/projects	List all projects
POST	/api/projects	Create a project
GET	/api/projects/{id}	Get a single project
PUT	/api/projects/{id}	Update a project
DELETE	/api/projects/{id}	Delete a project
GET	/api/projects/{id}/plan	Get the execution plan
POST	/api/projects/{id}/generate-plan	Generate an execution plan
POST	/api/projects/{id}/regenerate-plan	Regenerate the plan
POST	/api/projects/{id}/approve	Approve a pending project plan
POST	/api/projects/{id}/cancel	Cancel a running or pending project
GET	/api/projects/{id}/tasks	List tasks for a project
POST	/api/projects/{id}/tasks	Create a task

Note

Many additional sub-endpoints exist for project files, phases, metrics, docs generation, audit, etc. This page documents the primary endpoints. See the source code for the complete list.

---

List Projects

GET /api/projects

Returns all projects ordered by created_at descending.

Query Parameters

Parameter	Type	Default	Description
status	string	—	Filter by status (e.g. running, completed). Use all to clear filter
search	string	—	Search projects by name or description
sort_by	string	newest	Sort order
limit	integer	20	Maximum number of results (max 200)
offset	integer	0	Pagination offset

Response

{
  "projects": [
    {
      "id": "proj_01j9abc123",
      "name": "Weekly Report Automation",
      "description": "Gather metrics, write summary, email stakeholders",
      "status": "running",
      "created_at": "2026-02-28T09:00:00Z",
      "updated_at": "2026-02-28T09:05:12Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0,
  "status_counts": {
    "pending": 2,
    "running": 1,
    "completed": 5,
    "failed": 0,
    "cancelled": 1
  }
}

---

Create Project

POST /api/projects

Creates a new project.

Request Body

Field	Type	Required	Description
name	string	No	Human-readable project name (defaults to “Untitled”)
description	string	No	Project description
strategy	string	No	Execution strategy (default: performance)
auto_approve_plan	boolean	No	Skip manual plan approval (default: false)
auto_approve_phases	boolean	No	Auto-approve phase transitions (default: true)
decision_mode	string	No	Decision mode: agent or human (default: agent)
path	string	No	Workspace path for the project
agent_id	string	No	Agent to assign to the project
sme_archetype	string	No	Subject matter expert archetype

Response

Returns the created project object with status 201 Created.

---

Get Project

GET /api/projects/{id}

Returns a single project including its full task plan.

---

Update Project

PUT /api/projects/{id}

Updates an existing project’s fields.

---

Delete Project

DELETE /api/projects/{id}

Permanently deletes a project and all associated tasks.

Caution

This action is irreversible. All task history and outputs are permanently removed.

---

Get Plan

GET /api/projects/{id}/plan

Returns the current execution plan for a project.

---

Generate Plan

POST /api/projects/{id}/generate-plan

Generates an initial execution plan for the project. The project must not already have a plan.

---

Regenerate Plan

POST /api/projects/{id}/regenerate-plan

Regenerates the execution plan for an existing project. The project status resets to pending after a new plan is generated.

---

Approve Project

POST /api/projects/{id}/approve

Approves a pending project plan and starts execution.

Response

{
  "id": "proj_01j9xyz789",
  "status": "running",
  "updated_at": "2026-03-02T10:01:00Z"
}

---

Cancel Project

POST /api/projects/{id}/cancel

Cancels a pending or running project. In-progress tasks are interrupted; already-completed tasks remain in the record.

---

List Project Tasks

GET /api/projects/{id}/tasks

Returns all tasks for a project with current status and outputs.

---

Additional Project Endpoints

The following endpoints also exist for projects:

Method	Path	Description
POST	/api/projects/{id}/duplicate	Duplicate a project
GET	/api/projects/{id}/dag	Get the task DAG
POST	/api/projects/batch/delete	Batch delete projects
GET	/api/projects/{id}/phases	List phases
POST	/api/projects/{id}/phases	Add a phase
GET	/api/projects/{id}/events	Stream project events (SSE)
GET	/api/projects/{id}/metrics	Get project metrics
POST	/api/projects/{id}/refine-plan	Refine the plan
POST	/api/projects/{id}/audit	Run project audit
GET	/api/projects/{id}/output-files	Get output files
POST	/api/projects/{id}/files/upload	Upload a project file
GET	/api/projects/{id}/files/raw	Serve a raw project file
GET	/api/projects/{id}/download	Download project