# Getting started

The TechDisc API gives your extension access to a user's newest measured throws, disc presets and simulated flights. All endpoints use `https://api.techdisc.com`.

The most common pattern is:

- Confirm authentication and give the user visual feedback that the API connection is alive
- Load the user's discs
- Wait for a new throw
- Receive a new throw
- Apply a disc to simulate and stream a simulated flight
- Wait for the next throw

Endless games and training extensions can be built around this basic loop.

## Authentication {#authentication}

Obtain a Play token from the TechDisc web or mobile application. Send it in the `Authorization` header on every request. In the [API reference](index.html), select **Authorize** and enter the token without the `Bearer` prefix.

```bash
curl 'https://api.techdisc.com/v2/time' \
  --header 'Authorization: Bearer <TOKEN>'
```

A successful response has `status: "ok"` and `time` in epoch milliseconds. A `401` response means the token is missing, invalid or expired. Obtain a new token from TechDisc after expiry; these endpoints do not refresh it.

`GET /v2/time` is also the connection heartbeat. Call it when the user connects, before showing a connected state, and whenever you need to confirm the link is still alive. Its `time` is the cursor that arms [waiting for the next throw](#wait-for-a-throw); never substitute the client's clock.

The interactive reference keeps authorization in memory for the current page. It does not save your token between visits. Requests go directly to `https://api.techdisc.com`.

## Load the user's discs {#load-discs}

Call `GET /v2/discs` to load the user's disc presets and let them select a disc for your extension.

```bash
curl 'https://api.techdisc.com/v2/discs' \
  --header 'Authorization: Bearer <TOKEN>'
```

Use the selected preset's `flightNumbers` when simulating with that disc.

`flightNumbers` on a throw or a preset can be incomplete: `speed`, `glide`, `turn` and `weight` (grams) are each present only when the stored value is valid, and stored values are not range-checked. Simulation requires all four fields within the simulator's ranges, listed under [disc parameters](physics.html#physics-disc). A request with a missing or out-of-range field returns `400` naming the field, for example `weight must be a finite number`. Check the four fields before simulating, or handle that `400` by offering another disc.

## Get a throw {#read-a-throw}

Call `GET /v2/throws/latest` for the latest eligible throw. The latest-throw endpoint returns `204 No Content` if no eligible throw exists.

```bash
curl 'https://api.techdisc.com/v2/throws/latest' \
  --header 'Authorization: Bearer <TOKEN>'
```

Throws may include a complete `releaseState`: instantaneous `releaseHyzerAngle`, `releaseNoseAngle`, `gamma`, `wx` and `wy`. Top-level hyzer and nose are the corrected values for display. For the difference, see [measured and artificial releases](physics.html#physics-measured-state).

To reproduce the flight shown in the TechDisc app, use the throw's recorded `flightNumbers` and measured state with `maxVerticalDrop: 1`, the app's release height. A preset may have changed since that throw was recorded.

## Handle low-speed throws {#low-speed-throws}

> Throws below **10 MPH** are commonly seen when players toss the disc up and catch it to see if their API connection is active. They are not treated as complete throw measurements to reduce accidental throw measurements. However these Low Speed throws will be sent via the API so your extension can acknowledge the attempt. Show a message such as “Throw a little faster to measure your flight,” then keep listening.

| Throw speed             | What your extension receives                                             | What to do next                                                                  |
| ----------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Below 10 mph            | Speed and available metadata; no complete release measurements or flight | Acknowledge the attempt, advance the polling cursor, and wait for another throw  |
| Exactly 10 mph or above | Normal throw eligibility and measurement rules apply                     | Validate the available measurements and selected disc before requesting a flight |

Low-speed throws do not require valid spin to appear in throw responses. They omit `spinRpm`, `wobble`, `hyzerAngle`, `noseAngle`, `launchAngle`, `upsideDown`, and `releaseState`. IDs, timestamps, speed, and available metadata remain available. **Check the numeric speed**, rather than relying on a warning label: the rule applies whenever `speedMph` is finite and below 10.

Hidden throws are also included in latest and wait responses. The API forwards stored `hidden` and `warningStatus` strings when available, for example `hidden: "true"` or `warningStatus: "LOW_SPEED"`. These status fields do not change the speed threshold.

All three flight endpoints—`GET /v2/flights/{throw_id}`, `POST /v2/flights`, and `POST /v2/flights/stream`—reject low-speed throws with **HTTP 422** and the following JSON response:

```json
{
  "error": "A flight path cannot be generated for a low speed throw.",
  "code": "low_speed_throw"
}
```

For generated flights, a finite positive speed below 10 returns this error before other measurements are validated; malformed or nonpositive request speeds return `400`. A rejected stream request returns ordinary JSON, not an NDJSON flight stream. Do not retry the same low-speed flight request. The [polling example below](#wait-for-a-throw) shows how to acknowledge the attempt and move on without receiving it repeatedly.

## Simulate a measured throw {#simulate-a-throw}

After checking for [low-speed attempts](#low-speed-throws), send the measured `releaseState` unchanged whenever it is available. Supply speed, signed spin and launch separately. The full-response and streaming endpoints accept the same request body.

```javascript
// shot: a V2 throw; disc: the selected V2 disc preset
const body = {
  speedMph: shot.speedMph,
  spinRpm: shot.spinRpm,
  launchAngle: shot.launchAngle,
  ...(shot.releaseState
    ? { releaseState: shot.releaseState }
    : {
        hyzerAngle: shot.hyzerAngle,
        noseAngle: shot.noseAngle,
        wobble: shot.wobble ?? 0,
      }),
  ...(typeof shot.upsideDown === "boolean"
    ? { upsideDown: shot.upsideDown }
    : {}),
  flightNumbers: disc.flightNumbers,
  maxVerticalDrop: 1.5,
};

const response = await fetch("https://api.techdisc.com/v2/flights", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
if (!response.ok) throw new Error(`Simulation failed: ${response.status}`);
const flight = await response.json();
```

Without measured state, the fallback above is an approximation using display metrics. Artificial throws may intentionally omit `releaseState` and supply their own hyzer, nose and optional wobble. With measured state, those three top-level fields are ignored.

`maxVerticalDrop: 1.5` starts the disc 1.5 meters above the simulator's zero plane. The API default is 1 meter, which is also the release height of every stored flight in the TechDisc app: send `maxVerticalDrop: 1` to match the app's flight for a throw. Downhill terrain needs a larger value; see [release height and terrain](physics.html#physics-height).

The last sample in the flight path is the landing (impact with the 0 m height plane) unless t reaches 15 seconds. Float noise is possible so the final sample may not be exactly 0 m. Don't build dependence on a height value being exactly 0.

## Stream and render the flight {#stream-a-flight}

For fastest playback, send the same body to `POST /v2/flights/stream`. The response is newline-delimited JSON with `chunk`, `complete` and `error` events. Parse complete lines across network reads; a network chunk is not necessarily a complete event. A stream can emit an error after returning HTTP 200.

Use the returned `t` values as the playback clock. Neighboring flight chunks repeat the boundary sample. Pause when playback reaches the received buffer and resume when more samples arrive.

Positions are in meters. Quaternions already include spin. A completed stream can end airborne at the 15-second simulation limit. See [coordinates, quaternions and time](physics.html#physics-flight-data) and the [streaming endpoint reference](index.html#/Flights/streamFlight).

## Wait for the next throw {#wait-for-a-throw}

Arm the wait with server time, then long-poll `GET /v2/throws/latest/wait`. Alternatively you can use the latest throw (via `GET /v2/throws/latest`) to seed the cursor, however if that throw is older than 30 days it will fail with `400` on every attempt. Arming with the server time is the most widely reliable method and should be used unless your use-case specifically requires something different.

1. Call `GET /v2/time` and store its `time` for use in the next call. Never build the boundary from the client's clock.
2. Wait for the latest throw: `GET /v2/throws/latest/wait?after_time=<TIME>`. A newer eligible throw returns immediately. Otherwise the request waits up to about 60 seconds and returns `204 No Content`.
3. After `204`, repeat with the **same** cursor. Repeat this loop until a throw is received.
4. After a throw, advance the cursor to that throw's time: `after_time=<THROW_TIME>`, where `<THROW_TIME>` is the `throwTime` field of the returned throw, in epoch milliseconds. The boundary is exclusive and covers that whole millisecond, so the same throw is never returned again. A throw made while the previous one was being simulated or animated is therefore returned at once on the next call; to ignore such throws instead, re-arm from `GET /v2/time` when the extension is ready again or just add a number of milliseconds to the previous throw's throwTime to create the desired delay or blanking time. `after_id=<THROW_ID>` is an equivalent cursor that the server resolves to the same `throwTime`; using `after_time` throughout keeps one cursor type. A throw whose `throwTime` is ahead of server time (device clock skew) is rejected as a future cursor with `400`: re-arm from `GET /v2/time` and let `seen` skip that throw when it comes back.
5. Retry `429` (after `Retry-After` seconds), `5xx` and network failures with the same cursor and a bounded backoff. A `400` or `404` from the wait means the cursor is outside the horizon or unknown: re-arm from `GET /v2/time`. A `401` needs a new token.

```javascript
// token: Play token. seen: a Set of throw IDs handled in this session.
const api = (path) =>
  fetch(`https://api.techdisc.com${path}`, {
    headers: { Authorization: `Bearer ${token}` },
  });
const sleep = (seconds) =>
  new Promise((resolve) => setTimeout(resolve, seconds * 1000));
const arm = async () =>
  `after_time=${(await (await api("/v2/time")).json()).time}`;

let cursor = await arm();
while (true) {
  const response = await api(`/v2/throws/latest/wait?${cursor}`);
  if (response.status === 204) continue; // nothing new: wait again with the same cursor
  if (response.status === 400 || response.status === 404) {
    cursor = await arm(); // cursor expired or unknown: re-arm
    continue;
  }
  if (response.status === 429 || response.status >= 500) {
    await sleep(Number(response.headers.get("Retry-After")) || 5); // same cursor
    continue;
  }
  if (!response.ok) throw new Error(`Wait failed: ${response.status}`); // 401: new token
  const shot = await response.json();
  cursor = `after_time=${shot.throwTime}`; // exclusive: this throw is not returned again
  if (seen.has(shot.id)) continue;
  seen.add(shot.id);
  if (Number.isFinite(shot.speedMph) && shot.speedMph < 10) {
    // Show low-speed feedback in your UI. The cursor already advanced above.
    continue; // no flight request or normal throw score; wait for a new attempt
  }
  // Simulate shot with the selected disc, as in the previous section.
}
```

Use an HTTP timeout longer than the 60-second wait. The wait returns the newest eligible throw after the cursor, not every throw: two throws during one simulation collapse to the newer one, so deduplicate by ID and never compare IDs for order. See [wait for a throw](index.html#/Throws/waitForLatestThrow) for the cursor rules.

## Rate limits {#rate-limits}

| Limit                                     | Budget                            |
| ----------------------------------------- | --------------------------------- |
| Per account, across tokens and clients    | 60 requests/minute and 1,000/hour |
| Per client IP, across all eight endpoints | 1,200 requests/minute             |
| Active long polls                         | 3 per account                     |
| Active flight streams                     | 3 per account                     |

A `429` response includes `Retry-After` in seconds. Honor that delay before retrying. Missing or invalid tokens still consume the IP budget; browser CORS preflight requests do not. Individual events in a flight stream do not count as new requests.

## Changes

November 13th, 2026

- Documented low-speed throw handling

November 9th, 2026

- Initial Beta Release

Use the [OpenAPI specification](throw-disc-v2-openapi.yaml) for current request and response schemas.
