---
title: getactuators API
description: Free, read-only REST API for robot actuator and robot specs: endpoints, curl examples, pagination, errors, rate limits and versioning.
canonical: https://getactuators.com/docs/api
last-updated: 2026-09-26
---

# getactuators API

A free, public, **read-only** REST API over every actuator and robot on [getactuators](https://getactuators.com/). JSON in, JSON out, no key required. The same data is available to AI agents over [MCP](https://getactuators.com/mcp).

## Quickstart

```bash
curl -s "https://getactuators.com/api/v1/actuators?q=humanoid&limit=3"
```

## Authentication

None. Every endpoint is anonymous: no API key, no OAuth, no account. Just call it.

## Base URL

`https://getactuators.com`. All paths below are relative to it. CORS is open (`Access-Control-Allow-Origin: *`), so browsers can call it directly.

## Sandbox and safety

The API is read-only: no endpoint creates, changes or deletes anything, so production doubles as the sandbox and any call is safe to retry. `POST /api/v1/actuators/compare` accepts an `Idempotency-Key` header for client compatibility, but it is never needed.

## Endpoints

| Method | Path | Summary |
| --- | --- | --- |
| GET | `/api` | [API index](#get_api_index) |
| GET | `/openapi.json` | [OpenAPI document](#get_openapi_spec) |
| GET | `/api/v1/actuators` | [Search and filter actuators](#list_actuators) |
| GET | `/api/v1/actuators/compare` | [Fetch several actuators by id](#compare_actuators) |
| POST | `/api/v1/actuators/compare` | [Fetch several actuators by id (JSON body)](#compare_actuators_batch) |
| GET | `/api/v1/actuators/{id}` | [Get one actuator](#get_actuator) |
| GET | `/api/v1/robots` | [List robots](#list_robots) |
| GET | `/api/v1/robots/{id}` | [Get one robot with its joint motors](#get_robot) |
| GET | `/api/v1/categories` | [List actuator categories](#list_categories) |
| GET | `/api/v1/brands` | [List actuator brands](#list_brands) |
| GET | `/api/v1/use-cases` | [List use-case tags](#list_use_cases) |

### GET /api

**API index.** Machine-readable entry point: every endpoint with its method and summary, plus links to the docs, the OpenAPI document and the MCP server. Operation id: `get_api_index`.

```bash
curl -s "https://getactuators.com/api"
```

### GET /openapi.json

**OpenAPI document.** This OpenAPI 3.1 description of the API (also at /api/openapi.json). Operation id: `get_openapi_spec`.

```bash
curl -s "https://getactuators.com/openapi.json"
```

### GET /api/v1/actuators

**Search and filter actuators.** List robot actuators with optional filters (text, category, brand, use case, torque, mass, price, backdrivability, onboard driver) and sorting. Cursor-paginated: follow `pagination.next_cursor` until `has_more` is false. Operation id: `list_actuators`.

| Parameter | In | Description |
| --- | --- | --- |
| `q` | query | Free-text search over id, name, brand, category, use cases, notes. |
| `category` | query | Category slug. |
| `brand` | query | Exact brand name (case-insensitive). |
| `use_case` | query | Use-case tag, e.g. `humanoid`. |
| `min_peak_torque_nm` | query | Minimum peak torque in N·m. |
| `max_weight_g` | query | Maximum mass in grams. |
| `max_price_usd` | query | Maximum list price in USD. |
| `backdrivable` | query | Only backdrivable (`true`) or non-backdrivable (`false`). |
| `integrated_driver` | query | Only actuators with (`true`) or without an onboard driver. |
| `sort` | query | Sort field (default: id). |
| `order` | query | Sort direction (default desc when `sort` is set). |
| `limit` | query | Page size, 1 to 100 (default 25). |
| `cursor` | query | Opaque `pagination.next_cursor` from the previous page. |

```bash
curl -s "https://getactuators.com/api/v1/actuators?category=qdd_proprioceptive&min_peak_torque_nm=20&sort=torque_density_nm_per_kg&limit=5"
```

### GET /api/v1/actuators/compare

**Fetch several actuators by id.** Batch lookup of up to 20 actuators by id for side-by-side comparison. Results keep request order; unknown ids are listed in `not_found` instead of failing the whole request. Operation id: `compare_actuators`.

| Parameter | In | Description |
| --- | --- | --- |
| `ids` | query, required | Comma-separated actuator ids, 1 to 20, e.g. `a,b,c`. |

```bash
curl -s "https://getactuators.com/api/v1/actuators/compare?ids=robstride-02,cubemars-ak80-9"
```

### POST /api/v1/actuators/compare

**Fetch several actuators by id (JSON body).** Same as `compare_actuators` but takes `{"ids": [...]}` (1 to 20 ids) as a JSON body. Read-only and safe to retry: an `Idempotency-Key` header is accepted but not required. Operation id: `compare_actuators_batch`.

```bash
curl -s -X POST "https://getactuators.com/api/v1/actuators/compare" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["robstride-02", "cubemars-ak80-9", "not-a-real-id"]}'
```

### GET /api/v1/actuators/{id}

**Get one actuator.** Full specifications for one actuator, plus `robots_using`: the robots in the catalog whose joints use it. Operation id: `get_actuator`.

| Parameter | In | Description |
| --- | --- | --- |
| `id` | path, required | Actuator id (slug). |

```bash
curl -s "https://getactuators.com/api/v1/actuators/robstride-02"
```

### GET /api/v1/robots

**List robots.** Robots (arms, humanoids, quadrupeds) in the catalog with headline specs. Cursor-paginated like `list_actuators`. Operation id: `list_robots`.

| Parameter | In | Description |
| --- | --- | --- |
| `q` | query | Free-text search over name, brand, summary. |
| `brand` | query | Exact brand name (case-insensitive). |
| `limit` | query | Page size, 1 to 100 (default 25). |
| `cursor` | query | Opaque `pagination.next_cursor` from the previous page. |

```bash
curl -s "https://getactuators.com/api/v1/robots?limit=10"
```

### GET /api/v1/robots/{id}

**Get one robot with its joint motors.** One robot with every joint group resolved to its motor specs, linked to the matching catalog actuator when there is one. Operation id: `get_robot`.

| Parameter | In | Description |
| --- | --- | --- |
| `id` | path, required | Robot id (slug). |

```bash
curl -s "https://getactuators.com/api/v1/robots/i2rt-yam"
```

### GET /api/v1/categories

**List actuator categories.** Every category slug with a label, description and actuator count. Operation id: `list_categories`.

```bash
curl -s "https://getactuators.com/api/v1/categories"
```

### GET /api/v1/brands

**List actuator brands.** Every brand name (usable as the `brand` filter) with its actuator count. Operation id: `list_brands`.

```bash
curl -s "https://getactuators.com/api/v1/brands"
```

### GET /api/v1/use-cases

**List use-case tags.** Every use-case tag (usable as the `use_case` filter) with its actuator count. Operation id: `list_use_cases`.

```bash
curl -s "https://getactuators.com/api/v1/use-cases"
```

## Pagination

List endpoints are cursor-paginated. Pass `limit` (1 to 100, default 25). Each response has `pagination: { next_cursor, has_more, total }`; repeat the same query with `cursor=<next_cursor>` until `has_more` is `false`. Cursors are opaque and tied to the filters they were issued for.

```bash
curl -s "https://getactuators.com/api/v1/actuators?limit=25&cursor=<next_cursor>"
```

## Errors

Every error is [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json` with a stable `code`, a `hint` on how to fix the request and, for validation errors, a per-field `errors` array. Unknown `/api/*` paths return a JSON 404, never an HTML page.

```json
{
  "type": "https://getactuators.com/docs/api#error-not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No actuator with id \"nope\".",
  "code": "not_found",
  "hint": "Ids are slugs; list valid ones with GET /api/v1/actuators?q=<search>.",
  "instance": "/api/v1/actuators/nope",
  "docs": "https://getactuators.com/docs/api#errors"
}
```

| Code | Status | Meaning |
| --- | --- | --- |
| `invalid_parameter` | 400 | A query parameter has the wrong type or value; see `errors[]`. |
| `invalid_cursor` | 400 | The cursor is malformed or was issued for other filters. |
| `invalid_json` | 400 | The POST body is not JSON. |
| `not_found` | 404 | No actuator or robot with that id. |
| `unknown_endpoint` | 404 | The path is not part of the API. |
| `method_not_allowed` | 405 | Wrong HTTP method; the `Allow` header lists valid ones. |
| `unsupported_media_type` | 415 | POST bodies must be `application/json`. |
| `validation_failed` | 422 | The JSON body does not match the schema; see `errors[]`. |
| `rate_limited` | 429 | Slow down and retry after `Retry-After` seconds. |
| `internal_error` | 500 | Server bug; retry, then report it on GitHub. |

## Rate limits

120 requests per 60 seconds per client IP. Every response reports the budget in the IETF `RateLimit` and `RateLimit-Policy` headers and in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (seconds). Past the limit you get a 429 problem with `Retry-After`. Responses are cacheable for 5 minutes (`Cache-Control: public, max-age=300`).

## Versioning and deprecation

The major version is in the path (`/api/v1`) and echoed in the `API-Version` response header. Breaking changes ship only under a new path version (/api/v2). A deprecated operation keeps working for at least 6 months after it is marked: responses carry `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers plus a `Link rel="deprecation"` to the changelog, and the operation is flagged `deprecated: true` here. Additive changes (new fields, endpoints, filters) can land at any time, so clients should ignore unknown fields.

## Machine-readable resources

- [OpenAPI 3.1 document](https://getactuators.com/openapi.json) (also at `/api/openapi.json`); every operation has a snake_case `operationId` usable as a function-calling tool name.
- [API index](https://getactuators.com/api): JSON list of endpoints.
- [MCP server](https://getactuators.com/mcp): the same catalog as MCP tools, no auth.
- [llms.txt](https://getactuators.com/llms.txt): site overview for language models.
- [This page as Markdown](https://getactuators.com/docs/api.md).
- [Source and issues on GitHub](https://github.com/Miyamura80/getactuators).