API Documentation

Programmatic access to Humanoid Inc data. Requires an Analyst subscription or per-request x402 payment.

Authentication

All API requests must include a valid API key in the Authorization header.

Authorization: Bearer hum_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Generate API keys from Account Settings.

x402 Payment Gating

If your subscription is not active, the API returns 402 Payment Required with the following x402-standard headers:

HTTP/1.1 402 Payment Required
X-Payment-Required: true
X-Upgrade-URL: https://your-domain.com/pricing

{
  "error": "Payment Required",
  "message": "This endpoint requires a paid subscription...",
  "upgrade_url": "https://your-domain.com/pricing",
  "payment_required": true,
  "code": "x402"
}

Rate Limiting

All API endpoints are rate limited. Limits vary by access tier:

TierRequests / HourKey
Free / Unauthenticated60IP address
Pro (Analyst)1,000API key
Team (Enterprise)2,000API key

Every response includes rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1714500000

When the rate limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating seconds until the limit resets.

Endpoints

GET/api/v1

API entrypoint. Returns available endpoints and authentication info.

GET/api/v1/companies

List all companies. Supports filtering by query, country, and type.

Query Parameters
  • q (optional) — Search by name, program, or HQ
  • country (optional) — Filter by country in HQ field
  • type (optional) — Filter by company type (public, private, subsidiary, etc.)
GET/api/v1/companies/{id}

Get a single company by ID.

GET/api/v1/robots

List all robots. Supports filtering by query, use case, readiness, and company.

Query Parameters
  • q (optional) — Search by name or AI system
  • use_case (optional) — Filter by target use case
  • readiness (optional) — Filter by readiness level (production, pilot, prototype, limited_production)
  • company_id (optional) — Filter by company ID
GET/api/v1/robots/{id}

Get a single robot by ID.

GET/api/v1/market

Market size, regional breakdown, trends, and price segments.

Query Parameters
  • view (optional) — Filter by view: global, regional, trends, segments
GET/api/v1/search

Search across companies and robots by keyword.

Query Parameters
  • q — Search query
  • limit (optional) — Max results (default 20, max 100)