External API¶
The ARD External API lets you drive the platform programmatically — submit simulations, retrieve results, and read or switch the current vehicle — so you can integrate ARD into your own analysis tools and automate parameter studies.
It's a standard REST API that speaks JSON, and it's fully documented with an interactive, always-up-to-date OpenAPI schema (see Live API Reference below).
To use these capabilities from an AI app such as Claude instead of your own code, see Connect AI Apps (MCP).
Availability
API access is available on Team+ and Enterprise plans. Each API key is scoped to a single user and team.
Authentication¶
Every request is authenticated with an API key passed as a Bearer token in the Authorization header:
Generate and manage your key from the API Access tab in User Settings. Your key is shown only once, so copy and store it securely.
You can confirm a key works with the test-auth endpoint:
curl -X POST "https://api.appliedracingdynamics.com/external-api/test-auth" \
-H "Authorization: Bearer YOUR_API_KEY"
A 200 response means your key is valid.
What you can do¶
The API mirrors core platform actions, including:
- Browse your library: list vehicles, components, tracks and ambient conditions, with search
- Read and edit setups: look up a vehicle by ID or name, check it for warnings, and edit a vehicle, track or ambient conditions. Each edit creates a new version, exactly as it does in the app
- Compare and derive: list every field that differs between two vehicles (
GET /vehicles/{id}/diff), and read what the solver derives from a setup without a run: masses, rates, static state and the performance envelope (GET /vehicles/{id}/properties) - Read or set the current vehicle selected in your account
- Submit simulations, poll their status, and cancel one that is still running.
GET /melists what each type costs, andGET /simulation-configsyour team's saved presets - Run combination sweeps by naming the parameters to vary and their ranges.
GET /vehicles/{id}/sweepable-parameterslists what a vehicle can sweep, anddry_run: trueprices a sweep without launching it - Browse past simulations and their results
- Read results: a summary of a result's lap time and metrics, chosen channels over a range of samples (with your team's math channels evaluated on request), a sweep's table of combinations, or a download link for a result's full channel file in Parquet format
- Search the user guide
All requests are scoped to the team your API key belongs to, with the same access rules as the app. A key only reaches that team, even if you are a member of others, and it stops working if you leave the team.
Using the API never changes what you see in the app. Your current team, and the vehicle, track and ambient conditions you have selected, stay as you left them. The one exception is Set the current vehicle, which updates your selection only while the app is open on the key's team.
Limits¶
| Limit | Value |
|---|---|
| Requests per key | 10 per second, and 300 per minute |
| Simulations running at once, per user and team | 5 |
A request over either limit is refused with 429 Too Many Requests. The response includes a Retry-After header giving the number of seconds to wait, and a JSON body whose gate field says which limit applied (rate_limit or in_flight). A simulation counts as running until its status is final, so a sweep counts as one. Runs you start in the app count too, and POST /simulations/{id}/cancel frees a slot.
Live API Reference¶
The complete, interactive reference is generated directly from the running API, so it always reflects the current endpoints, request/response schemas, and example payloads.
- Interactive docs: https://api.appliedracingdynamics.com/external-api/docs
- OpenAPI schema (JSON): https://api.appliedracingdynamics.com/external-api/openapi.json
Generate a client
The OpenAPI JSON can be fed into tools like openapi-generator or Postman to scaffold a typed client in your language of choice.
Example¶
A minimal Python example that authenticates and fetches your currently selected vehicle:
import requests
API_KEY = "your-api-key-here"
BASE_URL = "https://api.appliedracingdynamics.com/external-api"
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.get(f"{BASE_URL}/current-vehicle", headers=headers)
response.raise_for_status()
print(response.json())
Polling a simulation¶
GET /simulation-status/{simulation_id} returns the simulation's status. Treat these as still running and keep polling:
status |
Meaning |
|---|---|
preparing |
A sweep's vehicles are still being built |
in_progress |
Simulation tasks are running |
ingesting |
Every task has finished and the results are being prepared for reading (some sweeps only) |
Anything else — success, partial_success, failed — is final. While a simulation is still running, POST /results/{simulation_id} answers with a plain 202 Accepted and no JSON body, so check the status code before parsing it.
Poll on a set of finished statuses rather than a list of running ones, so a running status added in future can't end your loop early:
import time
DONE = {"success", "partial_success", "failed"}
while True:
status = requests.get(
f"{BASE_URL}/simulation-status/{simulation_id}", headers=headers
).json()["status"]
if status in DONE:
break
time.sleep(5)
response = requests.post(f"{BASE_URL}/results/{simulation_id}", headers=headers)
if response.status_code == 202:
... # not ready yet: poll again
response.raise_for_status()
results = response.json()
Sweep results¶
A sweep has one result per combination, so POST /results/{simulation_id} can't tell which one you want and answers 409. List the combinations, then ask for each by its result_id:
rows = requests.get(
f"{BASE_URL}/simulations/{simulation_id}/sweep-table", headers=headers
).json()["rows"]
for row in rows:
response = requests.post(
f"{BASE_URL}/results/{simulation_id}",
json={"result_id": row["result_id"]},
headers=headers,
)
response.raise_for_status()
result = response.json()
The sweep table already holds each combination's swept values, lap time and metrics, so you only need the loop when you want channel data.
Keep keys out of source
Store API keys in environment variables or a secret manager — never commit them to version control or share them publicly. If a key is exposed, regenerate it from User Settings to invalidate the old one immediately.
Changelog¶
Sweep results by result_id¶
POST /results/{simulation_id}takesresult_idin the body to pick one combination of a sweep. A simulation with more than one result and noresult_idnow answers409instead of an error.- A
409that isn't a name clash no longer saysgate: name_taken. That covers this one and cancelling a finished simulation. Both now come with adetailand nogate.
Costs, cancelling, properties and presets¶
POST /simulations/{id}/cancelstops a simulation or sweep that is still preparing, running or ingesting. A finished one answers409. Credits for tasks that had already started are not refunded.POST /sweepswithdry_run: truevalidates and prices a sweep without launching it: combinations, credits against your balance (can_afford), and the expanded config. Paths, plan limits, the name and storage are checked as a submission checks them; the in-flight limit is only applied when you submit.GET /menow includessimulation_costs, the credits one run of each type costs.GET /vehicles/{id}/propertiesreturns the solver's derived properties of a setup without a run;reportisproperties,static_stateorenvelope.GET /vehicles/{id}/diff?against={id}lists every field that differs between two vehicles, unit-normalised and grouped by component.GET /simulation-configslists your team's saved presets, in the shapePOST /simulateandPOST /sweepstake.GET /math-channelslists your team's math channels, andPOST /results/{id}/channelsandPOST /folders/{id}/channelstakemath_channels(andx_axis) to evaluate them: a series joinsdata, a reducer joins the newmetricsfield.- The in-flight limit counts runs you start in the app as well as through the API; its message now says so.
Library, results and sweeps¶
New endpoints. None of them change what you have selected in the app. See the Live API Reference for their schemas.
- Library:
GET /components,PATCH /vehicles/{id},GET /vehicles/{id}/warnings,GETandPATCH /tracks/{id}, andGETandPATCH /ambient-conditions/{id}. - Results:
GET /simulations,GET /results/{id}/summary,POST /results/{id}/channels,GET /results/{id}/channels-fileandGET /simulations/{id}/sweep-table. - Sweeps:
GET /vehicles/{id}/sweepable-parametersandPOST /sweeps. - Docs:
GET /docs/search. - Refusals say why. A
402,403,409,423or429response now carries agatefield naming what refused the request:credits,billing,plan,restricted,name_taken,locked,rate_limitorin_flight. A refusal that used to arrive with an empty body now carries adetailtoo.
API keys stay in their own team¶
- Your app session is no longer changed by the API. Each request used to switch your current team in the app to the key's team. Running a simulation through the API also replaced the vehicle, track and ambient conditions selected in the app. Neither happens now.
GET /current-vehicleanswers404when your selected vehicle belongs to a different team from the key.PUT /vehiclestill returns the resolved vehicle. It now only updates your selection while the app is open on the key's team.- A key reaches only its own team. Results and simulations from your other teams answer
404. A key stops working once you leave its team. - New limits. See Limits. Requests over them answer
429with aRetry-Afterheader.
Result channel storage update¶
- New status
ingesting.SimulationStatus.statuscan now beingesting, afterin_progressand before the final status. It means the simulation is still running: keep polling. A loop that waitswhile status in ("in_progress", "preparing")stops too early and then gets a202from the results endpoint — see Polling a simulation. - Removed
cloud_file_retrievedandcloud_file_exists. These fields used to be in every results response from this API. The external endpoint always returned both astrue, whatever the result's actual storage state, so they carried no information. (The internal defaults werefalse, but the external API never exposed them.) They have been removed. If a generated client marks them as required, regenerate it from the OpenAPI schema, and remove any code that reads them.