---
title: API Reference
---

The ZevCloud API lets you programmatically manage projects, services, deployments, and more.

## Base URL

```
https://api.zevcloud.net/v1
```

## Authentication

All API requests require authentication via an API key:

```bash
curl https://api.zevcloud.net/v1/projects \
  -H "Authorization: Bearer sk_live_your_api_key"
```

Generate API keys from [Dashboard → Settings → API Keys](https://console.zevcloud.net/settings?tab=api-keys). Keys come in three scopes — `read`, `deploy`, and `full` — that constrain what the key can do. See [Authentication](/api/auth) for the full scope hierarchy and the list of routes that always require interactive human auth.

API keys are scoped to a team — every operation uses the team context the key was created in. The team ID is set by the server from the key, not from a request header.

## Request Format

- **Content-Type**: `application/json`
- **Team ID**: Automatically set from the API key. When using a ZevID identity token instead of an API key (interactive/dashboard usage), pass `x-team-id: <team-uuid>` to choose which team to act on.

## Response Format

All responses are JSON. Successful responses return the data directly:

```json
{
  "id": "uuid",
  "name": "My Project",
  "slug": "my-project"
}
```

List endpoints return paginated data:

```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 42,
    "pages": 2
  }
}
```

Error responses:

```json
{
  "statusCode": 400,
  "message": "Validation failed",
  "timestamp": "2026-03-28T12:00:00.000Z",
  "path": "/v1/projects"
}
```

Common auth-related status codes:

| Status | Meaning |
|--------|---------|
| `401` | Missing, invalid, expired, or revoked credentials. Also returned when an API key's creator has been removed from the team — the key is auto-revoked at this point. |
| `403` (scope) | Key's scope is below what the route requires. Body: `requires '<scope>', key has '<scope>'`. Issue a new key with a higher scope. |
| `403` (human-only) | Route requires interactive human authentication and cannot be performed with an API key. |

## Rate Limiting

| Endpoint | Limit |
|----------|-------|
| Most endpoints | 100 requests / minute |
| Deploy triggers | 10 / minute |
| Auth endpoints | 10 / minute |

Rate limit headers are included in every response:
- `X-RateLimit-Limit`
- `X-RateLimit-Remaining`
- `X-RateLimit-Reset`

## Endpoints

| Resource | Endpoints |
|----------|-----------|
| [Projects](/api/projects) | CRUD for projects |
| [Services](/api/services) | Create, manage, deploy services |
| [Deployments](/api/deployments) | Trigger and monitor deployments |
| [Domains](/api/domains) | Custom domain management |
| [Environment Variables](/api/env-vars) | Service-scoped env vars |