> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chevre.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Chevre REST API Endpoints — Projects and Workspaces

> Create, retrieve, update, and delete projects within Chevre workspaces using the REST API. Includes listing projects scoped to a workspace.

Projects are the primary containers for organizing your work within a workspace. Each project holds tasks, automations, and settings scoped to a specific team or initiative. Use the endpoints below to manage projects programmatically. All requests require your API key in the `Authorization` header as `Bearer <your_api_key>`.

***

## List projects in a workspace

**`GET`** **`https://api.chevre.io/v1/workspaces/{workspace_id}/projects`**

Returns a paginated list of all projects in the specified workspace. By default, only active (non-archived) projects are returned. Set `archived=true` to include archived projects instead.

### Path parameters

<ParamField path="workspace_id" type="string" required>
  The unique identifier of the workspace whose projects you want to list (e.g. `ws_01HXYZ`).
</ParamField>

### Query parameters

<ParamField query="page" type="integer" default="1">
  The page number to retrieve. Must be a positive integer.
</ParamField>

<ParamField query="per_page" type="integer" default="20">
  The number of projects to return per page. Minimum is `1`, maximum is `100`.
</ParamField>

<ParamField query="archived" type="boolean" default="false">
  When `true`, returns only archived projects. When `false` (the default), returns only active projects.
</ParamField>

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.chevre.io/v1/workspaces/ws_01HXYZ/projects?page=1&per_page=20&archived=false" \
    --header "Authorization: Bearer <your_api_key>" \
    --header "Accept: application/json"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.chevre.io/v1/workspaces/ws_01HXYZ/projects",
      params={"page": 1, "per_page": 20, "archived": False},
      headers={"Authorization": "Bearer <your_api_key>"},
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.chevre.io/v1/workspaces/ws_01HXYZ/projects?page=1&per_page=20&archived=false",
    {
      headers: {
        Authorization: "Bearer <your_api_key>",
        Accept: "application/json",
      },
    }
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Example response

```json 200 theme={null}
{
  "data": [
    {
      "id": "proj_01ABC",
      "workspace_id": "ws_01HXYZ",
      "name": "Website Redesign",
      "description": "Overhaul of the public-facing marketing website.",
      "color": "#6366f1",
      "visibility": "shared",
      "archived": false,
      "created_at": "2024-02-10T10:00:00Z",
      "updated_at": "2024-05-20T16:30:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20
  }
}
```

### Response fields

<ResponseField name="data" type="array">
  An array of project objects.

  <Expandable title="project object">
    <ResponseField name="id" type="string">
      The unique identifier for the project, prefixed with `proj_`.
    </ResponseField>

    <ResponseField name="workspace_id" type="string">
      The ID of the workspace this project belongs to.
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the project.
    </ResponseField>

    <ResponseField name="description" type="string">
      An optional description of the project's purpose.
    </ResponseField>

    <ResponseField name="color" type="string">
      The hex color code used to visually identify the project (e.g. `#6366f1`).
    </ResponseField>

    <ResponseField name="visibility" type="string">
      Access level for workspace members. Either `"private"` (only invited members) or `"shared"` (all workspace members).
    </ResponseField>

    <ResponseField name="archived" type="boolean">
      Whether the project has been archived. Archived projects are read-only.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the project was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of the most recent update.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Pagination metadata.

  <Expandable title="meta object">
    <ResponseField name="total" type="integer">
      Total number of projects matching the query.
    </ResponseField>

    <ResponseField name="page" type="integer">
      The current page number returned.
    </ResponseField>

    <ResponseField name="per_page" type="integer">
      The number of results per page used for this response.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Create a project

**`POST`** **`https://api.chevre.io/v1/projects`**

Creates a new project inside the specified workspace. The authenticated API key must have at least editor permissions in the target workspace.

### Request body

<ParamField body="workspace_id" type="string" required>
  The ID of the workspace where the project will be created.
</ParamField>

<ParamField body="name" type="string" required>
  The display name for the new project. Must be between 1 and 255 characters.
</ParamField>

<ParamField body="description" type="string">
  An optional description of the project's purpose or scope.
</ParamField>

<ParamField body="color" type="string">
  A hex color code (e.g. `"#6366f1"`) used to visually distinguish the project in the UI. Must be a valid 6-digit hex color including the `#` prefix.
</ParamField>

<ParamField body="visibility" type="string" default="private">
  Controls who in the workspace can see the project. Accepted values:

  * `"private"` — only explicitly invited members can access the project.
  * `"shared"` — all members of the workspace can access the project.
</ParamField>

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url "https://api.chevre.io/v1/projects" \
    --header "Authorization: Bearer <your_api_key>" \
    --header "Content-Type: application/json" \
    --data '{
      "workspace_id": "ws_01HXYZ",
      "name": "Website Redesign",
      "description": "Overhaul of the public-facing marketing website.",
      "color": "#6366f1",
      "visibility": "shared"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.chevre.io/v1/projects",
      json={
          "workspace_id": "ws_01HXYZ",
          "name": "Website Redesign",
          "description": "Overhaul of the public-facing marketing website.",
          "color": "#6366f1",
          "visibility": "shared",
      },
      headers={"Authorization": "Bearer <your_api_key>"},
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.chevre.io/v1/projects", {
    method: "POST",
    headers: {
      Authorization: "Bearer <your_api_key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      workspace_id: "ws_01HXYZ",
      name: "Website Redesign",
      description: "Overhaul of the public-facing marketing website.",
      color: "#6366f1",
      visibility: "shared",
    }),
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Example response

```json 201 theme={null}
{
  "data": {
    "id": "proj_01ABC",
    "workspace_id": "ws_01HXYZ",
    "name": "Website Redesign",
    "description": "Overhaul of the public-facing marketing website.",
    "color": "#6366f1",
    "visibility": "shared",
    "archived": false,
    "created_at": "2024-06-01T14:22:00Z",
    "updated_at": "2024-06-01T14:22:00Z"
  }
}
```

### Response fields

<ResponseField name="data" type="object">
  The newly created project object.

  <Expandable title="project object">
    <ResponseField name="id" type="string">
      The unique identifier for the project, prefixed with `proj_`.
    </ResponseField>

    <ResponseField name="workspace_id" type="string">
      The ID of the workspace this project belongs to.
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the project.
    </ResponseField>

    <ResponseField name="description" type="string">
      The optional description provided at creation.
    </ResponseField>

    <ResponseField name="color" type="string">
      The hex color code assigned to the project.
    </ResponseField>

    <ResponseField name="visibility" type="string">
      Access level: `"private"` or `"shared"`.
    </ResponseField>

    <ResponseField name="archived" type="boolean">
      Always `false` for a newly created project.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the project was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of the most recent update.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Get a project

**`GET`** **`https://api.chevre.io/v1/projects/{id}`**

Retrieves a single project by its ID. You must have access to the project's workspace and the project itself to retrieve it.

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the project to retrieve (e.g. `proj_01ABC`).
</ParamField>

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.chevre.io/v1/projects/proj_01ABC" \
    --header "Authorization: Bearer <your_api_key>" \
    --header "Accept: application/json"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.chevre.io/v1/projects/proj_01ABC",
      headers={"Authorization": "Bearer <your_api_key>"},
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.chevre.io/v1/projects/proj_01ABC",
    {
      headers: {
        Authorization: "Bearer <your_api_key>",
        Accept: "application/json",
      },
    }
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Example response

```json 200 theme={null}
{
  "data": {
    "id": "proj_01ABC",
    "workspace_id": "ws_01HXYZ",
    "name": "Website Redesign",
    "description": "Overhaul of the public-facing marketing website.",
    "color": "#6366f1",
    "visibility": "shared",
    "archived": false,
    "created_at": "2024-02-10T10:00:00Z",
    "updated_at": "2024-05-20T16:30:00Z"
  }
}
```

### Response fields

<ResponseField name="data" type="object">
  The requested project object.

  <Expandable title="project object">
    <ResponseField name="id" type="string">
      The unique identifier for the project, prefixed with `proj_`.
    </ResponseField>

    <ResponseField name="workspace_id" type="string">
      The ID of the workspace this project belongs to.
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the project.
    </ResponseField>

    <ResponseField name="description" type="string">
      The optional description of the project.
    </ResponseField>

    <ResponseField name="color" type="string">
      The hex color code assigned to the project.
    </ResponseField>

    <ResponseField name="visibility" type="string">
      Access level: `"private"` or `"shared"`.
    </ResponseField>

    <ResponseField name="archived" type="boolean">
      Whether the project has been archived.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the project was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of the most recent update.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Update a project

**`PATCH`** **`https://api.chevre.io/v1/projects/{id}`**

Updates one or more fields on an existing project. Send only the fields you want to change — all other fields remain unchanged. To archive a project, set `archived` to `true`.

<Note>
  Archiving a project (`"archived": true`) makes it read-only. All automations within an archived project are automatically paused. Set `"archived": false` to restore the project and re-enable its automations.
</Note>

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the project to update (e.g. `proj_01ABC`).
</ParamField>

### Request body

<ParamField body="name" type="string">
  A new display name for the project.
</ParamField>

<ParamField body="description" type="string">
  An updated description for the project.
</ParamField>

<ParamField body="color" type="string">
  A new hex color code (e.g. `"#10b981"`).
</ParamField>

<ParamField body="visibility" type="string">
  Updated access level. Accepted values: `"private"` or `"shared"`.
</ParamField>

<ParamField body="archived" type="boolean">
  Set to `true` to archive the project, or `false` to restore it.
</ParamField>

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url "https://api.chevre.io/v1/projects/proj_01ABC" \
    --header "Authorization: Bearer <your_api_key>" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "Website Redesign v2",
      "color": "#10b981",
      "visibility": "private"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      "https://api.chevre.io/v1/projects/proj_01ABC",
      json={
          "name": "Website Redesign v2",
          "color": "#10b981",
          "visibility": "private",
      },
      headers={"Authorization": "Bearer <your_api_key>"},
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.chevre.io/v1/projects/proj_01ABC",
    {
      method: "PATCH",
      headers: {
        Authorization: "Bearer <your_api_key>",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Website Redesign v2",
        color: "#10b981",
        visibility: "private",
      }),
    }
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Example response

```json 200 theme={null}
{
  "data": {
    "id": "proj_01ABC",
    "workspace_id": "ws_01HXYZ",
    "name": "Website Redesign v2",
    "description": "Overhaul of the public-facing marketing website.",
    "color": "#10b981",
    "visibility": "private",
    "archived": false,
    "created_at": "2024-02-10T10:00:00Z",
    "updated_at": "2024-06-10T09:15:00Z"
  }
}
```

### Response fields

<ResponseField name="data" type="object">
  The updated project object, reflecting all applied changes.

  <Expandable title="project object">
    <ResponseField name="id" type="string">
      The unique identifier for the project.
    </ResponseField>

    <ResponseField name="workspace_id" type="string">
      The ID of the workspace this project belongs to.
    </ResponseField>

    <ResponseField name="name" type="string">
      The updated display name of the project.
    </ResponseField>

    <ResponseField name="description" type="string">
      The updated or unchanged description.
    </ResponseField>

    <ResponseField name="color" type="string">
      The updated or unchanged hex color code.
    </ResponseField>

    <ResponseField name="visibility" type="string">
      The updated or unchanged access level.
    </ResponseField>

    <ResponseField name="archived" type="boolean">
      The updated archive status of the project.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the project was originally created.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of this update.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Delete a project

**`DELETE`** **`https://api.chevre.io/v1/projects/{id}`**

Permanently deletes a project and all of its contents, including tasks, automations, and settings associated with the project.

<Warning>
  This action is **permanent and irreversible**. All tasks, automations, and data inside the project are immediately and permanently deleted. Consider archiving the project instead if you may need to access its data in the future.
</Warning>

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the project to delete (e.g. `proj_01ABC`).
</ParamField>

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url "https://api.chevre.io/v1/projects/proj_01ABC" \
    --header "Authorization: Bearer <your_api_key>"
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      "https://api.chevre.io/v1/projects/proj_01ABC",
      headers={"Authorization": "Bearer <your_api_key>"},
  )
  print(response.status_code)  # 204
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.chevre.io/v1/projects/proj_01ABC",
    {
      method: "DELETE",
      headers: {
        Authorization: "Bearer <your_api_key>",
      },
    }
  );
  // Successful deletion returns 204 No Content
  console.log(response.status); // 204
  ```
</CodeGroup>

### Example response

```json 204 theme={null}
// No content returned on successful deletion
```

<Note>
  A successful deletion returns HTTP `204 No Content` with an empty response body.
</Note>