CLI APIs

These endpoints are called by the alethia CLI. Authentication is via Authorization: Bearer {jwt} header with a CLI-issued JWT. See Authentication Flows.

Zones

GET /api/cli/zones

List all zones with nested spec configurations.

POST /api/cli/zones

Create a new zone.

Body: { "name": "api-backend" }

GET /api/cli/zones/{id}

Get a single zone with its specs.

Configurations (Specs)

GET /api/cli/configurations

List all spec configurations for the authenticated user.

GET /api/cli/configurations/{name}

Get a configuration by name.

GET /api/cli/configurations/by-project-name/{project_name}

Look up a spec by project name.

POST /api/cli/configurations

Create a new spec configuration from CLI input.

Jobs

POST /api/jobs

Create a new job. Accepts:

{
  "job_type": "PLAN",
  "configuration_id": "spec-uuid",
  "assigned_worker_id": "worker-uuid",
  "plan_job_id": "plan-job-uuid"
}

Valid job types: PLAN, DEPLOY, DESTROY, DESTROY_WORKER.

If configuration_id is provided, the server auto-resolves cloud_identity_id, zone_id, computes config hash, and creates a config snapshot.

GET /api/jobs

List all jobs for the authenticated user. Supports ?status={status} and ?zone_id={id} filters.

GET /api/cli/jobs/{id}

Get job status and metadata.

GET /api/cli/jobs/{id}/logs

Get job logs (same format as worker API).

POST /api/cli/jobs/{id}/cancel

Cancel a QUEUED or PROCESSING job.

Workers

GET /api/cli/workers

List all registered Runners.

POST /api/cli/workers

Register a self-hosted Runner.

GET /api/cli/workers/{id}

Get Runner details.

Repositories

GET /api/cli/repositories/github

List GitHub repositories for the authenticated user.

GET /api/cli/repositories/gitlab

List GitLab repositories.

GET /api/cli/repositories/bitbucket

List Bitbucket repositories.

Releases

POST /api/releases/worker

Publish a new Runner release (CI/CD only, requires RELEASE_API_SECRET).

Body:

{
  "version": "0.1.0",
  "release_notes": "Changelog content..."
}

POST /api/runners/register

Register a cloud-hosted Runner (CI/CD only, requires RELEASE_API_SECRET). Used by Terraform during Runner deployment.