Chevre REST API — Overview, Formats, and Error Codes

Chevre provides a RESTful API that gives you programmatic access to all resources in your workspace — workspaces, projects, users, automations, and webhooks. Whether you’re building integrations, automating workflows, or syncing data with external tools, the API gives you the full power of Chevre over HTTP.

Base URL

All API requests are made to the following base URL:

https://api.chevre.io/v1

The version (v1) is included in the URL path. When Chevre introduces a new major version, the old version remains available so your integrations are never broken without notice.

API Characteristics

REST

Uses standard HTTP methods — GET, POST, PATCH, and DELETE — to perform operations on resources.

JSON

All request and response bodies use JSON. Set Content-Type: application/json on every request that sends a body.

Authentication

Every request must include a Bearer token in the Authorization header. See the Authentication page for details.

Versioning

The current API version is v1. The version is embedded in the URL path, so you always know exactly which contract you’re calling.

Request Format

Include your API key in the Authorization header and set the Content-Type header to application/json on any request with a body.

curl https://api.chevre.io/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Format

All successful responses return a JSON object. List endpoints wrap results in a data array and include a meta object with pagination details.

{
  "data": [
    {
      "id": "ws_01HXYZ",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "created_at": "2024-01-15T09:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20
  }
}

Pagination

All list endpoints support page and per_page query parameters. The meta object in every list response includes next and prev links so you can navigate through results without constructing URLs manually.

Parameter	Type	Description
`page`	integer	The page number to retrieve. Defaults to `1`.
`per_page`	integer	Number of results per page. Defaults to `20`, maximum `100`.

Error Responses

Chevre uses standard HTTP status codes to indicate success or failure. When a request fails, the response body contains an error object with a machine-readable code, a human-readable message, and the HTTP status.

{
  "error": {
    "code": "not_found",
    "message": "Workspace not found",
    "status": 404
  }
}

Error Code Reference

Status	Code	Meaning
`400`	`bad_request`	The request was malformed or missing required parameters.
`401`	`unauthorized`	The API key is missing, malformed, or revoked.
`403`	`forbidden`	The API key does not have permission to perform this action.
`404`	`not_found`	The requested resource does not exist.
`422`	`unprocessable_entity`	The request was well-formed but contained invalid field values.
`429`	`rate_limit_exceeded`	You have exceeded your plan’s request limit.
`500`	`internal_server_error`	An unexpected error occurred on Chevre’s servers.

Explore the API

Authentication

Learn how to generate API keys, set scopes, and authenticate every request.

Rate Limits

Understand request limits, response headers, and how to handle 429 responses gracefully.

Workspaces

Create and manage workspaces, members, and workspace-level settings.

Projects

Create projects, assign members, and manage project-level automations.

​Base URL

​API Characteristics

REST

JSON

Authentication

Versioning

​Request Format

​Response Format

​Pagination

​Error Responses

​Error Code Reference

​Explore the API

Authentication

Rate Limits

Workspaces

Projects

Base URL

API Characteristics

Request Format

Response Format

Pagination

Error Responses

Error Code Reference

Explore the API