API Documentation

Access the RCAN Robot Registry programmatically using our JSON API.

OpenAPI 3.1 Machine-readable OpenAPI 3.1 spec available at /schemas/registry-api.openapi.yaml — compatible with Swagger UI, Redoc, Stoplight, and any OpenAPI toolchain. ⬇ Download spec

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.

Versioned API (v1) — Recommended

The /api/v1/ endpoints are the canonical, versioned API. They include an api_version field in every response and add new capabilities like full-text search and RURI resolution.

GET /api/v1/index.json

API discovery endpoint. Returns the current API version, base URL, total robot count, and a list of all available endpoints with descriptions.

Example Request

curl "https://rcan.dev/api/v1/index.json"

Example Response

{
  "api_version": "1.0",
  "base_url": "https://rcan.dev/api/v1",
  "total_robots": 10,
  "endpoints": [
    { "path": "/api/v1/robots.json", "method": "GET", "description": "List all robots..." },
    ...
  ]
}

GET /api/v1/robots.json

Versioned robot list. Mirrors /api/robots.json but adds api_version and the ?q= full-text search parameter.

Query Parameters

Parameter	Type	Description
`q`	string	Full-text search across name, manufacturer, description, and tags (case-insensitive substring)
`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 Requests

# Full-text search
curl "https://rcan.dev/api/v1/robots.json?q=lidar"

# Filter + paginate
curl "https://rcan.dev/api/v1/robots.json?status=active&limit=5"

Example Response

{
  "api_version": "1.0",
  "success": true,
  "data": [ ... ],
  "meta": {
    "total": 3,
    "count": 3,
    "limit": null,
    "offset": 0,
    "filters": { "status": null, "manufacturer": null, "tag": null, "q": "lidar" }
  }
}

GET /api/v1/robots/[rrn].json

Versioned single-robot lookup by RRN. Same as /api/robots/[rrn].json but includes api_version.

Example Request

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

Example Response

{
  "api_version": "1.0",
  "success": true,
  "data": {
    "rrn": "RRN-00000001",
    "name": "TurtleBot 3 Burger",
    ...
  }
}

GET /api/v1/ruri/[encoded-ruri].json

Resolve a RURI to a robot registry entry. Pass the URL-encoded RURI as the path segment. Robots must have a ruri field set in their registry entry to be resolvable.

How to build the URL

const ruri = 'rcan://rcan.dev/opencastor/rover/abcdef12';
const url = `https://rcan.dev/api/v1/ruri/${encodeURIComponent(ruri)}.json`;
// → /api/v1/ruri/rcan%3A%2F%2Frcan.dev%2Fopencastor%2Frover%2Fabcdef12.json

Example Response (200)

{
  "api_version": "1.0",
  "success": true,
  "ruri": "rcan://rcan.dev/opencastor/rover/abcdef12",
  "data": { "rrn": "RRN-00000042", "name": "OpenCastor Rover", ... }
}

Error Response (404)

{
  "api_version": "1.0",
  "success": false,
  "error": "No robot found for this RURI",
  "ruri": "rcan://rcan.dev/unknown/model/00000000"
}

Legacy Endpoints

These endpoints remain available for backwards compatibility. New integrations should prefer the /api/v1/ equivalents above.

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