API Overview

Introduction to the Aether REST API

Base URL

https://api.aether.dev

If you are self-hosting Aether, replace this with your own deployment URL.

Request Format

All request and response bodies are JSON. Set the Content-Type header to application/json for requests with a body.

Authentication

Most endpoints require authentication. Include a Bearer token in the Authorization header:

curl https://api.runaether.dev/projects \
  -H "Authorization: Bearer YOUR_TOKEN"

See Authentication for details on obtaining and refreshing tokens.

Error Responses

Errors return an appropriate HTTP status code with a JSON body:

{
  "error": "Project not found"
}

Common Status Codes

Code	Description
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request — invalid parameters
401	Unauthorized — missing or invalid token
403	Forbidden — insufficient permissions
404	Not Found
409	Conflict — resource already exists
429	Too Many Requests — rate limit exceeded
500	Internal Server Error

Rate Limiting

API requests are rate-limited per user. When you exceed the limit, the API returns a 429 status code. Respect the Retry-After header value before retrying.

Pagination

List endpoints return all results by default. For endpoints that support pagination, use limit and offset query parameters.