API REFERENCE

REST API for session management, authentication, and resource control.

AUTHENTICATION

Include your API key in the X-API-Key header for all API requests.

# Create a session via the Developer SDK (recommended)
# The SDK handles auth and returns gateway/player URLs
$ npm install @aether-stack-dev/developer-sdk

# Or call your Supabase edge function directly:
$ curl -X POST https://YOUR_PROJECT.supabase.co/functions/v1/session \
  -H "X-API-Key: ak_your_api_key_here" \
  -H "Authorization: Bearer SUPABASE_ANON_JWT" \
  -H "Content-Type: application/json" \
  -d '{"end_user_id": "user_123"}'

# Response includes browser-safe session fields:
# {
#   "sessionToken": "st_...",
#   "gatewayUrl": "https://runtime.aether-stack.com",
#   "gatewayWsUrl": "wss://runtime.aether-stack.com",
#   "rendererPlayerUrl": "https://runtime.aether-stack.com/astack/start?astack_token=..."
# }

SECURITY BEST PRACTICES

▶Never expose API keys in client-side code — use session tokens instead
▶Use environment variables to store keys
▶Create scoped keys with minimum required permissions
▶Rotate keys regularly and monitor usage

API KEY SCOPES

API keys can be scoped to limit access. Create and manage keys from the dashboard or via the Server SDK.

sessions:readRead session details and status

sessions:writeCreate and terminate sessions

users:readRead user profiles

users:writeCreate, update, and delete users

billing:readRead usage, invoices, and billing info

billing:writeRecord usage and set alerts

workers:readRead worker status and metrics

workers:writeRequest worker scaling

admin:allFull admin access (audit logs, performance)

LEGACY PERMISSIONS

Keys created via the dashboard use these permission flags:

session_createCreate new sessions

session_manageManage existing sessions

usage_readAccess usage metrics

RATE LIMITS

DEFAULT LIMITS

Requests per minute60

Requests per hour1,000

Concurrent sessions5

New keys default to 60 requests per minute and 1,000 per hour. Limits can be lowered per key or raised up to the selected billing plan's ceiling. The pay-as-you-go plan currently allows five concurrent sessions.

SESSION ENDPOINTS

CREATE SESSION

POST /functions/v1/session

{
  "end_user_id": "user_123",
  "connection_type": "websocket",
  "ttl": 900,
  "quality": "high",
  "features": ["vision"],
  "metadata": { "source": "web" }
}

curl -X POST "$ASTACK_API_ENDPOINT/session" \
  -H "X-API-Key: $ASTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "connection_type": "websocket",
    "ttl": 900,
    "quality": "high",
    "features": ["vision"],
    "metadata": { "source": "raw-http" }
  }'

Returns a session object with sessionToken, gatewayUrl, gatewayWsUrl, rendererPlayerUrl, and expiresAt. ttl is the requested lifetime in seconds and is bounded by the control plane. The legacy workerUrl alias may be present during migration but is not the preferred browser field.

GET SESSION

curl -X GET "$ASTACK_API_ENDPOINT/session/$SESSION_ID" \
  -H "X-API-Key: $ASTACK_API_KEY"

TERMINATE SESSION

curl -X DELETE "$ASTACK_API_ENDPOINT/session/$SESSION_ID" \
  -H "X-API-Key: $ASTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "last_error": null }'

SESSION LIFECYCLE

PENDINGSession created, waiting for connection

ACTIVEUser connected, conversation in progress

COMPLETEDSession ended successfully

FAILEDSession ended due to error

EXPIREDSession TTL exceeded

SERVER INTEGRATION

END-TO-END EXAMPLE

Your backend creates a session and returns the connection details to the client.

import express from 'express';
import { AStackSDK, authMiddleware, errorHandler } from '@aether-stack-dev/developer-sdk';

const app = express();
const sdk = new AStackSDK({
  apiKey: process.env.ASTACK_API_KEY,
  apiEndpoint: process.env.ASTACK_API_ENDPOINT,
});

app.use(express.json());
app.use('/api', authMiddleware(sdk));

app.post('/api/start-session', async (req, res) => {
  const { session, token, credentials } = await sdk.createSession(req.body.userId, {
    quality: 'high',
  });
  res.json({
    sessionId: session.id,
    sessionToken: token,
    gatewayUrl: credentials.gatewayUrl,
    gatewayWsUrl: credentials.gatewayWsUrl,
    rendererPlayerUrl: credentials.rendererPlayerUrl,
    expiresAt: credentials.expiresAt,
  });
});

app.use(errorHandler());
app.listen(3000);