API Reference

Complete reference documentation for the GateFlow API.

Base URL

https://api.gateflow.ai/v1

Authentication

All API requests require authentication via Bearer token:

curl https://api.gateflow.ai/v1/chat/completions \
  -H "Authorization: Bearer gw_prod_your_key_here"

API Compatibility

GateFlow is OpenAI API compatible. Use the OpenAI SDK with a different base URL:

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.gateflow.ai/v1",
    api_key="gw_prod_..."
)

TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.gateflow.ai/v1',
  apiKey: 'gw_prod_...',
});

cURL

curl https://api.gateflow.ai/v1/chat/completions \
  -H "Authorization: Bearer gw_prod_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [...]}'

API Sections

Gateway API

Core AI functionality:

Endpoint	Description
POST /chat/completions	Generate chat responses
POST /embeddings	Create text embeddings
GET /models	List available models
POST /rerank	Rerank search results

Audio API

Voice and audio processing:

Endpoint	Description
POST /audio/transcriptions	Transcribe audio to text
POST /audio/speech	Convert text to speech
GET /audio/voices	List available voices
POST /audio/pipelines	Execute audio pipelines

Files API

File management:

Endpoint	Description
POST /files	Upload a file
GET /files	List files
GET /files/:id	Get file details
DELETE /files/:id	Delete a file

Management API

Account and settings:

Endpoint	Description
/management/api-keys	Manage API keys
/management/providers	Configure providers
/management/routing-rules	Set routing rules
/management/analytics	View analytics

Request Format

Headers

Header	Required	Description
Authorization	Yes	Bearer gw_prod_...
Content-Type	Yes	application/json
X-GateFlow-Trace-Id	No	Custom trace ID
X-GateFlow-Task-Type	No	Routing hint

GateFlow Extensions

Pass GateFlow-specific options in extra_body:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    extra_body={
        "gateflow": {
            "cache": "skip",
            "fallbacks": ["claude-3-5-sonnet"],
            "tags": {"team": "support"}
        }
    }
)

Response Format

Standard Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1705123456,
  "model": "gpt-4o",
  "choices": [...],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  },
  "gateflow": {
    "request_id": "req_xyz789",
    "provider": "openai",
    "latency_ms": 456,
    "cache": {
      "hit": false
    },
    "cost": {
      "input": 0.000025,
      "output": 0.00020,
      "total": 0.000225
    }
  }
}

Error Response

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "doc_url": "https://gateflow.ai/docs/api-reference/errors/auth-errors#invalid_api_key"
  }
}

Rate Limits

Default limits (can be customized per key):

Tier	Requests/min	Tokens/min
Free	60	40,000
Pro	600	400,000
Enterprise	Custom	Custom

Rate limit headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1705123516

Streaming

Enable streaming for real-time responses:

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    stream=True
)

for chunk in stream:
    print(chunk.choices[0].delta.content, end="")

SSE format:

data: {"id":"chatcmpl-123","choices":[{"delta":{"content":"Hello"}}]}

data: {"id":"chatcmpl-123","choices":[{"delta":{"content":" world"}}]}

data: [DONE]

Versioning

The API is versioned via the URL path:

https://api.gateflow.ai/v1/...

Breaking changes will be released under new versions. We maintain backward compatibility within versions.

SDKs

Official SDK support:

• Python: Use OpenAI SDK with custom base_url
• TypeScript/JavaScript: Use OpenAI SDK with custom baseURL
• Go: Use OpenAI SDK with custom endpoint
• REST: Direct HTTP calls with any client

Next Steps

• Chat Completions - Core chat API
• Error Handling - Understanding errors
• Quickstart - Get started quickly