API Reference
The Ancla API is a REST API at https://ancla.dev/api/v1. All endpoints return JSON and require authentication via API key or session.
Base URL
Section titled “Base URL”https://ancla.dev/api/v1Authentication
Section titled “Authentication”Include your API key in the X-API-Key header:
curl -H "X-API-Key: ancla_your_key_here" https://ancla.dev/api/v1/auth/sessionOr use session-based auth via the login endpoint.
Resources
Section titled “Resources”| Resource | Description |
|---|---|
| Authentication | Session, login, logout, CLI auth, OAuth |
| Workspaces | Manage workspaces, members, and workspace-level config |
| Projects | Create and manage projects within workspaces |
| Environments | Deployment targets (production, staging, preview) |
| Services | Deployable units within environments |
| Builds | Build container images for services |
| Deploys | Deploy builds and inspect deploy status and logs |
| Config Vars | Manage environment variables at every scope (workspace, project, env, service) |
| Pipeline | Pipeline status, metrics, deploy, rollback |
| Promotions | Promote builds between environments |
| Observability | CPU, memory, and pod metrics |
| Teams | Team management and team-scoped config |
| Integrations | Docker auth, GitHub webhooks, signing certs |
Error responses
Section titled “Error responses”All errors return a JSON body:
{ "status": 404, "message": "not found"}| Status | Meaning |
|---|---|
| 401 | Not authenticated — run ancla login or provide an API key |
| 403 | Permission denied — you don’t have access to this resource |
| 404 | Resource not found |
| 422 | Validation error — check the request body |
| 500 | Server error |