Skip to content

api.md

Latest commit

 

History

History
204 lines (153 loc) · 4.82 KB

api.md

File metadata and controls

204 lines (153 loc) · 4.82 KB
Raw

Aether HTTP API

Base path: /api/v1

OpenAPI spec served at /api/v1/docs (Swagger UI) when enabled.

Authentication

User API

Authorization: Bearer <access_jwt>
X-Organization-ID: <uuid>   # when not implicit in route

Agent API

Ed25519 signed requests per agent-protocol.md. No Bearer-only auth.

User Endpoints

Auth

Method Path Auth Description
POST /auth/register none Create user + org
POST /auth/login none Returns access + refresh tokens
POST /auth/refresh refresh body New access token
POST /auth/logout Bearer Revoke refresh session

POST /auth/register

{
  "email": "ops@example.com",
  "password": "…",
  "organization_name": "Acme Corp"
}

Response 201:

{
  "user": {"id": "uuid", "email": "…"},
  "organization": {"id": "uuid", "name": "…", "slug": "acme-corp"},
  "tokens": {
    "access_token": "…",
    "refresh_token": "…",
    "expires_in": 900
  }
}

POST /auth/login

{"email": "…", "password": "…"}

Organizations

Method Path Role Description
GET /organizations/current viewer+ Current org details
PATCH /organizations/current admin+ Update org settings

Servers

Method Path Role Description
GET /servers viewer+ List servers (paginated)
POST /servers operator+ Create server
GET /servers/{id} viewer+ Get server
PATCH /servers/{id} operator+ Update server
DELETE /servers/{id} admin+ Soft delete
POST /servers/{id}/enrollment-token operator+ Generate enrollment token

POST /servers/{id}/enrollment-token

Response:

{
  "token": "aether_enr_…",
  "expires_at": "2026-07-23T14:00:00Z"
}

Token shown once; only hash stored.

Agents

Method Path Role Description
GET /agents viewer+ List agents
GET /agents/{id} viewer+ Agent details + status
POST /agents/{id}/revoke admin+ Revoke credential
POST /agents/{id}/config operator+ Push new config version

Monitors

Method Path Role Description
GET /monitors viewer+ List monitors
POST /monitors operator+ Create monitor
GET /monitors/{id} viewer+ Get monitor
PATCH /monitors/{id} operator+ Update monitor
DELETE /monitors/{id} admin+ Soft delete
GET /monitors/{id}/checks viewer+ Recent check results

Incidents

Method Path Role Description
GET /incidents viewer+ List incidents
GET /incidents/{id} viewer+ Incident + events
POST /incidents/{id}/acknowledge operator+ Ack incident

Metrics

Method Path Role Description
GET /servers/{id}/metrics viewer+ Query system metrics
GET /servers/{id}/uptime viewer+ Uptime percentages

Query params: from, to, resolution (raw, 1m).

Agent Endpoints

All require Ed25519 signing.

Method Path Description
POST /agent/enroll Initial enrollment (token auth)
GET /agent/config Fetch signed remote config
POST /agent/config/ack Acknowledge config apply
POST /agent/heartbeat Periodic heartbeat
POST /agent/metrics Batch metric ingestion
POST /agent/inventory Inventory snapshot

Pagination

List endpoints support:

?cursor=<opaque>&limit=50

Response:

{
  "data": [],
  "pagination": {
    "next_cursor": "…",
    "has_more": true
  }
}

Default limit: 50. Max: 200.

Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable message",
    "details": [{"field": "email", "message": "invalid format"}],
    "request_id": "uuid"
  }
}

RBAC Matrix

Resource viewer operator admin owner
Read servers/monitors ✓ ✓ ✓ ✓
Create/update servers ✓ ✓ ✓
Delete servers ✓ ✓
Manage users ✓ ✓
Delete organization ✓
Revoke agents ✓ ✓
Push agent config ✓ ✓ ✓

Health

Method Path Auth Description
GET /health none Liveness
GET /ready none DB connectivity

Rate Limits

Scope Limit
Auth endpoints 10/min per IP
Agent endpoints 120/min per agent
User API 300/min per user

Returns 429 with Retry-After header.