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

Obtain a Play token from the TechDisc web or mobile application. Send it in the Authorization header on every request. In the API reference, 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; 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

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. 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

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.

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

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 shows how to acknowledge the attempt and move on without receiving it repeatedly.

Simulate a measured throw

After checking for low-speed attempts, 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.

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

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 and the streaming endpoint reference.

Wait for the next 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 for the cursor rules.

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 for current request and response schemas.