API Reference

Complete reference documentation for the Astralform REST API, including authentication, endpoints, and response formats.

Base URL

All API requests should be made to:

https://api.astralform.ai/v1

For self-hosted deployments, use your server’s URL.

Authentication

All requests require an API key in the X-API-Key header:

curl -X GET https://api.astralform.ai/v1/conversations \
  -H "X-API-Key: af_live_xxxxxxxxxxxx"

Get your API key from the dashboard.

Content Type

All requests should include:

Content-Type: application/json

Response Format

Successful responses return JSON:

{
  "data": { ... },
  "meta": {
    "request_id": "req_123abc"
  }
}

Error responses:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid"
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request
401	Unauthorized
404	Not Found
429	Rate Limited
500	Server Error

Rate Limits

Default limits per API key:

Plan	Requests/min
Free	60
Pro	300
Enterprise	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1609459200

Endpoints

Chat Stream

POST /v1/chat/stream

Tool Result

POST /v1/tool-result

List Conversations

GET /v1/conversations

Get Conversation

GET /v1/conversations/:id