API Reference

v1.0

REST API

The RelayPlane API provides programmatic access to AI model routing, optimization, and management features. Use it to integrate RelayPlane into your applications, tools, and workflows.

Quick Links

Authentication

RelayPlane uses API keys for authentication. Include your API key in the request header:

curl -H "x-api-key: your-relay-api-key" \
     https://api.relayplane.com/api/health

API Key Security

• Never expose your API key in client-side code
• Use environment variables to store your key
• Rotate keys regularly for security

Getting an API Key

Base URL

All API requests are made to:

https://api.relayplane.com/api

Request Format

All requests must use HTTPS
Request bodies should be JSON with Content-Type: application/json
All timestamps are in ISO 8601 format
Rate limits apply based on your plan

Error Handling

RelayPlane uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Code	Meaning	Description
200	OK	Request successful
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key lacks required permissions
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: to",
    "details": {
      "parameter": "to",
      "provided": null,
      "expected": "string"
    }
  },
  "request_id": "req_123456789"
}

POST /api/relay

Route a request to an AI model with optional optimization features.

Request

POST https://api.relayplane.com/api/relay
Content-Type: application/json
x-api-key: your-relay-api-key

{
  "to": "claude-3-sonnet",
  "payload": {
    "model": "claude-3-sonnet-20240229",
    "max_tokens": 1000,
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ]
  },
  "metadata": {
    "user_id": "user_123",
    "session": "session_456"
  }
}

Parameters

Parameter	Type	Required	Description
to	string	✅ Yes	Target model identifier
payload	object	✅ Yes	Model-specific request payload
metadata	object	❌ No	Custom tracking data

Response

{
  "relay_id": "evt_rel_123456789",
  "status_code": 200,
  "latency_ms": 445,
  "body": {
    "id": "msg_123",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Paris is the capital of France."
      }
    ],
    "model": "claude-3-sonnet-20240229",
    "stop_reason": "end_turn",
    "usage": {
      "input_tokens": 12,
      "output_tokens": 8
    }
  },
  "fallback_used": false
}

Supported Models

Anthropic

claude-3-opus
claude-3-sonnet
claude-3-haiku

OpenAI

gpt-4
gpt-4-turbo
gpt-3.5-turbo

Google

gemini-pro
gemini-pro-vision

Streaming Requests

Enable streaming by setting stream: true in your payload and using the Accept: text/event-stream header:

curl -X POST "https://api.relayplane.com/api/relay" \
  -H "x-api-key: your-relay-api-key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "to": "claude-3-sonnet",
    "payload": {
      "stream": true,
      "model": "claude-3-sonnet-20240229",
      "max_tokens": 1000,
      "messages": [{"role": "user", "content": "Write a poem"}]
    }
  }'

GET /api/discover

Discover available agents and their capabilities.

Request

GET https://api.relayplane.com/api/discover?capability=text-analysis&limit=10
x-api-key: your-relay-api-key

Query Parameters

Parameter	Type	Required	Description
capability	string	❌ No	Filter by capability
limit	integer	❌ No	Max results (default: 50)
offset	integer	❌ No	Results offset (default: 0)

Response

{
  "agents": [
    {
      "id": "agent_123",
      "name": "Text Analyzer Pro",
      "capability": "text-analysis",
      "description": "Advanced text analysis and sentiment detection",
      "endpoint": "https://api.example.com/analyze",
      "protocol": "http",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

POST /api/register

Request

POST https://api.relayplane.com/api/register
Content-Type: application/json
x-api-key: your-relay-api-key

{
  "name": "My Custom Agent",
  "capability": "text-analysis",
  "description": "Custom text analysis agent",
  "endpoint": "https://api.myservice.com/analyze",
  "protocol": "http"
}

Response

{
  "id": "agent_123456",
  "name": "My Custom Agent",
  "capability": "text-analysis",
  "description": "Custom text analysis agent",
  "endpoint": "https://api.myservice.com/analyze",
  "protocol": "http",
  "created_at": "2024-01-15T10:30:00Z"
}

GET /api/health

Check the health status of the RelayPlane API.

Request

GET https://api.relayplane.com/api/health
x-api-key: your-relay-api-key

Response

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0",
  "uptime": 3600,
  "services": {
    "database": "healthy",
    "cache": "healthy",
    "ai_providers": "healthy"
  }
}

API Key Management

Manage your RelayPlane API keys through the dashboard or programmatically.

Manage API Keys: Visit the API Keys dashboard →

Key Types

Standard Key

For general API access

• All core endpoints
• Rate limited by plan
• Usage tracking

Read-Only Key

For monitoring and analytics

• Health checks only
• Usage analytics
• Log viewing

Request Logs

View and analyze your API request logs through the dashboard.

View Logs: Visit the Logs dashboard →

Log Data

Each request is logged with the following information:

Unique request ID
Timestamp and latency
Model used and response status
Token usage and estimated cost
Fallback events (if applicable)
Custom metadata

Log Retention

Plan	Retention	Export
Free	7 days	Dashboard only
Maker	30 days	CSV/JSON export
Pro	90 days	API access + webhooks

Billing & Usage

Monitor your usage and billing information through the dashboard.

View Usage: Visit the Billing dashboard →

Usage Tracking

Track your usage across all endpoints:

Total API requests per month
Requests by model/endpoint
Average latency and success rates
Estimated costs by provider

Need Help?

Questions about the API? Check out our resources: