API reference, v1

GET/api/v1/robots

Every robot in the registry, open and closed. Filter by class, openness facets, verb state and text.

curl -s 'https://hyperspawn.io/api/v1/robots?class=humanoid&open=cad,bom&limit=10'

• 200Page of RobotSummary. X-Total-Count header carries the total.
• 400Unknown class, facet or verb

GET/api/v1/robots/{org}/{slug}

The full registry record with sources, openness score, level, and links to the same robot on every verb domain.

curl -s 'https://hyperspawn.io/api/v1/robots/hyperspawn/dropbear'

• 200RobotDetail
• 404Unknown robot. details.suggestions lists near matches.

GET/api/v1/robots/{org}/{slug}/package

BOM, fabrication parts, assembly step graph, firmware and policies, plus computed totals. Safety-critical steps are listed in computed.safetySteps.

curl -s 'https://hyperspawn.io/api/v1/robots/hyperspawn/dropbear/package'

• 200BuildPackage
• 404Unknown robot, or code=no_build_package when none is compiled yet

GET/api/v1/robots/{org}/{slug}/sourcing

Resolves each BOM line to the cheapest priced offer in the region (GLOBAL offers count everywhere). Lines without a price come back in `unpriced`, never dropped.

curl -s 'https://hyperspawn.io/api/v1/robots/hyperspawn/dropbear/sourcing?region=IN'

• 200Sourcing
• 400Bad region
• 404Unknown robot or no build package

GET/api/v1/search

Ranked text search across the registry. Every token must match.

curl -s 'https://hyperspawn.io/api/v1/search?q=open%20humanoid'

• 200SearchResult
• 400Missing q

GET/api/v1/compare

Side-by-side specs, openness facets, levels and verb states for 2 to 6 robots. null means not published.

curl -s 'https://hyperspawn.io/api/v1/compare?ids=unitree/g1,unitree/h1'

• 200Comparison
• 400Fewer than 2 or more than 6 ids
• 404Unknown id

GET/api/v1/places

Makers, labs, build sites and spaces with coordinates. verified=true only for reviewed build reports.

curl -s 'https://hyperspawn.io/api/v1/places'

• 200PlaceList
• 400Unknown kind

GET/api/v1/levels

L0 Indexed to L5 Certified, the gate for each, and how many robots sit at each level.

curl -s 'https://hyperspawn.io/api/v1/levels'

• 200Levels

GET/api/v1/openness/{org}/{slug}

The computed 0-100 openness score with per-facet weights, licenses, models and repos.

curl -s 'https://hyperspawn.io/api/v1/openness/unitree/g1'

• 200Openness
• 404Unknown robot. details.suggestions lists near matches.

GET/api/v1/builds

Build reports a person reviewed and approved: robot, builder display name, city, country, city-centre geo, photos, date. No emails or contacts, never a street address. Newest first.

curl -s 'https://hyperspawn.io/api/v1/builds'

• 200BuildList. X-Total-Count header carries the total.
• 400Bad country
• 503Build storage not configured

GET/api/v1/builds/{org}/{slug}

Approved build reports for one robot. The count is the L4 Built evidence for its package.

curl -s 'https://hyperspawn.io/api/v1/builds/hyperspawn/dropbear'

• 200RobotBuilds
• 404Unknown robot. details.suggestions lists near matches.
• 503Build storage not configured

GET/api/v1/companies

Humanoid and robot makers, robot foundation-model companies, research labs, platforms and component makers. Funding, last round and valuation appear only with a dated source URL.

curl -s 'https://hyperspawn.io/api/v1/companies?kind=humanoid-maker&country=CN'

• 200CompanyList
• 400Unknown kind or status

GET/api/v1/companies/{id}

One company with its robots, brain models, timeline events and links to its filtered news, video and paper feeds.

curl -s 'https://hyperspawn.io/api/v1/companies/unitree'

• 200CompanyDetail
• 404Unknown company. details.suggestions lists near matches.

GET/api/v1/models

Robot foundation models: VLAs, world models, locomotion and whole-body controllers. Openness, license, embodiments and verified links to paper, code and weights.

curl -s 'https://hyperspawn.io/api/v1/models?open=open-weights'

• 200ModelList
• 400Unknown kind or open value

GET/api/v1/timeline

Dated, sourced events in humanoid and open robotics history: robots, companies, funding, research and open-source releases.

curl -s 'https://hyperspawn.io/api/v1/timeline?from=2025&kind=open-source'

• 200Timeline
• 400Bad date, kind or order

GET/api/v1/events

Robotics conferences, competitions and expos with dates, city and coordinates. Default: upcoming and live, soonest first.

curl -s 'https://hyperspawn.io/api/v1/events?when=upcoming'

• 200EventList
• 400Bad when, kind or year

GET/api/v1/news

Live: robotics outlets' RSS (The Robot Report, IEEE Spectrum, Humanoids Daily, Robohub, TechCrunch, and more) plus Brave News search, deduped and tagged with registry robot, company and model ids. Headline, source, date, link and a short text summary; no images. Cached 30 minutes; failed sources are listed, never fatal.

curl -s 'https://hyperspawn.io/api/v1/news?limit=10'

• 200NewsList. sources[] reports each upstream's status.
• 400Bad robot id or since

GET/api/v1/papers

Live from the arXiv API: newest cs.RO papers on humanoids, legged locomotion, whole-body control, VLAs, dexterous manipulation and sim-to-real, tagged with registry ids. Cached 30 minutes.

curl -s 'https://hyperspawn.io/api/v1/papers?q=humanoid&limit=10'

• 200PaperList
• 400Bad robot id or since

GET/api/v1/videos

Live from official maker YouTube channels (channel RSS). Returns video ids with embed and watch URLs, tagged with registry ids. Cached 30 minutes.

curl -s 'https://hyperspawn.io/api/v1/videos?company=unitree&limit=6'

• 200VideoList
• 400Bad robot id or since

POST/api/v1/reports

build-report, correction, training-run, bounty-claim, robot (propose a robot for the registry). Stored privately for human review; nothing public changes until reviewed.

curl -X POST https://hyperspawn.io/api/v1/reports \
  -H 'Content-Type: application/json' \
  -d '{ "kind": "correction", "robot": "unitree/g1", "message": "DOF is 23 in the base config", "url": "https://www.unitree.com/g1" }'

• 201Stored. Returns the submission id.
• 400Invalid JSON or validation failed. details.issues lists each field.
• 413Body over 64 KB
• 415Content-Type is not application/json
• 429Rate limited. details.retryAfterSeconds says when to retry.
• 502Storage write failed. Nothing was stored.
• 503Intake storage not configured. Nothing was stored.

POST/api/v1/requests

crew-request, team-application, contact, careers, investor. contact, careers, investor and team-application require email.

curl -X POST https://hyperspawn.io/api/v1/requests \
  -H 'Content-Type: application/json' \
  -d '{ "kind": "crew-request", "robot": "hyperspawn/dropbear", "city": "Pune", "country": "IN", "message": "Need help with actuator bring-up" }'

• 201Stored. Returns the submission id.
• 400Invalid JSON or validation failed. details.issues lists each field.
• 413Body over 64 KB
• 415Content-Type is not application/json
• 429Rate limited. details.retryAfterSeconds says when to retry.
• 502Storage write failed. Nothing was stored.
• 503Intake storage not configured. Nothing was stored.

GET/api/v1/jobs

Recent training jobs (public fields) and the GPU workers that polled in the last 2 minutes. A job is queued until a worker claims it; nothing here is simulated.

curl -s 'https://hyperspawn.io/api/v1/jobs?limit=5'

• 200{ workers, jobs[], storage }
• 503Job storage not configured

POST/api/v1/jobs

Humanoids with a sim model only. task: stand | walk | push | imitate (imitate needs a motion library retargeted to the robot). backend: mjlab | isaaclab. Returns the job id and a cancel token. It runs when a GPU worker (hs-train-worker) claims it.

curl -X POST https://hyperspawn.io/api/v1/jobs \
  -H 'Content-Type: application/json' \
  -d '{ "robot": "unitree/g1", "task": "stand", "backend": "mjlab", "hyperparams": { "numEnvs": 4096, "maxIterations": 1500, "seed": 42 }, "budget": { "gpuMinutes": 30 } }'

• 201Queued. Returns id, spec, cancelToken, url, page.
• 400Validation failed (unknown robot, not a humanoid, task not available for it)
• 429Rate limited (6 jobs per hour per address)
• 503Job storage not configured. Nothing was stored.

GET/api/v1/jobs/{id}

Spec, status, queue position, worker, metric points reported by the worker, log tail, and artifact URLs (policy.onnx, contract.json, eval.json, eval.mp4).

curl -s 'https://hyperspawn.io/api/v1/jobs/20261011T095226-cd52484da6cdb656'

• 200Job
• 404No such job

GET/api/v1/jobs/next

For GPU workers. Claims the oldest queued job matching X-Worker-Backends (atomic, one worker per job) and returns it; 204 when the queue is empty. Polling also marks the worker online.

curl -s 'https://hyperspawn.io/api/v1/jobs/next' \
  -H "Authorization: Bearer $WORKER_TOKEN" -H 'X-Worker-Name: my-gpu' -H 'X-Worker-Backends: mjlab'

• 200{ job: { id, spec } }
• 204Queue empty
• 401Missing or wrong worker token

PATCH/api/v1/jobs/{id}

Heartbeat (renews a 5-minute lease), progress, metric points, log lines, final status (succeeded | failed). Answers cancel: true once the creator canceled.

curl -X PATCH https://hyperspawn.io/api/v1/jobs/{id} \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $WORKER_TOKEN" -H 'X-Worker-Name: my-gpu' \
  -d '{ "progress": { "iteration": 120, "maxIterations": 1500, "elapsedS": 300 }, "metrics": [ { "t": 300, "it": 120, "reward": 12.4, "episodeS": 8.1, "fps": 98000 } ], "log": [ "iteration 120" ] }'

• 200{ ok, status, cancel }
• 401Missing or wrong worker token
• 409Not this worker's job, or the job is finished

POST/api/v1/jobs/{id}/artifacts

Raw body, ?name=policy.onnx | contract.json | eval.json | eval.mp4 | metrics.csv. Max 4 MB. Stored privately; served at GET /api/v1/jobs/{id}/artifacts/{name}.

curl -X POST 'https://hyperspawn.io/api/v1/jobs/{id}/artifacts?name=policy.onnx' \
  -H "Authorization: Bearer $WORKER_TOKEN" -H 'X-Worker-Name: my-gpu' \
  --data-binary @policy.onnx

• 201{ ok, artifact }
• 401Missing or wrong worker token
• 413Over 4 MB

Intake kinds

Both POST endpoints accept every kind; the table shows the canonical one. Bodies are JSON, at most 64 KB, validated field by field. Accepted submissions are written to private storage and return 201 with an id. A human reviews each one before anything public changes. If storage is not configured the API returns 503 and stores nothing. Light rate limit: 12 submissions per 10 minutes per address.

Optional on every kind: name, email, message, url, links[], source. Kind-specific: photos[], logs[], city, country (build-report); task, policy, hardware (training-run); field (correction); maker, class, repos[], license (robot); role (careers); fund (investor).

MCP

https://hyperspawn.io/mcp speaks MCP over streamable HTTP, stateless, no auth. Tools are read-only and return JSON text. Errors come back as tool results with isError: true.

claude mcp add --transport http hyperspawn https://hyperspawn.io/mcp

• search_robots(query, limit?)Ranked text search over the registry.
• get_robot(id)Full record for org/slug, with sources and sibling-domain links.
• get_build_package(id)BOM, fabrication, assembly steps, firmware, policies.
• source_parts(robot, region)Resolve BOM lines to offers in IN, US, EU or CN; unpriced lines listed.
• compare_robots(ids[])Side-by-side specs, openness and verbs for 2 to 6 robots.
• list_open_robots(facets?, class?, verb?)Robots whose listed facets are all public.
• verification_levels()The L0-L5 ladder and robot counts per level.
• get_openness(id)Computed openness score with per-facet weights and licenses.
• list_verified_builds(robot?, country?, builder?)Human-reviewed build reports: builder, city, city-centre geo, photos, date.
• list_companies(kind?, country?, query?)Robot makers, foundation-model companies, labs and component makers, with sourced funding.
• get_company(id)One company with its robots, brain models and timeline.
• list_brain_models(company?, kind?, open?, query?)Robot foundation models (VLAs, world models) with paper, code and weights links.
• get_timeline(kind?, robot?, company?, from?, to?)Dated, sourced events in humanoid and open robotics history.
• list_events(when?, kind?, country?)Upcoming and past robotics conferences, competitions and expos.
• get_news(robot?, company?, query?, limit?)Live robotics news (outlet RSS + Brave News), deduped, tagged, links only.
• get_papers(robot?, company?, query?, limit?)Newest arXiv cs.RO papers on humanoids, locomotion and VLAs.
• get_videos(company?, robot?, query?, limit?)Latest videos from official maker YouTube channels, with embed URLs.