Chevre REST API Endpoints — Workspaces Reference

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

page

integer

default:"1"

The page number to retrieve. Must be a positive integer.

per_page

integer

default:"20"

The number of workspaces to return per page. Minimum is 1, maximum is 100.

Example request

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"

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())

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);

Example response

200

{
  "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

data

array

An array of workspace objects.

Show workspace object

string

The unique identifier for the workspace, prefixed with ws_.

name

string

The display name of the workspace.

slug

string

The URL-safe identifier for the workspace. Unique across all workspaces.

member_count

integer

The total number of members currently in the workspace.

created_at

string

ISO 8601 timestamp of when the workspace was created.

updated_at

string

ISO 8601 timestamp of the most recent update to the workspace.

Create a workspace

POST https://api.chevre.io/v1/workspaces Creates a new workspace. The authenticated user becomes the workspace owner automatically.

Request body

name

string

required

The display name for the new workspace. Must be between 1 and 255 characters.

slug

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.

timezone

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.

Example request

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"
  }'

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())

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);

Example response

201

{
  "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

data

object

The newly created workspace object.

Show workspace object

string

The unique identifier for the workspace, prefixed with ws_.

name

string

The display name of the workspace.

slug

string

The URL-safe identifier for the workspace.

timezone

string

The IANA timezone identifier assigned to the workspace.

member_count

integer

The number of members in the workspace. Starts at 1 (the creator).

created_at

string

ISO 8601 timestamp of when the workspace was created.

updated_at

string

ISO 8601 timestamp of the most recent update.

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 reference.

Path parameters

string

required

The unique identifier of the workspace whose projects you want to list (e.g. ws_01HXYZ).

Query parameters

page

integer

default:"1"

The page number to retrieve. Must be a positive integer.

per_page

integer

default:"20"

The number of projects to return per page. Minimum is 1, maximum is 100.

archived

boolean

default:"false"

When true, returns only archived projects. When false (the default), returns only active projects.

Example request

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"

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())

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);

Example response

200

{
  "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

data

array

An array of project objects belonging to the workspace.

Show project object

string

The unique identifier for the project, prefixed with proj_.

workspace_id

string

The ID of the workspace this project belongs to.

name

string

The display name of the project.

description

string

An optional description of the project’s purpose.

color

string

The hex color code used to visually identify the project (e.g. #6366f1).

visibility

string

Access level for workspace members. Either "private" (only invited members) or "shared" (all workspace members).

archived

boolean

Whether the project has been archived. Archived projects are read-only.

created_at

string

ISO 8601 timestamp of when the project was created.

updated_at

string

ISO 8601 timestamp of the most recent update.

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

string

required

The unique identifier of the workspace to retrieve (e.g. ws_01HXYZ).

Example request

curl --request GET \
  --url "https://api.chevre.io/v1/workspaces/ws_01HXYZ" \
  --header "Authorization: Bearer <your_api_key>" \
  --header "Accept: application/json"

import requests

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

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);

Example response

200

{
  "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

data

object

The requested workspace object.

Show workspace object

string

The unique identifier for the workspace, prefixed with ws_.

name

string

The display name of the workspace.

slug

string

The URL-safe identifier for the workspace.

timezone

string

The IANA timezone identifier assigned to the workspace.

member_count

integer

The total number of members currently in the workspace.

created_at

string

ISO 8601 timestamp of when the workspace was created.

updated_at

string

ISO 8601 timestamp of the most recent update.

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

string

required

The unique identifier of the workspace to update (e.g. ws_01HXYZ).

Request body

name

string

The new display name for the workspace.

slug

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.

timezone

string

A new IANA timezone identifier (e.g. "Europe/London"). Updating the timezone affects all future scheduled automations but does not reschedule existing ones.

Example request

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"
  }'

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())

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);

Example response

200

{
  "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

data

object

The updated workspace object, reflecting all applied changes.

Show workspace object

string

The unique identifier for the workspace, prefixed with ws_.

name

string

The updated display name of the workspace.

slug

string

The updated or unchanged URL-safe identifier.

timezone

string

The updated or unchanged IANA timezone identifier.

member_count

integer

The total number of members currently in the workspace.

created_at

string

ISO 8601 timestamp of when the workspace was originally created.

updated_at

string

ISO 8601 timestamp of this update.

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.

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.

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

string

required

The unique identifier of the workspace to delete (e.g. ws_01HXYZ).

Example request

curl --request DELETE \
  --url "https://api.chevre.io/v1/workspaces/ws_01HXYZ" \
  --header "Authorization: Bearer <your_api_key>"

import requests

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

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

Example response

204

// No content returned on successful deletion

A successful deletion returns HTTP 204 No Content with an empty response body.

​List workspaces

​Query parameters

​Example request

​Example response

​Response fields

​Create a workspace

​Request body

​Example request

​Example response

​Response fields

​List projects in a workspace

​Path parameters

​Query parameters

​Example request

​Example response

​Response fields

​Get a workspace

​Path parameters

​Example request

​Example response

​Response fields

​Update a workspace

​Path parameters

​Request body

​Example request

​Example response

​Response fields

​Delete a workspace

​Path parameters

​Example request

​Example response

List workspaces

Query parameters

Example request

Example response

Response fields

Create a workspace

Request body

Example request

Example response

Response fields

List projects in a workspace

Path parameters

Query parameters

Example request

Example response

Response fields

Get a workspace

Path parameters

Example request

Example response

Response fields

Update a workspace

Path parameters

Request body

Example request

Example response

Response fields

Delete a workspace

Path parameters

Example request

Example response