API Documentation

Access the RCAN Robot Registry programmatically using our JSON API.

Base URL

https://rcan.dev/api

Authentication

No authentication required. The API is publicly accessible and read-only.

Rate Limits

No rate limits are currently enforced. Please be respectful and cache responses when possible.

Endpoints

GET /api/robots.json

List all registered robots with optional filtering and pagination.

Query Parameters

Parameter Type Description
status string Filter by status: active, retired, prototype, concept
manufacturer string Filter by manufacturer name (case-insensitive, partial match)
tag string Filter by tag (exact match, case-insensitive)
limit integer Maximum number of results to return
offset integer Number of results to skip (for pagination)

Example Request

curl "https://rcan.dev/api/robots.json?status=active&limit=5"

Example Response

{
  "success": true,
  "data": [
    {
      "rrn": "RRN-00000001",
      "name": "TurtleBot 3 Burger",
      "manufacturer": "ROBOTIS",
      "model": "turtlebot3_burger",
      "description": "A compact, affordable mobile robot...",
      "status": "active",
      "tags": ["education", "mobile", "ros2"]
    }
  ],
  "meta": {
    "total": 10,
    "count": 5,
    "limit": 5,
    "offset": 0
  }
}
GET /api/robots/[rrn].json

Get detailed information about a specific robot by its RRN.

Path Parameters

Parameter Type Description
rrn string Robot Registration Number (e.g., RRN-00000001)

Example Request

curl "https://rcan.dev/api/robots/RRN-00000001.json"

Example Response

{
  "success": true,
  "data": {
    "rrn": "RRN-00000001",
    "name": "TurtleBot 3 Burger",
    "manufacturer": "ROBOTIS",
    "model": "turtlebot3_burger",
    "description": "A compact, affordable mobile robot...",
    "image": "/robots/turtlebot3-burger.svg",
    "production_year": 2017,
    "status": "active",
    "urdf_url": "https://github.com/ROBOTIS-GIT/turtlebot3/...",
    "github_url": "https://github.com/ROBOTIS-GIT/turtlebot3",
    "website": "https://www.robotis.us/turtlebot-3/",
    "specs": {
      "weight_kg": 1.0,
      "dimensions": "138 x 178 x 192 mm",
      "max_speed_mps": 0.22,
      "dof": 2,
      "ros_version": ["ROS 1", "ROS 2"],
      "sensors": ["LDS-01 LiDAR", "IMU", "Wheel Encoders"],
      "compute": "Raspberry Pi 4",
      "battery_life_hours": 2.5
    },
    "owner": {
      "name": "Open Source Community",
      "type": "community",
      "website": "https://emanual.robotis.com/..."
    },
    "ruri": null,
    "submitted_by": "github:continuonai",
    "submitted_date": "2026-01-04",
    "tags": ["education", "mobile", "ros2", "lidar"]
  }
}

Error Response (404)

{
  "success": false,
  "error": "Robot not found",
  "rrn": "RRN-99999999"
}
GET /api/badge/[rrn].svg

Generate an SVG badge for a robot to embed in GitHub READMEs.

Query Parameters

Parameter Type Description
style string Badge style: flat (default), flat-square, plastic
label string Custom left-side label (default: "RCAN")

Example Usage

<!-- Markdown -->
![RCAN](https://rcan.dev/api/badge/RRN-00000001.svg)

<!-- HTML -->
<img src="https://rcan.dev/api/badge/RRN-00000001.svg" alt="RCAN Registry">
GET /api/qr/[rrn].svg

Generate a QR code linking to the robot's registry page.

Query Parameters

Parameter Type Description
size integer QR code size in pixels (default: 200, max: 1000)

Example Usage

curl "https://rcan.dev/api/qr/RRN-00000001.svg?size=300"

Response Format

All JSON responses follow a consistent format:

{
  "success": boolean,      // true if request succeeded
  "data": object | array,  // response payload
  "meta": {                // pagination info (list endpoints only)
    "total": number,
    "count": number,
    "limit": number | null,
    "offset": number
  },
  "error": string          // error message (only on failure)
}

CORS

Cross-Origin Resource Sharing (CORS) is enabled for all origins. You can make API requests directly from browser-based applications.

Caching

Responses include Cache-Control: public, max-age=3600 headers. Data is regenerated on each site build, so caching for up to 1 hour is recommended.

Code Examples

JavaScript / TypeScript

// Fetch all active robots
const response = await fetch('https://rcan.dev/api/robots.json?status=active');
const { data: robots } = await response.json();

// Fetch a specific robot
const robot = await fetch('https://rcan.dev/api/robots/RRN-00000001.json')
  .then(r => r.json())
  .then(r => r.data);

console.log(robot.name); // "TurtleBot 3 Burger"

Python

import requests

# Fetch all robots
response = requests.get('https://rcan.dev/api/robots.json')
robots = response.json()['data']

# Fetch by manufacturer
response = requests.get('https://rcan.dev/api/robots.json',
                       params={'manufacturer': 'ROBOTIS'})
robotis_robots = response.json()['data']

cURL

# List all robots
curl https://rcan.dev/api/robots.json

# Filter by status and limit results
curl "https://rcan.dev/api/robots.json?status=active&limit=5"

# Get specific robot
curl https://rcan.dev/api/robots/RRN-00000001.json