Chevre REST API Endpoints — Projects and Workspaces

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

workspace_id

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&archived=false" \
  --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, "archived": False},
    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&archived=false",
  {
    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.

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.

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

workspace_id

string

required

The ID of the workspace where the project will be created.

name

string

required

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

description

string

An optional description of the project’s purpose or scope.

color

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.

visibility

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.

Example request

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

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

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

Example response

201

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

data

object

The newly created project object.

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

The optional description provided at creation.

color

string

The hex color code assigned to the project.

visibility

string

Access level: "private" or "shared".

archived

boolean

Always false for a newly created project.

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

string

required

The unique identifier of the project to retrieve (e.g. proj_01ABC).

Example request

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

import requests

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

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

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

Response fields

data

object

The requested project object.

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

The optional description of the project.

color

string

The hex color code assigned to the project.

visibility

string

Access level: "private" or "shared".

archived

boolean

Whether the project has been archived.

created_at

string

ISO 8601 timestamp of when the project was created.

updated_at

string

ISO 8601 timestamp of the most recent update.

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.

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.

Path parameters

string

required

The unique identifier of the project to update (e.g. proj_01ABC).

Request body

name

string

A new display name for the project.

description

string

An updated description for the project.

color

string

A new hex color code (e.g. "#10b981").

visibility

string

Updated access level. Accepted values: "private" or "shared".

archived

boolean

Set to true to archive the project, or false to restore it.

Example request

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

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

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

Example response

200

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

data

object

The updated project object, reflecting all applied changes.

Show project object

string

The unique identifier for the project.

workspace_id

string

The ID of the workspace this project belongs to.

name

string

The updated display name of the project.

description

string

The updated or unchanged description.

color

string

The updated or unchanged hex color code.

visibility

string

The updated or unchanged access level.

archived

boolean

The updated archive status of the project.

created_at

string

ISO 8601 timestamp of when the project was originally created.

updated_at

string

ISO 8601 timestamp of this update.

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.

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.

Path parameters

string

required

The unique identifier of the project to delete (e.g. proj_01ABC).

Example request

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

import requests

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

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

Example response

204

// No content returned on successful deletion

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

​List projects in a workspace

​Path parameters

​Query parameters

​Example request

​Example response

​Response fields

​Create a project

​Request body

​Example request

​Example response

​Response fields

​Get a project

​Path parameters

​Example request

​Example response

​Response fields

​Update a project

​Path parameters

​Request body

​Example request

​Example response

​Response fields

​Delete a project

​Path parameters

​Example request

​Example response

List projects in a workspace

Path parameters

Query parameters

Example request

Example response

Response fields

Create a project

Request body

Example request

Example response

Response fields

Get a project

Path parameters

Example request

Example response

Response fields

Update a project

Path parameters

Request body

Example request

Example response

Response fields

Delete a project

Path parameters

Example request

Example response