Daemion docs

How do I manage projects?

Auth: Bearer token from device pairing
Base URL: http://localhost:3001
All examples tested against live gateway

Projects group threads, agents, and work into named workspaces. Each project has a filesystem path that scopes file operations, and an optional default agent that handles new threads created in that project.

How do I list projects?

GET /projects Auth required

List all projects. Returns active projects by default; pass archived=true to include archived ones.

Parameter Type Description
archived boolean Set to true to return archived (soft-deleted) projects. Defaults to false.
bash
Verified

curl “http://localhost:3001/projects”
-H “Authorization: Bearer $DAEMION_TOKEN”

Response shape:

json

[ { “id”: “ext_09def789”, “name”: “daemion”, “path”: ”~/daemion”, “description”: “Daemion source repo”, “icon”: null, “color”: “#6366f1”, “default_agent”: “sonnet”, “agent_ids”: [“ext_01abc123”], “archived_at”: null, “created_at”: “2026-03-01T10:00:00Z”, “updated_at”: “2026-03-31T08:00:00Z” } ]

The agent_ids array lists agents explicitly linked to this project via the agent_projects join table. default_agent is the agent used when creating new threads in this project.

How do I create a project?

POST /projects Auth required

Create a new project. name and path are required.

Parameter Type Description
name REQUIRED string Display name for the project.
path REQUIRED string Absolute filesystem path the project represents.
description string Short description of the project.
icon string Emoji or icon identifier for display.
color string Hex color for the project badge.
default_agent string Agent ID to use when creating new threads in this project.
bash
Verified

curl -X POST http://localhost:3001/projects
-H “Authorization: Bearer $DAEMION_TOKEN”
-H “Content-Type: application/json”
-d ’{ “name”: “daemion”, “path”: ”~/daemion”, “description”: “Daemion source repo”, “default_agent”: “sonnet”, “color”: “#6366f1” }’

Returns 201 with the created project object. agent_ids will be an empty array on creation.

How do I get a single project?

GET /projects/:id Auth required

Fetch a project by its ID.

bash
Verified

curl “http://localhost:3001/projects/ext_09def789”
-H “Authorization: Bearer $DAEMION_TOKEN”

How do I update a project?

PATCH /projects/:id Auth required

Update any combination of project fields. Only fields you include are changed.

Parameter Type Description
name string New display name.
path string New filesystem path.
description string New description. Pass null to clear.
icon string New icon. Pass null to clear.
color string New hex color. Pass null to clear.
default_agent string New default agent ID.
bash
Verified

curl -X PATCH http://localhost:3001/projects/ext_09def789
-H “Authorization: Bearer $DAEMION_TOKEN”
-H “Content-Type: application/json”
-d ’{ “default_agent”: “opus”, “color”: “#f59e0b” }’

Returns 200 with the full updated project object (without agent_ids).

How do I delete a project?

DELETE /projects/:id Auth required

Soft-delete a project by archiving it. Returns 204 with no body. The project is not permanently removed — it can be retrieved with archived=true.

bash
Verified

curl -X DELETE http://localhost:3001/projects/ext_09def789
-H “Authorization: Bearer $DAEMION_TOKEN”

DELETE is a soft delete. The project is archived, not permanently removed. Retrieve archived projects with GET /projects?archived=true.
Q What is the project path used for?
The path field is a filesystem path on the gateway host that scopes file operations for this project. When an agent opens files within a thread tied to a project, it uses this path as context.
Q What is the difference between default_agent and agent_ids?
default_agent is the agent used automatically when a new thread is created inside this project. agent_ids are agents explicitly linked to the project via the agent_projects join table — typically agents that have worked within it.
Q Can I permanently delete a project?
No. DELETE is a soft delete — the project is archived. This protects thread history. To see archived projects, pass archived=true to GET /projects.
Q Do I need a project to use threads?
No. Projects are optional. Threads exist independently and can be assigned to a project at creation or via PATCH.

What can go wrong

Common errors

400 {"error": "name and path are required"} — POST /projects requires both name and path. Both must be non-empty strings.

400 {"error": "invalid JSON"} — The request body could not be parsed. Make sure your Content-Type: application/json header is set and the body is valid JSON.

404 {"error": "project not found"} — No project with that ID exists (or it has been archived). Use GET /projects?archived=true to check archived projects.

500 {"error": "update failed"} — The PATCH could not write to the database. Check gateway logs for details.

401 {"error": "unauthorized"} — Bearer token is missing or invalid. Re-pair the device to get a fresh token.

What’s next?