Skip to main content
Aether exposes a REST API for managing projects, workspaces, tasks, and related resources programmatically. Requests and responses are JSON, and every endpoint is authenticated.

​
Base URL

The public, versioned API lives under the /v1 prefix:
A request to list your projects is therefore:

​
Scope

Only the versioned /v1 groups are part of the public API:
  • /v1/projects
  • /v1/workspaces
  • /v1/tasks
  • /v1/projects/{id}/env-vars
  • /v1/projects/{id}/secret-files
  • /v1/skills
  • /v1/automations
  • /v1/usage
Account and integration endpoints — profile, billing, notifications, platform keys, provider API keys, GitHub, Sentry, Linear, Slack, and the agent-auth groups — are mounted at the root (no /v1 prefix) and are used by the web app and CLI. They are documented in the API Reference for completeness but are not part of the stable versioned surface. Internal service-to-service endpoints (/internal/*), inbound webhooks, OAuth callbacks, and operator routes are not part of the public API.
The same handlers backing /v1 are also reachable at the root path for the first-party web app and CLI. The difference is CORS: /v1/* allows any origin, while the root surface is restricted to the Aether frontend origin. For your own integrations, always use /v1.

​
Authentication

Every endpoint requires a Bearer token in the Authorization header — either an aether_ platform API key or a session JWT. See Authentication for how to mint a key and what each credential is for.

​
Request Format

All request and response bodies are JSON. Set Content-Type: application/json on any request that has a body.

​
Errors

Errors return an HTTP status code with a JSON body containing a single error field:
Each endpoint documents the exact status codes it can return. See the per-endpoint pages under this section.

​
Pagination

List endpoints page with two query parameters:
The usage summary endpoint paginates its per-task breakdown with task_offset and task_limit instead.