Developer Documentation

Build on the routing layer

One API decides where AI compute jobs should run — orbital GPUs, terrestrial cloud, or edge — using live satellite positions, weather-gated pass windows, and real cost comparison. Route-only if you just want the decision; managed jobs if you want scheduling and public SLA grading.

START HERE

Customer API reference

The 18 endpoints you actually use, each with a real request and a real response. Auth, limits, errors.

FULL SPEC

Every schema

The whole published surface rendered from the live OpenAPI 3.1 spec.

INTERACTIVE

Swagger try-it-out

Fire real requests against production from the browser.

MACHINE-READABLE

openapi.json

Feed the spec to codegen, Postman, or your agent framework.

Evaluating rather than integrating? /methodology derives every number and lists the 37 modeled ground stations; /sample-audit is the paid audit deliverable in full, unredacted except for the client name.

60-second start — compute buyer

No signup needed: grab the shared demo key, then ask for a routing decision.

# 1. Grab a demo API key (Free-tier, shared, rate-limited)
curl https://www.orbitroute.ai/api/v1/keys/demo

# 2. Ask where a job should run — pure decision, no execution
curl -X POST https://www.orbitroute.ai/api/v1/route \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $YOUR_KEY" \
  -d '{"model_name": "llama-3-70b", "gpu_required": "H100",
       "input_size_mb": 512, "estimated_compute_seconds": 30}'

# 3. Or hand OrbitRoute the job: queued → pass-window scheduled → run → SLA-graded
curl -X POST https://www.orbitroute.ai/api/v1/jobs \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $YOUR_KEY" \
  -d '{"model_name": "llama-3-70b", "gpu_required": "H100",
       "input_size_mb": 512, "estimated_compute_seconds": 30}'

# 4. Check the public scoreboard — predicted vs actual, no key needed
curl https://www.orbitroute.ai/api/v1/jobs-stats/sla

Your own key (higher limits, your usage history): free signup — 100 routing decisions/day, no card.

60-second start — satellite operator

The federation API turns your capacity into routable supply: register once, advertise nodes, jobs route against your advertised physics and price. Listing is free — no fee to register or to appear in the directory. Full walkthrough, limits, and troubleshooting: the operator onboarding page.

Operator directory: listed — the first-mover slot is open. Listing is free. The first operators onboarded get integration support directly from the founder, and their capability data accumulates the longest scoring history in the learning loop before execution goes live.

# Register once — your or_op_ key is shown exactly once
curl -X POST https://www.orbitroute.ai/api/v1/federation/operators \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Orbital", "contact_email": "ops@acme.example", "jurisdiction": "US"}'

# Advertise a node → it is directory-listed immediately (see below for routable)
curl -X POST https://www.orbitroute.ai/api/v1/federation/nodes \
  -H "Content-Type: application/json" \
  -H "X-Operator-Key: $ORBITROUTE_OPERATOR_KEY" \
  -d '{"node_id": "acme-tile-1", "norad_id": 25544, "gpu_type": "H100",
       "gpu_count": 8, "power_budget_w": 12000, "price_usd_per_gpu_hr": 1.99}'

"directory-listed, not routable" is a normal first answer, not an error. Every advertisement is stored and listed with its live position; a node joins the routing fleet only when both hold — (1) OrbitRoute can propagate its orbit (a resolvable norad_id, or TLE lines under 14 days old), and (2) OrbitRoute has attested that you operate that spacecraft. Attestation is a manual check by a human, because registration is anonymous and self-serve, so a registration on its own proves nothing about who controls a satellite — and that same gate is what stops anyone else advertising nodes against your spacecraft under your company name. The 201 names which condition you are missing; /federation explains both and how to clear them (hello@orbitroute.ai for attestation).

Capability fields (power budget, eclipse battery fraction, ISL neighbors, jurisdiction, attestation) are in the full reference under CapabilityAdvertisement. Ground-segment partners: hello@orbitroute.ai.

Authentication

HeaderWhoWhere to get it
X-API-KeyCompute buyers — routing, cost compare, managed jobsFree signup (100/day) → paid tiers on pricing
X-Operator-KeySatellite operators — federation node managementPOST /api/v1/federation/operators, shown once

Core endpoints

EndpointWhat it does
POST /api/v1/routeRouting decision: orbital vs terrestrial, with scores, cost, latency, and full reasoning disclosure
POST /api/v1/cost-compareSide-by-side job cost across AWS / GCP / Azure / orbital
POST /api/v1/jobsSubmit a managed job — queued, pass-window scheduled, executed, SLA-graded
GET /api/v1/jobs/{id}Job status + predicted-vs-actual grades
GET /api/v1/jobs-stats/slaThe public SLA scoreboard aggregate (human version)
POST /api/v1/federation/nodesAdvertise orbital capacity — directory-listed at once, routed once propagatable and attested (how)
GET /api/v1/federation/nodesPublic federation directory — live position, illumination, and each node's verification state
GET /api/v1/viz/snapshotThe live constellation + station + uplink state behind the globe
GET /api/v1/ground-stationsAll 37 modeled sites with masks, modeled bandwidth and weather-gated link recommendation (the table)
GET /api/v1/ground-stations/coverageContact duty cycle and worst gap per reference orbit, simulated against those exact stations

Each of these, with a real request and a real response body: the customer API reference.

SDKs

Python (sync + async, single httpx dependency) and TypeScript (zero-dependency, fetch-based) clients are published:

pip install orbitroute        # Python
npm install orbitroute        # TypeScript / JavaScript

Both wrap routing, cost-compare, managed jobs, SLA, and federation, and raise a typed error with .status_code/.detail. Prefer plain HTTP? The API surface above is small, and openapi.json (with a declared server URL) feeds any generator.

Data provenance — read before building. Routing decisions disclose what's real: expander satellites carry capacity_class: modeled/federated, ground stations carry source: modeled until contracted, and job execution currently runs through a simulated orbital adapter. Don't build anything that assumes bytes reach orbital hardware yet — build against the decision engine, the scheduling, and the grading, which are real.