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

# API Overview

> The Aether REST API: base URL, scope, request format, errors, and pagination

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:

```
https://api.runaether.dev/v1
```

A request to list your projects is therefore:

```bash theme={"dark"}
curl https://api.runaether.dev/v1/projects \
  -H "Authorization: Bearer aether_..."
```

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

<Note>
  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`.
</Note>

## Authentication

Every endpoint requires a Bearer token in the `Authorization` header — either an `aether_` platform API key or a session JWT. See [Authentication](/api-reference/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:

```json theme={"dark"}
{
  "error": "Project not found"
}
```

| Code | Meaning |
| - | - |
| `200` | Success |
| `201` | Created |
| `202` | Accepted — work was enqueued (for example, creating a task) |
| `204` | No Content — successful deletion or update with no body |
| `400` | Bad Request — malformed input |
| `401` | Unauthorized — missing or invalid token |
| `404` | Not Found |
| `409` | Conflict |
| `422` | Unprocessable Entity — validation failed |
| `500` | Internal Server Error |

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:

| Parameter | Description |
| - | - |
| `page` | Page number, 1-based. Defaults to the first page. |
| `limit` | Items per page. Maximum `100`. |

```bash theme={"dark"}
curl "https://api.runaether.dev/v1/tasks?page=2&limit=50" \
  -H "Authorization: Bearer aether_..."
```

The [usage summary](/api-reference/v1/usage/get-usage-summary) endpoint paginates its per-task breakdown with `task_offset` and `task_limit` instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.