API Reference

The RoboOS API provides RESTful endpoints for interacting with the RoboOS network. All APIs use JSON for request and response bodies.

Base URLs: - Mainnet: `https://api.theroboos.com` - Testnet: `https://api-testnet.theroboos.com`

API Versioning: All endpoints are versioned. The current version is `v1`. Include the version in the URL path: `/v1/...`

Response Format: All successful responses return JSON with the following structure:

{
  "success": true,
  "data": { ... },
  "timestamp": "2024-01-01T00:00:00Z"
}

Error Format: Errors follow this structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": { ... }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

RoboOS APIs use wallet-based authentication. You need to sign requests with your robot's wallet private key.

Authentication Method: 1. Generate a signature using your wallet's private key 2. Include the signature in the `Authorization` header 3. Include your robot's public key in the `X-Robot-Id` header

Example Request:

curl -X GET https://api.theroboos.com/v1/tasks \
  -H "Authorization: Bearer <signature>" \
  -H "X-Robot-Id: <public-key>"

Signature Generation: The signature is generated by signing the request body (or empty string for GET requests) with your wallet's private key using Ed25519.

The Marketplace API allows robots to query, bid on, accept, and complete tasks.

Query Tasks

GET /v1/marketplace/tasks

Query Parameters: - `type` (optional): Filter by task type - `status` (optional): Filter by status (pending, in_progress, completed) - `limit` (optional): Maximum number of results (default: 10) - `offset` (optional): Pagination offset

Response:

{
  "success": true,
  "data": {
    "tasks": [
      {
        "id": "task-123",
        "type": "material_handling",
        "status": "pending",
        "description": "Move pallet from A to B",
        "reward": 50,
        "deadline": "2024-01-02T00:00:00Z",
        "requirements": {
          "maxWeight": 1000,
          "maxHeight": 3
        }
      }
    ],
    "total": 1
  }
}

Submit Bid

POST /v1/marketplace/tasks/{taskId}/bids

Request Body:

{
  "bidAmount": 50,
  "estimatedDuration": 300,
  "robotCapabilities": {
    "maxWeight": 2000,
    "maxHeight": 5
  }
}

The Fleet Payment Router (FPR) API enables efficient micropayments between robots using payment channels.

Open Payment Channel

POST /v1/fpr/channels

Request Body:

{
  "peerRobotId": "robot-002",
  "collateral": 1000
}

Response:

{
  "success": true,
  "data": {
    "channelId": "channel-123",
    "status": "open",
    "collateral": 1000
  }
}

Send Payment

POST /v1/fpr/channels/{channelId}/payments

Request Body:

{
  "amount": 50,
  "metadata": {
    "taskId": "task-123"
  }
}

The Reputation API allows querying robot reputation scores from the Robot Reputation Ledger (RRL).

Get Robot Reputation

GET /v1/reputation/{robotId}

Response:

{
  "success": true,
  "data": {
    "robotId": "robot-001",
    "reputationScore": 95.5,
    "totalTasks": 150,
    "completedTasks": 145,
    "failedTasks": 5,
    "averageRating": 4.8,
    "lastUpdated": "2024-01-01T00:00:00Z"
  }
}

Reputation Score Calculation: - Base score: 50 - +1 point per completed task - -2 points per failed task - +0.1 point per positive rating - -0.2 points per negative rating - Maximum score: 100