XRollout API Documentation

🔐 Authentication

All API requests require authentication using an API key. You can create and manage API keys in your dashboard.

Pass your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

💰 Pricing & Credits

API usage is billed against your credit balance. You can earn credits through community contributions or redeem credits for additional API usage.

🚦 Rate Limits

Default rate limit is 100 requests per minute per API key. If you exceed the rate limit, you will receive a 429 Too Many Requests response.

The response includes a Retry-After header indicating how many seconds to wait.

📡 Endpoints

{
  "status": "ok",
  "service": "xrollout-api",
  "timestamp": 1704067200
}

{
  "object": "list",
  "data": [
    {
      "id": "slam_processing",
      "name": "SLAM Processing",
      "description": "Process SLAM from video input to generate trajectory and point cloud",
      "endpoint": "/v1/slam/process",
      "pricing": {
        "type": "variable",
        "base_credits": 5,
        "min_credits": 5,
        "max_credits": 50
      }
    }
  ]
}

{
  "object": "usage_statistics",
  "credits": {
    "available_balance": 150,
    "total_earned": 500,
    "total_spent": 350,
    "total_api_credits_charged": 120
  },
  "requests": {
    "last_24h": 45
  }
}

{
  "input": {
    "video_url": "https://example.com/your-video.mp4",
    "mode": "cnn",
    "target_fps": 15,
    "max_size": 640
  },
  "options": {
    "output_format": "json",
    "return_point_cloud": true
  }
}

{
  "id": "req_abc123456789",
  "object": "slam_processing",
  "created": 1704067200,
  "status": "completed",
  "result": {
    "message": "Processing completed successfully",
    "trajectory": [...],
    "statistics": {
      "keyframes": 128,
      "points": 18500,
      "processing_time_ms": 3842
    }
  },
  "usage": {
    "credits_charged": 8
  }
}

{
  "id": "cal_abc123456789",
  "object": "camera_calibration",
  "created": 1704067200,
  "status": "completed",
  "result": {
    "message": "Calibration completed successfully",
    "intrinsics": {
      "fx": 500.0,
      "fy": 500.0,
      "cx": 320.0,
      "cy": 240.0
    },
    "distortion": [...],
    "success": true
  },
  "usage": {
    "credits_charged": 10
  }
}

🤖 MCP Tools (Model Context Protocol)

XRollout exposes an MCP-compatible JSON-RPC endpoint at /mcp/v1. This lets you call XRollout tools directly from AI agents and MCP clients. Authentication uses the same Authorization: Bearer header as the REST API.

MCP Request Format

All MCP calls use JSON-RPC 2.0 over HTTP POST:

POST /mcp/v1
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "TOOL_NAME",
    "arguments": { ... }
  }
}

List Available Tools

curl -X POST https://your-domain/mcp/v1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Tool: xrollout_create_article

Create and publish an article on XRollout using Markdown content. This tool is free.

Parameters

Example — cURL

curl -X POST https://your-domain/mcp/v1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "xrollout_create_article",
      "arguments": {
        "title": "My Robotics Research Notes",
        "content": "## Introduction\n\nThis article explores recent advances in robot manipulation...",
        "tags": "robotics, research, manipulation",
        "published": true
      }
    }
  }'

Example — Python

import json, urllib.request

API_KEY = "YOUR_API_KEY"
URL = "https://your-domain/mcp/v1"

# Read a local Markdown file
with open("my-article.md") as f:
    content = f.read()

payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "xrollout_create_article",
        "arguments": {
            "title": "My Robotics Research Notes",
            "content": content,
            "tags": "robotics, research",
            "published": True
        }
    }
}

req = urllib.request.Request(
    URL,
    data=json.dumps(payload).encode(),
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}"
    }
)
with urllib.request.urlopen(req) as resp:
    result = json.loads(resp.read())
    print(result)

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{'status': 'created', 'article_id': 42, 'slug': 'my-robotics-research-notes', 'url': '/articles/my-robotics-research-notes', 'title': 'My Robotics Research Notes', 'published': true}"
      }
    ],
    "isError": false
  }
}

⚠️ Errors

All errors follow a standard JSON format:

{
  "error": {
    "message": "Human-readable error message",
    "type": "error_type",
    "code": "specific_error_code"
  }
}

🔍 Example Usage — REST API (cURL)

curl -X POST https://your-domain/v1/slam/process \
  -H "Authorization: Bearer sk_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "video_url": "https://example.com/robot_video.mp4",
      "mode": "cnn",
      "target_fps": 15,
      "max_size": 640
    },
    "options": {
      "output_format": "json",
      "return_point_cloud": true
    }
  }'