REST API Patterns

This page documents common patterns for working with the Aero2 REST API directly, without using an SDK.

Authentication

API requests are authenticated using one of two methods:

Include an access token in the Authorization header:

curl https://your-app.aero2.dev/api/users/me \
  -H "Authorization: Bearer <access_token>"

Browser-based requests can use the session cookie set by Aero2 during sign-in. The cookie is sent automatically by the browser with each request.

All list endpoints support pagination using page and limit query parameters:

curl "https://your-app.aero2.dev/api/users?page=1&limit=20" \
  -H "Authorization: Bearer <admin_token>"

Responses include pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 85,
    "total_pages": 5
  }
}

All errors follow a standard format:

{
  "error": "validation_error",
  "message": "Email address is required"
}

Status	Meaning
`400`	Bad Request — Invalid input or missing required fields
`401`	Unauthorized — Missing or invalid authentication
`403`	Forbidden — Authenticated but lacking permission
`404`	Not Found — Resource does not exist
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error — Unexpected server-side error

API responses include rate limiting headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

When the rate limit is exceeded, the API returns a 429 status with a Retry-After header indicating how many seconds to wait before retrying:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1739654400

API Overview — Full API reference
JavaScript / TypeScript SDK — Client library that handles these patterns automatically