Docs

Documentation

Call any provider through one endpoint

ModelRiver normalises request payloads, handles fallbacks, and returns structured metadata so your application stays simple.

Base configuration

  • Endpoint: https://api.modelriver.com/v1/ai
  • Authentication: Authorization: Bearer mr_live_... (project API key)
  • Content-Type: application/json

Synchronous requests

Standard requests return the AI response immediately. Use this for real-time interactions like chatbots or search.

Bash
curl -X POST https://api.modelriver.com/v1/ai \
-H "Authorization: Bearer mr_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"workflow": "marketing-summary",
"messages": [
{"role": "user", "content": "Summarise this week's launch."}
],
"metadata": {
"audience": "enterprise customers"
}
}'

Async requests

For long-running tasks, use the async endpoint. It returns a job ID immediately, and you receive the result via WebSocket or Webhook.

Endpoint: POST https://api.modelriver.com/v1/ai/async

Bash
curl -X POST https://api.modelriver.com/v1/ai/async \
-H "Authorization: Bearer mr_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"workflow": "batch-processor",
"messages": [
{"role": "user", "content": "Process this large document..."}
]
}'

Response (Immediate)

JSON
1{
2 "message": "success",
3 "status": "pending",
4 "channel_id": "550e8400-e29b-41d4-a716-446655440000",
5 "websocket_url": "ws://api.modelriver.com/socket",
6 "websocket_channel": "ai_response:550e8400-e29b-41d4-a716-446655440000"
7}

WebSocket Flow

  1. Connect to the WebSocket URL with the ws_token.
  2. Join the channel ai_response:{project_id}:{channel_id}.
  3. Listen for response events containing the final payload.

Tip: Use the official Client SDK to handle WebSocket connections, reconnection, and progress tracking automatically.

Optional fields

  • workflow: name of a saved workflow. Overrides provider and model.
  • provider, model: required when not using workflows.
  • messages: chat-style payload (the most common format across providers).
  • response_format / structured_output_schema: pass a JSON schema directly if you do not want to create a workflow.
  • inputs, metadata, context: free-form fields your workflow can access. Add them to cache fields to surface in responses/logs.

Response payload

JSON
1{
2 "data": { "summary": "..." },
3 "customer_data": { "metadata.audience": "enterprise customers" },
4 "meta": {
5 "status": "success",
6 "http_status": 200,
7 "workflow": "marketing-summary",
8 "requested_provider": "openai",
9 "requested_model": "gpt-4o-mini",
10 "used_provider": "openai",
11 "used_model": "gpt-4o-mini",
12 "duration_ms": 1420,
13 "usage": {
14 "prompt_tokens": 123,
15 "completion_tokens": 45,
16 "total_tokens": 168
17 },
18 "structured_output": true,
19 "attempts": [
20 {"provider": "openai", "model": "gpt-4o-mini", "status": "success"}
21 ]
22 },
23 "backups": [
24 {"position": 1, "provider": "anthropic", "model": "claude-3-5-sonnet"}
25 ]
26}

Error payloads

  • ModelRiver returns 200 with an error object when the request was valid but the provider failed.
  • Transport/authentication problems return standard HTTP status codes (401, 403, 429, 5xx).
JSON
1{
2 "data": null,
3 "customer_data": {},
4 "error": {
5 "message": "Provider request failed",
6 "details": {"status": 504, "message": "Upstream timeout"}
7 },
8 "meta": {
9 "status": "error",
10 "http_status": 502,
11 "workflow": "marketing-summary",
12 "attempts": [
13 {"provider": "openai", "model": "gpt-4o-mini", "status": "error", "reason": "timeout"}
14 ]
15 }
16}

Tips for production use

  • Use workflows so you can change providers and prompts without redeploying applications.
  • Leverage cache fields to echo request metadata in responses—especially helpful for tracing user IDs or experiment variants.
  • Handle backups in the response if you need to know which fallback succeeded.
  • Respect rate limits; if you see 429, implement exponential backoff or reach out to increase limits.
  • Store responses if you need historical context—ModelRiver retains logs, but you can export them or stream them elsewhere.