> ## 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 — Workspaces Reference

> Create and list workspaces, and retrieve projects scoped to a workspace using the Chevre REST API. All endpoints require a valid Bearer token.

Workspaces are the top-level organizational unit in Chevre. Every project, automation, and team member belongs to a workspace. Use the endpoints below to create and manage workspaces programmatically. All requests must include your API key in the `Authorization` header as `Bearer <your_api_key>`.

***

## List workspaces

**`GET`** **`https://api.chevre.io/v1/workspaces`**

Returns a paginated list of all workspaces the authenticated API key has access to. Results are ordered by creation date, newest first.

### 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 workspaces to return per page. Minimum is `1`, maximum is `100`.
</ParamField>

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.chevre.io/v1/workspaces?page=1&per_page=20" \
    --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",
      params={"page": 1, "per_page": 20},
      headers={"Authorization": "Bearer <your_api_key>"},
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.chevre.io/v1/workspaces?page=1&per_page=20",
    {
      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": "ws_01HXYZ",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "member_count": 12,
      "created_at": "2024-01-15T09:00:00Z",
      "updated_at": "2024-06-01T14:22:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20
  }
}
```

### Response fields

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

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

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

    <ResponseField name="slug" type="string">
      The URL-safe identifier for the workspace. Unique across all workspaces.
    </ResponseField>

    <ResponseField name="member_count" type="integer">
      The total number of members currently in the workspace.
    </ResponseField>

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

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

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

  <Expandable title="meta object">
    <ResponseField name="total" type="integer">
      Total number of workspaces accessible to your API key.
    </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 workspace

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

Creates a new workspace. The authenticated user becomes the workspace owner automatically.

### Request body

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

<ParamField body="slug" type="string">
  A URL-safe identifier for the workspace. Must be lowercase, contain only letters, numbers, and hyphens, and be unique across all workspaces. If omitted, Chevre auto-generates a slug from the `name`.
</ParamField>

<ParamField body="timezone" type="string" default="UTC">
  The IANA timezone identifier for the workspace (e.g. `"America/New_York"`). Used as the default timezone for scheduled automations and reports.
</ParamField>

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url "https://api.chevre.io/v1/workspaces" \
    --header "Authorization: Bearer <your_api_key>" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "Acme Corp",
      "slug": "acme-corp",
      "timezone": "America/New_York"
    }'
  ```

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

  response = requests.post(
      "https://api.chevre.io/v1/workspaces",
      json={
          "name": "Acme Corp",
          "slug": "acme-corp",
          "timezone": "America/New_York",
      },
      headers={"Authorization": "Bearer <your_api_key>"},
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.chevre.io/v1/workspaces", {
    method: "POST",
    headers: {
      Authorization: "Bearer <your_api_key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Acme Corp",
      slug: "acme-corp",
      timezone: "America/New_York",
    }),
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Example response

```json 201 theme={null}
{
  "data": {
    "id": "ws_01HXYZ",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "timezone": "America/New_York",
    "member_count": 1,
    "created_at": "2024-06-01T14:22:00Z",
    "updated_at": "2024-06-01T14:22:00Z"
  }
}
```

### Response fields

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

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

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

    <ResponseField name="slug" type="string">
      The URL-safe identifier for the workspace.
    </ResponseField>

    <ResponseField name="timezone" type="string">
      The IANA timezone identifier assigned to the workspace.
    </ResponseField>

    <ResponseField name="member_count" type="integer">
      The number of members in the workspace. Starts at `1` (the creator).
    </ResponseField>

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

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

***

## List projects in a workspace

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

Returns a paginated list of all projects belonging to the specified workspace. This is a convenient shorthand for browsing a workspace's projects without needing to call the Projects endpoints directly. For full project creation and management, see the [Projects](/api-reference/endpoints/projects) reference.

### Path parameters

<ParamField path="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" \
    --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},
      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",
    {
      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 belonging to the workspace.

  <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 for the response.

  <Expandable title="meta object">
    <ResponseField name="total" type="integer">
      Total number of projects in the workspace 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>

***

## Get a workspace

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

Retrieves a single workspace by its ID. You must have access to the workspace to retrieve it.

### Path parameters

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

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.chevre.io/v1/workspaces/ws_01HXYZ" \
    --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",
      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",
    {
      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": "ws_01HXYZ",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "timezone": "America/New_York",
    "member_count": 12,
    "created_at": "2024-01-15T09:00:00Z",
    "updated_at": "2024-06-01T14:22:00Z"
  }
}
```

### Response fields

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

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

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

    <ResponseField name="slug" type="string">
      The URL-safe identifier for the workspace.
    </ResponseField>

    <ResponseField name="timezone" type="string">
      The IANA timezone identifier assigned to the workspace.
    </ResponseField>

    <ResponseField name="member_count" type="integer">
      The total number of members currently in the workspace.
    </ResponseField>

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

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

***

## Update a workspace

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

Updates one or more fields on an existing workspace. Send only the fields you want to change — all other fields remain unchanged.

### Path parameters

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

### Request body

<ParamField body="name" type="string">
  The new display name for the workspace.
</ParamField>

<ParamField body="slug" type="string">
  A new URL-safe identifier for the workspace. Must be unique across all workspaces. Changing a slug immediately invalidates any previously shared workspace URLs.
</ParamField>

<ParamField body="timezone" type="string">
  A new IANA timezone identifier (e.g. `"Europe/London"`). Updating the timezone affects all future scheduled automations but does not reschedule existing ones.
</ParamField>

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url "https://api.chevre.io/v1/workspaces/ws_01HXYZ" \
    --header "Authorization: Bearer <your_api_key>" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "Acme Corporation",
      "timezone": "Europe/London"
    }'
  ```

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

  response = requests.patch(
      "https://api.chevre.io/v1/workspaces/ws_01HXYZ",
      json={"name": "Acme Corporation", "timezone": "Europe/London"},
      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",
    {
      method: "PATCH",
      headers: {
        Authorization: "Bearer <your_api_key>",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Acme Corporation",
        timezone: "Europe/London",
      }),
    }
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Example response

```json 200 theme={null}
{
  "data": {
    "id": "ws_01HXYZ",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "timezone": "Europe/London",
    "member_count": 12,
    "created_at": "2024-01-15T09:00:00Z",
    "updated_at": "2024-06-10T08:45:00Z"
  }
}
```

### Response fields

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

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

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

    <ResponseField name="slug" type="string">
      The updated or unchanged URL-safe identifier.
    </ResponseField>

    <ResponseField name="timezone" type="string">
      The updated or unchanged IANA timezone identifier.
    </ResponseField>

    <ResponseField name="member_count" type="integer">
      The total number of members currently in the workspace.
    </ResponseField>

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

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

***

## Delete a workspace

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

Deletes a workspace and all of its contents, including projects, automations, members, and settings.

<Warning>
  This action is **permanent and irreversible**. Deleting a workspace immediately removes all associated projects, automations, webhooks, and member associations. There is no recovery path. Ensure you have exported any data you need before proceeding.
</Warning>

This endpoint requires your API key to have the **admin** scope on the workspace. Requests authenticated with keys that have read-only or editor scope will receive a `403 Forbidden` response.

### Path parameters

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

### Example request

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

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

  response = requests.delete(
      "https://api.chevre.io/v1/workspaces/ws_01HXYZ",
      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/workspaces/ws_01HXYZ",
    {
      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>