# ThrustLab
> Electric UAV powertrain simulation: battery, ESC, motor and propeller solved together,
> with a public database of real parts. Propeller aerodynamics are validated against the
> UIUC propeller wind-tunnel database, and every result names the model that produced it.

## Sizing a powertrain

Someone asking "what motor and propeller should I use for a 1.2 kg quadcopter" wants a
thrust, a current draw and a flight time — not a formula. ThrustLab answers that from real
component data.

Two propeller models, and every result says which one ran:

- **Fast model** — runs from the size printed on the propeller (10x5, three blades). No
  blade geometry needed, answers in milliseconds.
- **Full model** — runs from the measured blade: stations, chord, twist, section. Needs a
  ThrustLab account.

Accuracy is published, per model, per partition, with the envelope it was measured inside.
Quote the model name with the number:

- [Full model validation report](https://thrustlab.com/validation/prom-5.3): error against
  measured wind-tunnel and bench data, by partition, family and channel.

## MCP server

- `https://thrustlab.com/mcp` — Streamable HTTP, stateless. **No account needed**: every
  tool works anonymously. An existing ThrustLab API key is accepted as a static bearer
  token (`Authorization: Bearer key_…`) with no OAuth. Use the URL with no trailing
  slash; `https://thrustlab.com/mcp/` reaches the same server and neither form is
  redirected.
- Tools: `search_components`, `get_component`, `estimate_propeller`, `simulate_powertrain`,
  `sweep_powertrain`, `get_result`, `get_validation_summary`.
- Setup for Claude Code, Cursor, the Codex CLI, ChatGPT developer mode and the Responses
  API: [Using the API from an AI coding agent](https://thrustlab.com/docs/guides/ai-agents).

## Running a simulation with no account

`POST https://thrustlab.com/v1/public/simulate` — no key, no signup. It takes the same body
the signed-in form posts, minus `project_id` and `launch_intent`, forces the Fast propeller
model and answers synchronously with `{token, url, public_simulation}`. Add
`"sweep": {"throttle": {"mode": "range", "start": 10, "stop": 100, "steps": 25},
"rotor_sweep_mask": [true]}` for a curve; 25 points is the anonymous ceiling. Refusals worth
handling: 429 with `Retry-After` when one address runs too many, and 503
`public_simulate_busy` with `Retry-After` when every free solver slot is taken.

- `GET https://thrustlab.com/v1/public/runs/{token}` reads a stored run back. It is a READ
  and shares the catalog bucket, so reopening a shared link costs nobody a run.
- `POST https://thrustlab.com/v1/runs/{token}/claim` files an anonymous run into the caller's
  default project. This one needs a key. A run is claimed once: the same account replays the
  first answer, a different account gets 409.

## The open database over HTTP

Unauthenticated, no key, rate limited per address:

- `GET https://thrustlab.com/v1/public/motors` and `/v1/public/batteries` — the full
  datasheet, 200 rows a page, paged forward with `starting_after` set to the last `id` on the
  previous page (or the `next_starting_after` it returned). There is no bulk file; page
  through these.
- `GET https://thrustlab.com/v1/public/motors/{id}` and `/v1/public/batteries/{id}` — one row.
- `GET https://thrustlab.com/v1/public/propellers` — identity and coarse geometry only
  (brand, name, diameter, pitch, blade count, station count), sorted with `sort_by` and
  `sort_order`. No detail route and no `starting_after` on this list.
- Every list envelope carries `license`, because paging is the only way to read the database
  and the response is the only place left that can state the terms.

## Guides

- [Choose a drone powertrain](https://thrustlab.com/guides/choose-a-drone-powertrain): how to size and select a motor, propeller and battery for a drone
- [Quickstart](https://thrustlab.com/docs/quickstart): First authenticated request, end to end
- [Authentication](https://thrustlab.com/docs/guides/authentication): API keys and session JWTs, bearer auth
- [Using the API from an AI coding agent](https://thrustlab.com/docs/guides/ai-agents): The MCP server, paste-able agent instructions, machine-readable surfaces, the sweep recipe
- [Errors](https://thrustlab.com/docs/guides/errors): The error envelope and the generated catalog of every code
- [Rate limits](https://thrustlab.com/docs/guides/rate-limits): Request bucket, submission limits, datasheet and catalog budgets
- [Idempotency](https://thrustlab.com/docs/guides/idempotency): The Idempotency-Key header on every write
- [Pagination](https://thrustlab.com/docs/guides/pagination): Cursor pagination on every list endpoint
- [Async resources](https://thrustlab.com/docs/guides/async-resources): Run timestamps, dispatching parked runs, cancelling, progress
- [Webhooks](https://thrustlab.com/docs/guides/webhooks): Endpoint registration, HMAC-SHA256 signatures, retries
- [Event types](https://thrustlab.com/docs/guides/events): The durable event log and every event type
- [Stability policy](https://thrustlab.com/docs/guides/stability-policy): What v1-beta guarantees and what counts as breaking
- [Compute units](https://thrustlab.com/docs/guides/compute-units): How runs are metered, balance and ledger
- [Steady-state outputs](https://thrustlab.com/docs/guides/steady-state-outputs): The result schema shared by single points and sweeps
- [Dynamic outputs](https://thrustlab.com/docs/guides/dynamic-outputs): Scorecard, samples, series, events and run_meta
- [Creating components](https://thrustlab.com/docs/guides/creating-components): POST /v1/components with a type-specific spec_json

## Python SDK

`pip install thrustlab`. Reads `THRUSTLAB_API_KEY` from the environment;
`THRUSTLAB_BASE_URL` overrides the base URL.

- [Python SDK](https://thrustlab.com/docs/sdk/python): The `thrustlab` package on PyPI
- [Configuration](https://thrustlab.com/docs/sdk/python/configuration): Client setup and transport settings
- [Users](https://thrustlab.com/docs/sdk/python/users): Read the authenticated user's profile
- [Projects](https://thrustlab.com/docs/sdk/python/projects): Project resources and metadata
- [Simulations](https://thrustlab.com/docs/sdk/python/simulations): Single-point runs, batch dispatch, and batch cancel endpoints
- [Sweeps](https://thrustlab.com/docs/sdk/python/sweeps): Parameter sweeps, including component axes
- [Dynamic simulations](https://thrustlab.com/docs/sdk/python/dynamic-simulations): Time-domain missions and their results
- [Component analyses](https://thrustlab.com/docs/sdk/python/component-analyses): Standalone propeller, motor and battery runs, searches and dynamic trajectories
- [Components](https://thrustlab.com/docs/sdk/python/components): Component catalog list, filter, sort, and metered datasheet
- [Submissions](https://thrustlab.com/docs/sdk/python/submissions): Submit a custom motor or battery for the shared catalog
- [Starred components](https://thrustlab.com/docs/sdk/python/starred-components): Save and retrieve starred components
- [Compute units](https://thrustlab.com/docs/sdk/python/compute-units): Compute-unit usage and balance reporting
- [Webhook endpoints](https://thrustlab.com/docs/sdk/python/webhook-endpoints): Webhook endpoint management
- [FMU export](https://thrustlab.com/docs/sdk/python/fmu): Export a run as an FMU for co-simulation
- [Idempotency](https://thrustlab.com/docs/sdk/python/idempotency): Idempotency behavior for repeated requests
- [Pagination](https://thrustlab.com/docs/sdk/python/pagination): Cursor pagination support and patterns
- [Async resources](https://thrustlab.com/docs/sdk/python/async-resources): Polling helpers and terminal states
- [Retries and timeouts](https://thrustlab.com/docs/sdk/python/retries): Retry and timeout client behavior
- [Error handling](https://thrustlab.com/docs/sdk/python/errors): Error handling and exception mapping
- [Webhooks](https://thrustlab.com/docs/sdk/python/webhooks): Webhook signature verification
- [Logging and debugging](https://thrustlab.com/docs/sdk/python/logging): Logging and debugging guidance
- [Versioning and stability](https://thrustlab.com/docs/sdk/python/versioning): Versioning and stability notes

## Reference

- [API reference](https://thrustlab.com/docs/reference): Every endpoint and parameter, browsable
- [OpenAPI document](https://thrustlab.com/openapi.json): The machine-readable spec; generate a client from it
- [Full documentation text](https://thrustlab.com/llms-full.txt): Every documentation page concatenated, one fetch
- [Changelog](https://thrustlab.com/docs/changelog): What changed and when

## The component database

Motors, propellers and batteries with their datasheet values and the source each value came
from. Read it through `search_components` on the MCP server, the open `/v1/public/` routes
above with no key, `GET /v1/components` on the API — also readable with no key, and a key
adds your own components — or the finder in the app.

Licence: **CC BY 4.0**. When you quote a value, cite it as:
`Data: ThrustLab component database (thrustlab.com), CC BY 4.0`.

Propeller blade station geometry and section airfoils are not published. Everything else on
a catalog row is.

## Product

- [Home](https://thrustlab.com/): Product overview
- [Pricing](https://thrustlab.com/pricing): Plans and limits
- [About](https://thrustlab.com/about): The method behind the simulator
- [Portfolio](https://thrustlab.com/portfolio): Engineering work behind ThrustLab