> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chevre.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Chevre REST API — Overview, Formats, and Error Codes

> Explore the Chevre REST API — base URLs, request and response formats, versioning, pagination, and a complete error code reference.

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

<CardGroup cols={2}>
  <Card title="REST" icon="arrow-right-arrow-left">
    Uses standard HTTP methods — `GET`, `POST`, `PATCH`, and `DELETE` — to perform operations on resources.
  </Card>

  <Card title="JSON" icon="brackets-curly">
    All request and response bodies use JSON. Set `Content-Type: application/json` on every request that sends a body.
  </Card>

  <Card title="Authentication" icon="key">
    Every request must include a Bearer token in the `Authorization` header. See the [Authentication](/api-reference/authentication) page for details.
  </Card>

  <Card title="Versioning" icon="tag">
    The current API version is `v1`. The version is embedded in the URL path, so you always know exactly which contract you're calling.
  </Card>
</CardGroup>

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

```bash theme={null}
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.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/api-reference/authentication">
    Learn how to generate API keys, set scopes, and authenticate every request.
  </Card>

  <Card title="Rate Limits" icon="gauge-high" href="/api-reference/rate-limits">
    Understand request limits, response headers, and how to handle 429 responses gracefully.
  </Card>

  <Card title="Workspaces" icon="building" href="/api-reference/endpoints/workspaces">
    Create and manage workspaces, members, and workspace-level settings.
  </Card>

  <Card title="Projects" icon="folder-open" href="/api-reference/endpoints/projects">
    Create projects, assign members, and manage project-level automations.
  </Card>
</CardGroup>