Projects API

Response Body (Array)

Fetch all projects to build a workspace selector or dashboard overview:

// List all projects with their task counts
const response: Response = await fetch("http://localhost:3000/api/projects");
const projects: Project[] = await response.json();

// Show active projects with pending work
const active: Project[] = projects.filter((p) => p.status === "active" && p.taskCount > 0);
active.forEach((p) => console.log(`${p.name}: ${p.taskCount} tasks`));

import requests

# List all projects with their task counts
response = requests.get("http://localhost:3000/api/projects")
projects: list[dict] = response.json()

# Show active projects with pending work
active = [p for p in projects if p["status"] == "active" and p["taskCount"] > 0]
for p in active:
  print(f"{p['name']}: {p['taskCount']} tasks")

Example response:

[
  {
    "id": "proj-8f3a-4b2c",
    "name": "Marketing Site Redesign",
    "description": "Q2 redesign of the company marketing site",
    "workingDirectory": "/Users/team/projects/marketing-site",
    "status": "active",
    "taskCount": 12,
    "createdAt": "2026-03-15T09:00:00.000Z",
    "updatedAt": "2026-04-02T14:22:00.000Z"
  },
  {
    "id": "proj-c7d1-9e4f",
    "name": "API Integration Tests",
    "description": "Automated test suite for third-party API integrations",
    "workingDirectory": "/Users/team/projects/api-tests",
    "status": "active",
    "taskCount": 5,
    "createdAt": "2026-03-20T11:30:00.000Z",
    "updatedAt": "2026-04-01T16:45:00.000Z"
  }
]

Request Body

Response 201 Created — New project with status: "active"

Errors: 400 — Zod validation failure

Create a project pointing to a local codebase — Stagent automatically scans the directory for environment details (language, framework, dependencies):

// Create a project with a working directory
// The environment scan starts automatically in the background
const response: Response = await fetch("http://localhost:3000/api/projects", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
  name: "Marketing Site Redesign",
  description: "Q2 redesign initiative",
  workingDirectory: "/Users/team/projects/marketing-site",
}),
});
const project: Project = await response.json();

console.log(project.id);     // "proj-8f3a-4b2c"
console.log(project.status); // "active"

import requests

# Create a project with a working directory
# The environment scan starts automatically in the background
response = requests.post("http://localhost:3000/api/projects", json={
  "name": "Marketing Site Redesign",
  "description": "Q2 redesign initiative",
  "workingDirectory": "/Users/team/projects/marketing-site",
})
project: dict = response.json()

print(project["id"])     # "proj-8f3a-4b2c"
print(project["status"]) # "active"

Example response:

{
  "id": "proj-8f3a-4b2c",
  "name": "Marketing Site Redesign",
  "description": "Q2 redesign initiative",
  "workingDirectory": "/Users/team/projects/marketing-site",
  "status": "active",
  "taskCount": 0,
  "createdAt": "2026-04-03T10:00:00.000Z",
  "updatedAt": "2026-04-03T10:00:00.000Z"
}

Response 200 — Project object

Errors: 404 — { "error": "Not found" }

Fetch a specific project to display its details or check status before creating tasks:

// Fetch a project and check if it's ready for work
const response: Response = await fetch("http://localhost:3000/api/projects/proj-8f3a-4b2c");
const project: Project = await response.json();

if (project.status === "active") {
console.log(`${project.name} is active with ${project.taskCount} tasks`);
}

import requests

# Fetch a project and check if it's ready for work
response = requests.get("http://localhost:3000/api/projects/proj-8f3a-4b2c")
project: dict = response.json()

if project["status"] == "active":
  print(f"{project['name']} is active with {project['taskCount']} tasks")

Request Body (all fields optional)

Response 200 — Updated project object

Errors: 400 — Validation failure, 404 — Not found

Pause a project to prevent task auto-execution while keeping all resources intact:

// Pause a project — tasks remain but won't auto-execute
await fetch("http://localhost:3000/api/projects/proj-8f3a-4b2c", {
method: "PATCH",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ status: "paused" }),
});

import requests

# Pause a project — tasks remain but won't auto-execute
requests.patch("http://localhost:3000/api/projects/proj-8f3a-4b2c", json={
  "status": "paused",
})

Response 200 — { "success": true }

Errors: 404 — Not found, 500 — Cascade delete failure

The cascade deletion order ensures foreign key safety:

1. Environment data (scans, checkpoints, artifacts, sync ops)
2. Chat data (messages, conversations)
3. Usage ledger entries
4. Task children (logs, notifications, documents, context)
5. Document defaults, user tables (with rows, columns, triggers, charts)
6. Direct children (documents, tasks, workflows, schedules)
7. Project record

Delete a project and everything inside it — this is irreversible:

// WARNING: Cascade deletes all tasks, workflows, schedules, and documents
const res: Response = await fetch("http://localhost:3000/api/projects/proj-8f3a-4b2c", {
method: "DELETE",
});
const { success }: { success: boolean } = await res.json();
console.log(success ? "Project deleted" : "Delete failed");

import requests

# WARNING: Cascade deletes all tasks, workflows, schedules, and documents
res = requests.delete("http://localhost:3000/api/projects/proj-8f3a-4b2c")
data: dict = res.json()
print("Project deleted" if data["success"] else "Delete failed")

Response Body (Array)

Retrieve all documents bound to a project — these are automatically available as context for every task in the project:

// List project documents to verify context is configured
const response: Response = await fetch("http://localhost:3000/api/projects/proj-8f3a-4b2c/documents");
const docs: { direction: string; originalName: string; size: number }[] = await response.json();

docs.forEach((d) => {
const sizeKB: string = (d.size / 1024).toFixed(1);
console.log(`[${d.direction}] ${d.originalName} (${sizeKB} KB)`);
});

import requests

# List project documents to verify context is configured
response = requests.get("http://localhost:3000/api/projects/proj-8f3a-4b2c/documents")
docs: list[dict] = response.json()

for d in docs:
  size_kb = d["size"] / 1024
  print(f"[{d['direction']}] {d['originalName']} ({size_kb:.1f} KB)")

Example response:

[
  {
    "id": "doc-brand-guidelines-v3",
    "originalName": "brand-guidelines-v3.pdf",
    "filename": "brand-guidelines-v3-1712145600.pdf",
    "mimeType": "application/pdf",
    "size": 245760,
    "direction": "input",
    "status": "processed",
    "category": "reference"
  }
]

Request Body

Response Body

Errors: 400 — documentIds not an array, 404 — Project not found

Replace the entire set of default documents — previous bindings are removed first, then new ones are created:

// Atomically replace project document bindings
const response: Response = await fetch("http://localhost:3000/api/projects/proj-8f3a-4b2c/documents", {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
  documentIds: ["doc-brand-guidelines-v3", "doc-sitemap-current"],
}),
});
const { updated }: { updated: number } = await response.json();

console.log(`Bound ${updated} documents to project`);

import requests

# Atomically replace project document bindings
response = requests.put("http://localhost:3000/api/projects/proj-8f3a-4b2c/documents", json={
  "documentIds": ["doc-brand-guidelines-v3", "doc-sitemap-current"],
})
data: dict = response.json()

print(f"Bound {data['updated']} documents to project")