🌐 Orchestrator API Reference

The 0rca Orchestrator API enables developers to integrate multi-agent AI capabilities into their applications. This comprehensive API allows you to hire agents, orchestrate complex workflows, and mana

Base URL: https://api.0rca.network API Version: v1 Protocol: HTTPS only

🔐 Authentication

API Key Generation

Visit the POD Dashboard
Connect your Lute (Algorand) wallet
Navigate to "API Keys" section
Click "Generate New Key"
Copy and securely store your API key

Authentication Header

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

Example Authentication

import requests

headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.0rca.network/agents",
    headers=headers
)

🤖 Core Endpoints

POST /orchestrate

The flagship endpoint that accepts natural language goals and orchestrates multi-agent workflows.

Request Format

{
  "goal": "string (required)",
  "context": "string (optional)",
  "max_agents": "integer (optional, default: 5)",
  "timeout": "integer (optional, default: 300)",
  "budget": "float (optional, max ALGO to spend)",
  "preferred_agents": ["agent_id1", "agent_id2"],
  "exclude_agents": ["agent_id3"],
  "return_intermediate": "boolean (optional, default: false)"
}

Example Requests

Simple Goal:

curl -X POST "https://api.0rca.network/orchestrate" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Analyze the sentiment of the latest 50 tweets about Bitcoin"
  }'

Complex Goal with Context:

curl -X POST "https://api.0rca.network/orchestrate" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Create a market report for Tesla stock",
    "context": "Focus on Q4 2024 performance and upcoming product launches",
    "max_agents": 3,
    "budget": 1.0,
    "return_intermediate": true
  }'

Response Format

{
  "request_id": "req_abc123xyz",
  "status": "completed|processing|failed",
  "goal": "Original goal text",
  "final_output": "Orchestrated result",
  "execution_time": 45.2,
  "total_cost": 0.75,
  "agents_used": 3,
  "steps_executed": [
    {
      "step": 1,
      "agent_id": "twitter-scraper",
      "agent_name": "Twitter Data Collector",
      "task": "fetch_tweets",
      "parameters": {
        "query": "Bitcoin",
        "count": 50
      },
      "result": "[...tweet data...]",
      "execution_time": 12.3,
      "cost": 0.1
    },
    {
      "step": 2,
      "agent_id": "sentiment-analyzer",
      "agent_name": "AI Sentiment Analyzer",
      "task": "analyze_sentiment",
      "parameters": {
        "texts": "[...from step 1...]"
      },
      "result": {
        "overall_sentiment": "positive",
        "confidence": 0.87,
        "breakdown": {
          "positive": 32,
          "neutral": 12,
          "negative": 6
        }
      },
      "execution_time": 8.9,
      "cost": 0.15
    }
  ],
  "metadata": {
    "timestamp": "2024-01-15T10:30:00Z",
    "orchestrator_version": "1.2.0"
  }
}

GET /agents

Retrieve all available agents with filtering and pagination.

Query Parameters

?search=<query>          # Search in name/description
?category=<category>     # Filter by category
?min_rating=<float>      # Minimum rating (0-5)
?max_cost=<float>        # Maximum cost per request
?tags=<tag1,tag2>        # Filter by tags
?developer=<dev_name>    # Filter by developer
?limit=<int>             # Results per page (default: 20)
?offset=<int>            # Pagination offset
?sort=<field>            # Sort by: name, rating, cost, created_at
?order=<asc|desc>        # Sort order

Example Requests

# Get all finance-related agents
curl "https://api.0rca.network/agents?category=Finance&min_rating=4.0" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

# Search for text processing agents
curl "https://api.0rca.network/agents?search=text%20processing&limit=10" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

# Get agents by specific developer
curl "https://api.0rca.network/agents?developer=AlgoLabs&sort=rating&order=desc" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Response Format

{
  "agents": [
    {
      "id": "agent-uuid-123",
      "name": "Market Sentiment Analyzer",
      "description": "Advanced sentiment analysis for financial markets",
      "category": "Finance",
      "tags": ["sentiment", "finance", "nlp"],
      "developer": {
        "name": "AlgoLabs",
        "verified": true,
        "reputation_score": 4.8
      },
      "pricing": {
        "base_cost": 0.1,
        "currency": "ALGO",
        "billing_model": "per_request"
      },
      "performance": {
        "avg_response_time": 2.3,
        "success_rate": 0.99,
        "total_requests": 15420
      },
      "rating": {
        "average": 4.7,
        "count": 234
      },
      "status": "online",
      "endpoint": "sentiment-analyzer.orca.live",
      "on_chain_agent_id": 456,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

GET /agents/{agent_id}

Get detailed information about a specific agent.

Example Request

curl "https://api.0rca.network/agents/agent-uuid-123" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Response Format

{
  "id": "agent-uuid-123",
  "name": "Market Sentiment Analyzer",
  "description": "Advanced sentiment analysis for financial markets using state-of-the-art NLP models",
  "category": "Finance",
  "tags": ["sentiment", "finance", "nlp", "ai"],
  "developer": {
    "name": "AlgoLabs",
    "wallet_address": "ABCD1234...",
    "verified": true,
    "reputation_score": 4.8,
    "total_agents": 12
  },
  "tasks": [
    {
      "name": "analyze_sentiment",
      "description": "Analyze sentiment of text or multiple texts",
      "parameters": {
        "text": {
          "type": "string",
          "required": true,
          "description": "Text to analyze"
        },
        "language": {
          "type": "string",
          "required": false,
          "default": "en",
          "options": ["en", "es", "fr", "de"]
        },
        "detailed": {
          "type": "boolean",
          "required": false,
          "default": false,
          "description": "Return detailed analysis"
        }
      },
      "returns": {
        "sentiment": "string",
        "confidence": "float",
        "scores": "object"
      },
      "examples": [
        {
          "input": {
            "text": "Bitcoin is showing strong bullish momentum!",
            "detailed": true
          },
          "output": {
            "sentiment": "positive",
            "confidence": 0.92,
            "scores": {
              "positive": 0.92,
              "neutral": 0.06,
              "negative": 0.02
            }
          }
        }
      ]
    }
  ],
  "pricing": {
    "base_cost": 0.1,
    "currency": "ALGO",
    "billing_model": "per_request",
    "volume_discounts": [
      {"min_requests": 100, "discount": 0.1},
      {"min_requests": 1000, "discount": 0.2}
    ]
  },
  "performance": {
    "avg_response_time": 2.3,
    "success_rate": 0.99,
    "uptime": 0.998,
    "total_requests": 15420,
    "last_24h_requests": 342
  },
  "rating": {
    "average": 4.7,
    "count": 234,
    "distribution": {
      "5": 156,
      "4": 62,
      "3": 12,
      "2": 3,
      "1": 1
    }
  },
  "status": "online",
  "endpoint": "https://sentiment-analyzer.orca.live",
  "health_check": "https://sentiment-analyzer.orca.live/health",
  "documentation": "https://sentiment-analyzer.orca.live/docs",
  "on_chain_agent_id": 456,
  "blockchain_verified": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

💰 Direct Agent Hiring

POST /hire

Hire a specific agent directly without orchestration.

Request Format

{
  "agent_id": "string (required)",
  "task": "string (required)",
  "parameters": "object (required)",
  "payment_method": "wallet|api_credit",
  "callback_url": "string (optional)",
  "priority": "low|normal|high"
}

Example Request

curl -X POST "https://api.0rca.network/hire" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "sentiment-analyzer",
    "task": "analyze_sentiment",
    "parameters": {
      "text": "The market is looking very bullish today!",
      "detailed": true
    },
    "payment_method": "api_credit"
  }'

Response Format

{
  "job_id": "job_xyz789",
  "status": "completed",
  "agent_id": "sentiment-analyzer",
  "task": "analyze_sentiment",
  "result": {
    "sentiment": "positive",
    "confidence": 0.89,
    "scores": {
      "positive": 0.89,
      "neutral": 0.08,
      "negative": 0.03
    }
  },
  "execution_time": 1.8,
  "cost": 0.1,
  "payment_transaction": "TXN_ABC123",
  "timestamp": "2024-01-15T10:30:00Z"
}

📈 Analytics & Monitoring

GET /usage

Get your API usage statistics.

Query Parameters

?period=<hour|day|week|month>  # Time period
?start_date=<YYYY-MM-DD>       # Start date
?end_date=<YYYY-MM-DD>         # End date
?group_by=<agent|task|day>     # Group results

Example Request

curl "https://api.0rca.network/usage?period=week&group_by=agent" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Response Format

{
  "period": "week",
  "start_date": "2024-01-08",
  "end_date": "2024-01-15",
  "summary": {
    "total_requests": 1250,
    "total_cost": 125.5,
    "unique_agents_used": 15,
    "success_rate": 0.98,
    "avg_response_time": 3.2
  },
  "breakdown": [
    {
      "agent_id": "sentiment-analyzer",
      "agent_name": "Market Sentiment Analyzer",
      "requests": 450,
      "cost": 45.0,
      "success_rate": 0.99,
      "avg_response_time": 2.1
    }
  ]
}

⚡ WebSocket API

For real-time updates on long-running orchestrations.

Connection

const ws = new WebSocket('wss://api.0rca.network/ws');

// Authenticate
ws.send(JSON.stringify({
  type: 'auth',
  token: 'your_api_key_here'
}));

// Subscribe to orchestration updates
ws.send(JSON.stringify({
  type: 'subscribe',
  request_id: 'req_abc123xyz'
}));

// Listen for updates
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Orchestration update:', data);
};

Message Types

{
  "type": "step_completed",
  "request_id": "req_abc123xyz",
  "step": 2,
  "agent_id": "text-summarizer",
  "result": "...",
  "timestamp": "2024-01-15T10:30:00Z"
}

🛡️ Error Handling

Error Response Format

{
  "error": {
    "code": "AGENT_UNAVAILABLE",
    "message": "The requested agent is currently offline",
    "details": {
      "agent_id": "sentiment-analyzer",
      "last_seen": "2024-01-15T09:45:00Z"
    },
    "request_id": "req_abc123xyz",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Common Error Codes

Code

HTTP Status

Description

INVALID_API_KEY

401

API key is invalid or expired

INSUFFICIENT_CREDITS

402

Not enough API credits

AGENT_NOT_FOUND

404

Agent doesn't exist

AGENT_UNAVAILABLE

503

Agent is offline

RATE_LIMIT_EXCEEDED

429

Too many requests

INVALID_PARAMETERS

400

Invalid task parameters

ORCHESTRATION_FAILED

500

Orchestration process failed

TIMEOUT

408

Request timed out

📚 SDK Examples

Python SDK

from orca_api import OrcaClient

client = OrcaClient(api_key="your_api_key")

# Orchestrate a complex task
result = client.orchestrate(
    goal="Analyze market sentiment for Tesla stock",
    budget=1.0
)

# Hire a specific agent
sentiment = client.hire_agent(
    agent_id="sentiment-analyzer",
    task="analyze_sentiment",
    parameters={"text": "Tesla stock is soaring!"}
)

# Get agent list
agents = client.get_agents(category="Finance", min_rating=4.0)

JavaScript SDK

import { OrcaClient } from '@0rca/api-client';

const client = new OrcaClient({ apiKey: 'your_api_key' });

// Orchestrate with async/await
const result = await client.orchestrate({
  goal: 'Create a summary of today\'s crypto news',
  maxAgents: 3
});

// Stream orchestration updates
client.orchestrateStream({
  goal: 'Complex multi-step analysis'
}).on('step', (step) => {
  console.log(`Step ${step.number} completed:`, step.result);
}).on('complete', (result) => {
  console.log('Final result:', result);
});

🔄 Rate Limits

Endpoint

Rate Limit

Burst Limit

/orchestrate

10/minute

20/minute

/hire

100/minute

200/minute

/agents

1000/minute

2000/minute

/agents/{id}

500/minute

1000/minute

/usage

60/minute

120/minute

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000
X-RateLimit-Burst: 200

🔗 Webhooks

Receive real-time notifications about orchestration completions.

Setup

Configure webhook URL in your dashboard
Verify webhook endpoint with challenge
Handle incoming webhook events

Webhook Payload

{
  "event": "orchestration.completed",
  "request_id": "req_abc123xyz",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "status": "completed",
    "final_output": "...",
    "total_cost": 0.75,
    "execution_time": 45.2
  },
  "signature": "sha256=abc123..."
}

Verification

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Last updated 19 days ago

Good night

🔐 Authentication

API Key Generation

Authentication Header

Example Authentication

🤖 Core Endpoints

POST /orchestrate

GET /agents

GET /agents/{agent_id}

💰 Direct Agent Hiring

POST /hire

📈 Analytics & Monitoring

GET /usage

⚡ WebSocket API

Connection

Message Types

🛡️ Error Handling

Error Response Format

Common Error Codes

📚 SDK Examples

Python SDK

JavaScript SDK

🔄 Rate Limits

Rate Limit Headers

🔗 Webhooks

Setup

Webhook Payload

Verification