The web app does everything through GarageStack's own REST API, and anything else can use the same API: a script, Home Assistant, a dashboard. This page covers the reference that describes it, and what a developer keeps up to date when changing it.
Open /api/reference/ on the address you use for GarageStack, or follow API reference under Settings > Data & API > API tokens. It lists every endpoint with what it takes and what it answers, and asks you to sign in first if you have not.
A deployment serves the page once API_REFERENCE_ENABLED=true is set; demo mode and development serve it unless that says false. It is off by default because it runs a third-party library, Scalar, on GarageStack's own address with your session, and most installs never need it. Off, /api/reference/ answers 404 and the settings show no link. The OpenAPI document below is served either way.
Test Request on any endpoint sends the request with your own session: nothing to fill in, and it is the real thing. A command goes to the car, a delete deletes. In demo mode it goes to the demo car.
The page is Scalar, served by the API itself. It loads nothing from elsewhere: no fonts or scripts from a CDN, no telemetry, and Scalar's AI and hosted-client features are switched off.
The same description is an OpenAPI 3.1 document:
/api/openapi/v1.jsonon a running GarageStack, for a signed-in session or an API token. Code generators and other OpenAPI tools take it as it is.openapi.jsonin this folder, as of the commit you are looking at. It is the quickest way to learn the API without running anything, for people and coding agents alike.
The reference page comes with a Content-Security-Policy of its own, built around a new nonce on every request. The nginx in the GarageStack images leaves its own policy off that page for that reason. A proxy in front that adds or replaces a Content-Security-Policy on every response (a Traefik headers middleware, for one) has to leave /api/reference alone as well, or the page stays blank.
| Who | How | What it may do |
|---|---|---|
| The browser, and the reference page | The session cookie that signing in sets | Everything |
| A script | Authorization: Bearer gs_..., a read-only token from Settings |
GET only, and not the export, the logs or the tokens. See read-only API tokens |
| The Homepage widget | X-Widget-Key: <WIDGET_API_KEY> |
/api/widget only. See WIDGET.md |
The reference marks each endpoint with the ways in it accepts, so an endpoint a token cannot call says so.
- Times are UTC, in ISO 8601. Distances are km, speeds km/h, temperatures °C, tyre pressures bar, energy kWh and power kW, whatever units the app is set to show.
- A refusal is a problem details body with a
code, such astrip.changedortoken.readOnly. The code stays the same between releases;detailsays the same in English. The web app translates the code. - A request from a page on another address than
CORS_ORIGINthat would change something is refused with403andcsrf.originNotAllowed. A script sends noOriginheader and is not affected. - Each address may make 120 requests a minute (
RATE_LIMIT_GLOBAL_PER_MINUTE), and some endpoints allow fewer. Past that the answer is429. - A command (
POST /api/vehicles/{vin}/commands/{command}) answers once it is sent. The car's answer arrives later over the SignalR hub at/hubs/telemetry, or shows in the next telemetry.
The document is generated from the endpoints themselves (ASP.NET Core's OpenAPI support), so describing an endpoint is part of writing it:
- Its group has
.WithTags("..."), and a new tag gets a sentence inApiReferenceText.Tags(src/GarageStack.Api/Reference/ApiReferenceText.cs). A group that takes{vin}uses.ResolvesVehicle(), which resolves the vehicle and documents the404for an unknown VIN. - Every endpoint has a
.WithSummary("..."), and says what it answers:.Produces<T>()for a body,.Produces(StatusCodes.Status204NoContent)(or another status) without one, and.ProducesProblem(status)for each refusal it makes throughApiProblems. A handler returnsIResult, so the framework cannot see this for itself. - Records that go in or out carry XML doc comments: a
<summary>and<param>s become the descriptions in the reference. - A body read by hand (a
JsonElement) is described with an operation transformer on the endpoint, as the command endpoint does withVehicleCommandRequest.
What every endpoint shares is added in one place, OpenApiSetup: which ways in an endpoint accepts (from the token rules in ApiTokenAuthentication.Refusal, the same ones the API enforces), and the 401, 403 and 429 any request can meet.
Two tests in GarageStack.Tests hold this up:
EveryEndpoint_DeclaresWhatItAnswers_AndItsGroupIsDescribedfails for an endpoint without a summary, without a declared answer, or with a tag that has no description.ApiDocument_MatchesTheCommittedCopycompares the document withopenapi.json. When they differ, it writes the new document there and fails: look at the change, and commit it with the code that made it. The diff shows a reviewer what the API change looks like from the outside.
The page itself is ApiReferencePage: where it is served, the sign-in redirect, and its Content-Security-Policy. frontend/nginx-app.conf gives /api/reference its own location without the app's policy, and frontend/e2e/api-reference.spec.ts checks the page in the production image.