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

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

array

An array of project objects.

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.

Show meta object

integer

Total number of projects matching the query.

integer

The current page number returned.

integer

The number of results per page used for this response.

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

string

required

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

string

required

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

string

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

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.

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

object

The newly created project object.

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

The optional description provided at creation.

string

The hex color code assigned to the project.

string

Access level: "private" or "shared".

boolean

Always false for a newly created project.

string

ISO 8601 timestamp of when the project was created.

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

object

The requested project object.

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

The optional description of the project.

string

The hex color code assigned to the project.

string

Access level: "private" or "shared".

boolean

Whether the project has been archived.

string

ISO 8601 timestamp of when the project was created.

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

string

A new display name for the project.

string

An updated description for the project.

string

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

string

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

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

object

The updated project object, reflecting all applied changes.

Show project object

string

The unique identifier for the project.

string

The ID of the workspace this project belongs to.

string

The updated display name of the project.

string

The updated or unchanged description.

string

The updated or unchanged hex color code.

string

The updated or unchanged access level.

boolean

The updated archive status of the project.

string

ISO 8601 timestamp of when the project was originally created.

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