Skip to main content

API Overview

The FAOS API enables developers to programmatically interact with agents, workflows, and data. This reference documents all available endpoints.

Base URL​

Production: https://api.faosx.ai/v1
Sandbox:    https://sandbox.api.faosx.ai/v1

Authentication​

All API requests require authentication via API key or OAuth 2.0 token.

# API Key (Header)
curl -H "Authorization: Bearer sk_live_xxx" \
  https://api.faosx.ai/v1/agents

# API Key (Query parameter - not recommended)
curl https://api.faosx.ai/v1/agents?api_key=sk_live_xxx

See Authentication for detailed setup.

Request Format​

  • Content-Type: application/json
  • Accept: application/json
  • Character Encoding: UTF-8
curl -X POST https://api.faosx.ai/v1/agents \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "template": "customer-service"}'

Response Format​

All responses are JSON with consistent structure:

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Error Responses​

{
  "error": {
    "code": "invalid_request",
    "message": "The 'name' field is required",
    "param": "name"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Pagination​

List endpoints support cursor-based pagination:

GET /v1/agents?limit=20&cursor=abc123

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "has_more": true,
    "next_cursor": "def456"
  }
}

Rate Limits​

PlanRequests/MinuteRequests/Day
Starter6010,000
Growth300100,000
EnterpriseCustomCustom

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312800

API Endpoints​

Agents​

  • GET /v1/agents - List agents
  • POST /v1/agents - Create agent
  • GET /v1/agents/:id - Get agent
  • PATCH /v1/agents/:id - Update agent
  • DELETE /v1/agents/:id - Delete agent

Workflows​

  • GET /v1/workflows - List workflows
  • POST /v1/workflows - Create workflow
  • POST /v1/workflows/:id/run - Execute workflow

Messages​

  • POST /v1/agents/:id/messages - Send message to agent
  • GET /v1/agents/:id/messages - Get conversation history

Webhooks​

  • POST /v1/webhooks - Create webhook
  • GET /v1/webhooks - List webhooks
  • DELETE /v1/webhooks/:id - Delete webhook

OpenAPI Specification​

The FAOS API is fully described using the OpenAPI 3.1 specification. You can use the spec to generate clients, validate requests, or import into tools like Postman.

https://api.faosx.ai/v1/openapi.json

Import into Postman​

  1. Open Postman and click Import
  2. Enter the URL: https://api.faosx.ai/v1/openapi.json
  3. Click Import to generate a full collection

SDKs​

Official SDKs are available:

# Python
pip install faos

# TypeScript / JavaScript
npm install @faos/sdk

See the SDK Documentation for full reference and examples.

Next Steps​