# Projects

> Projects are named folders inside a workspace for chats, agents and other resources. A resource without projectid sits in the workspace root.

**URL:** https://inference.sh/docs/api/rest/projects
**Last updated:** 2026-10-31

---

Projects are named folders inside a workspace for chats, agents and other resources. A resource without `project_id` sits in the workspace root.

`project_id` on a chat or agent says which project it is filed in. It is unrelated to a [per-chat context](/docs/api/agent/template#per-chat-context) variable that happens to be named `project_id`.

---

## Scopes

| Scope | Access |
|-------|--------|
| `projects:read` | List and get projects, and file a chat in one |
| `projects:write` | Create, update and delete projects |

The `standard` key preset holds both. The [`run-only` preset](/docs/api/rest/api-keys#preset-bundles) holds `projects:read`, so chats it starts can be filed in a project.

---

## Endpoints

| Method | Path | Scope | Purpose |
|--------|------|-------|---------|
| `GET` | `/projects` | `projects:read` | List projects |
| `POST` | `/projects/list` | `projects:read` | List projects (JSON body) |
| `GET` | `/projects/{id}` | `projects:read` | Get a project |
| `POST` | `/projects` | `projects:write` | Create a project |
| `PATCH` | `/projects/{id}` | `projects:write` | Update the fields you send |
| `POST` | `/projects/{id}` | `projects:write` | Update |
| `DELETE` | `/projects/{id}` | `projects:write` | Delete |

Lists use [cursor pagination](/docs/api/rest/overview#cursor-pagination).

---

## Project object

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Project ID |
| `name` | string | Display name |
| `description` | string | Longer text |
| `type` | string | `agent`, `app`, `flow` or `other` (default `other`) |
| `color` | string | UI color |
| `icon` | string | Icon key |

Responses also carry the usual record and permission fields (`created_at`, `updated_at`, `user_id`, `team_id`, `visibility`, …).

Create and update accept `name`, `description`, `type`, `color` and `icon`.

```bash
curl -X POST https://api.inference.sh/projects \
  -H "Authorization: Bearer inf_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q4 launch", "type": "agent"}'
```

---

## Filing resources

| Resource | How |
|----------|-----|
| Chat | `project_id` on [Create chat](/docs/api/rest/agents#create-chat) or on [Run agent](/docs/api/rest/agents#run-agent-recommended) when it creates the chat; [Set chat project](/docs/api/rest/agents#set-chat-project) afterwards. Sub-agent chats and branches keep their parent's project |
| Agent | `project_id` on [Create or update agent template](/docs/api/rest/agents#create-or-update-agent-template); [Move agent to project](/docs/api/rest/agents#move-agent-to-project) afterwards |

Filter [List chats](/docs/api/rest/agents#list-chats) with `project_id` to list one project's chats.

**JavaScript SDK:** `client.projects` has `list`, `get`, `create`, `update` and `delete`. **Python SDK:** call the routes over HTTP and type them with `ProjectDTO` and `ProjectType` from `inferencesh.types`.