Skip to content

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:

Authorization: Bearer YOUR_API_KEY

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 /me lists what each type costs, and GET /simulation-configs your team's saved presets
  • Run combination sweeps by naming the parameters to vary and their ranges. GET /vehicles/{id}/sweepable-parameters lists what a vehicle can sweep, and dry_run: true prices 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.

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} takes result_id in the body to pick one combination of a sweep. A simulation with more than one result and no result_id now answers 409 instead of an error.
  • A 409 that isn't a name clash no longer says gate: name_taken. That covers this one and cancelling a finished simulation. Both now come with a detail and no gate.

Costs, cancelling, properties and presets

  • POST /simulations/{id}/cancel stops a simulation or sweep that is still preparing, running or ingesting. A finished one answers 409. Credits for tasks that had already started are not refunded.
  • POST /sweeps with dry_run: true validates 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 /me now includes simulation_costs, the credits one run of each type costs.
  • GET /vehicles/{id}/properties returns the solver's derived properties of a setup without a run; report is properties, static_state or envelope.
  • GET /vehicles/{id}/diff?against={id} lists every field that differs between two vehicles, unit-normalised and grouped by component.
  • GET /simulation-configs lists your team's saved presets, in the shape POST /simulate and POST /sweeps take.
  • GET /math-channels lists your team's math channels, and POST /results/{id}/channels and POST /folders/{id}/channels take math_channels (and x_axis) to evaluate them: a series joins data, a reducer joins the new metrics field.
  • 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, GET and PATCH /tracks/{id}, and GET and PATCH /ambient-conditions/{id}.
  • Results: GET /simulations, GET /results/{id}/summary, POST /results/{id}/channels, GET /results/{id}/channels-file and GET /simulations/{id}/sweep-table.
  • Sweeps: GET /vehicles/{id}/sweepable-parameters and POST /sweeps.
  • Docs: GET /docs/search.
  • Refusals say why. A 402, 403, 409, 423 or 429 response now carries a gate field naming what refused the request: credits, billing, plan, restricted, name_taken, locked, rate_limit or in_flight. A refusal that used to arrive with an empty body now carries a detail too.

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-vehicle answers 404 when your selected vehicle belongs to a different team from the key.
  • PUT /vehicle still 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 429 with a Retry-After header.

Result channel storage update

  • New status ingesting. SimulationStatus.status can now be ingesting, after in_progress and before the final status. It means the simulation is still running: keep polling. A loop that waits while status in ("in_progress", "preparing") stops too early and then gets a 202 from the results endpoint — see Polling a simulation.
  • Removed cloud_file_retrieved and cloud_file_exists. These fields used to be in every results response from this API. The external endpoint always returned both as true, whatever the result's actual storage state, so they carried no information. (The internal defaults were false, 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.