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

integer

default:"1"

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

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

array

An array of workspace objects.

Show workspace object

string

The unique identifier for the workspace, prefixed with ws_.

string

The display name of the workspace.

string

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

integer

The total number of members currently in the workspace.

string

ISO 8601 timestamp of when the workspace was created.

string

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

object

Pagination metadata for the response.

Show meta object

integer

Total number of workspaces accessible to your API key.

integer

The current page number returned.

integer

The number of results per page used for this response.

Create a workspace

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

Request body

string

required

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

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.

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

object

The newly created workspace object.

Show workspace object

string

The unique identifier for the workspace, prefixed with ws_.

string

The display name of the workspace.

string

The URL-safe identifier for the workspace.

string

The IANA timezone identifier assigned to the workspace.

integer

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

string

ISO 8601 timestamp of when the workspace was created.

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

integer

default:"1"

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

integer

default:"20"

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

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

array

An array of project objects belonging to the workspace.

Show project object

string

The unique identifier for the project, prefixed with proj_.

string

The ID of the workspace this project belongs to.

string

The display name of the project.

string

An optional description of the project’s purpose.

string

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

string

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

boolean

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

string

ISO 8601 timestamp of when the project was created.

string

ISO 8601 timestamp of the most recent update.

object

Pagination metadata for the response.

Show meta object

integer

Total number of projects in the workspace matching the query.

integer

The current page number returned.

integer

The number of results per page used for this response.

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

object

The requested workspace object.

Show workspace object

string

The unique identifier for the workspace, prefixed with ws_.

string

The display name of the workspace.

string

The URL-safe identifier for the workspace.

string

The IANA timezone identifier assigned to the workspace.

integer

The total number of members currently in the workspace.

string

ISO 8601 timestamp of when the workspace was created.

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

string

The new display name for the workspace.

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.

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

object

The updated workspace object, reflecting all applied changes.

Show workspace object

string

The unique identifier for the workspace, prefixed with ws_.

string

The updated display name of the workspace.

string

The updated or unchanged URL-safe identifier.

string

The updated or unchanged IANA timezone identifier.

integer

The total number of members currently in the workspace.

string

ISO 8601 timestamp of when the workspace was originally created.

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