Skip to main content
ROBOSPORT.API
Account
Menu

RoboSport developers / web API

BUILD AGAINST THE SIGNAL.

Use the implemented first-party account and event-simulation API today, then follow the separately labelled RSDP draft toward production integrations.

Quickstart

FROM SIGN-IN TO RSDP MESSAGES

Register with a cookie jar, carry the CSRF companion token on mutations, then create and step a private deterministic event.

Open visual simulator
OpenAPI 3.1application/vnd.oai.openapi+json;version=3.1

Machine-readable web API contract

Download the generated contract checked against this build's documented routes, response shapes and authoritative RSDP schemas.

Download OpenAPI JSON
Register and create a sandbox simulationbash
# 1. Use the deployed RoboSport web API and create an account.
export ROBOSPORT_ORIGIN='https://robosport.live'

curl --fail-with-body --silent --show-error \
  --cookie-jar robosport.cookies \
  --header "origin: $ROBOSPORT_ORIGIN" \
  --header 'content-type: application/json' \
  --data '{"display_name":"Pilot","email":"you@example.com","password":"change-me"}' \
  "$ROBOSPORT_ORIGIN/api/v1/auth/register"

# 2. Read the readable CSRF companion cookie. The session JWT stays HttpOnly.
CSRF_TOKEN="$(awk '$6 == "rs_csrf" || $6 == "__Host-rs_csrf" {print $7}' robosport.cookies | tail -n 1)"
IDEMPOTENCY_KEY="$(uuidgen | tr '[:upper:]' '[:lower:]')"

# 3. Create a deterministic sandbox run.
curl --fail-with-body --silent --show-error \
  --cookie robosport.cookies \
  --cookie-jar robosport.cookies \
  --header 'content-type: application/json' \
  --header "origin: $ROBOSPORT_ORIGIN" \
  --header "x-csrf-token: $CSRF_TOKEN" \
  --header "idempotency-key: $IDEMPOTENCY_KEY" \
  --data '{"scenario_id":"autonomous-sprint","scenario_version":1,"seed":42,"speed":1}' \
  "$ROBOSPORT_ORIGIN/api/v1/simulations"
Step the simulation and read messagesbash
# Replace SIMULATION_ID and EXPECTED_REVISION with values from create/read.
curl --fail-with-body --silent --show-error \
  --cookie robosport.cookies \
  --header 'content-type: application/json' \
  --header "origin: $ROBOSPORT_ORIGIN" \
  --header "x-csrf-token: $CSRF_TOKEN" \
  --header "idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  --data '{"action":"step","expected_revision":1}' \
  "$ROBOSPORT_ORIGIN/api/v1/simulations/SIMULATION_ID/actions"

curl --fail-with-body --silent --show-error \
  --cookie robosport.cookies \
  "$ROBOSPORT_ORIGIN/api/v1/simulations/SIMULATION_ID/messages?limit=100"

Web identity

PASSWORD IN. TOKEN HIDDEN.

Passwords establish a first-party RoboSport session. The access JWT and opaque refresh token remain Secure and HttpOnly; applications should use the cookie and CSRF contract rather than reading or storing tokens.

Browser session

Implemented now

Email/password accounts, rotation, logout, profile, password change and per-browser revocation. New passwords need at least 6 characters; no capitals, numbers or symbols are required.

Integration credentials

A separate future boundary

Producer credentials, API-client scopes and official-source authority are not granted by a normal web account.

POST

/api/v1/auth/register

Create a first-party email/password account and secure browser session.

Authentication
Public
POST

/api/v1/auth/login

Verify an account password and issue rotated HttpOnly session cookies.

Authentication
Public
POST

/api/v1/auth/refresh

Rotate an eligible browser session without exposing its JWT to JavaScript.

Authentication
Session cookie
POST

/api/v1/auth/logout

Revoke the current refresh session and clear its cookies.

Authentication
Session cookie
GET

/api/v1/auth/me

Read the current account and browser-session summary.

Authentication
Session cookie
GET

/api/v1/account

Read the current account profile.

Authentication
Session cookie
PATCH

/api/v1/account

Update the current account display name.

Authentication
Session cookie
POST

/api/v1/account/password

Change the password and revoke other browser sessions.

Authentication
Session cookie
GET

/api/v1/account/sessions

List revocable browser sessions without returning tokens or IP addresses.

Authentication
Session cookie
DELETE

/api/v1/account/sessions/{session_id}

Revoke another browser session owned by the account.

Authentication
Session cookie

Event laboratory

DETERMINISTIC SANDBOX API

Runs use explicit revisions for controls. Restart creates a new run, while messages and snapshots keep the original run intact.

GET

/api/v1/simulation-scenarios

List deterministic event templates available to the signed-in user.

Authentication
Session cookie
GET

/api/v1/simulations

List private simulation runs owned by the current account.

Authentication
Session cookie
POST

/api/v1/simulations

Create an isolated sandbox contest from a versioned scenario and optional seed.

Authentication
Session cookie
GET

/api/v1/simulations/{simulation_id}

Read one owned run, its virtual clock and revision.

Authentication
Session cookie
POST

/api/v1/simulations/{simulation_id}/actions

Start, pause, resume, step, cancel or restart using optimistic revision checks.

Authentication
Session cookie
GET

/api/v1/simulations/{simulation_id}/messages

Page through schema-valid synthetic RSDP messages using an opaque cursor.

Authentication
Session cookie
GET

/api/v1/simulations/{simulation_id}/snapshot

Read the current projected sandbox contest and entry state.

Authentication
Session cookie

Failure contract

PROBLEMS STAY MACHINE-READABLE

Failures use JSON Problem Details. Authentication errors remain generic, validation errors identify correctable fields and private values never appear in responses.

Problem Details responsejson
{
  "type": "https://robosport.live/problems/invalid-request",
  "title": "Request validation failed",
  "status": 400,
  "detail": "Review the invalid fields and try again."
}
401Sign in or refresh the browser session.
403The request origin, CSRF token or authorization policy was rejected.
404The route or resource was not found. Resources owned by another account are deliberately hidden.
409The simulation revision changed; read the run and retry deliberately.
400The JSON body or one of its fields is invalid.
429A defensive request limit or simulator storage quota was reached; rejected mutations are not partially applied.

RSDP v0.1 / proposed production service

THE CONTRACT IS AHEAD OF THE SERVICE.

The repository contains generated OpenAPI, AsyncAPI and JSON Schema types, but the public registry, ingest, live gateway and signed-result services below are not connected.

Understand RSDP
GETDraft / not connected

/v1/competitions

Proposed production competition registry read.

Authentication
Scoped bearer token
POSTDraft / not connected

/v1/ingest/messages

Proposed scoped producer ingestion boundary for one to 1,000 RSDP messages.

Authentication
Scoped bearer token
GETDraft / not connected

/v1/contests/{contest_id}/events

Proposed historical canonical event query and cursor recovery path.

Authentication
Scoped bearer token
GETDraft / not connected

/v1/contests/{contest_id}/results

Proposed versioned result-record query.

Authentication
Scoped bearer token