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.
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.
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.
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:
{
"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.
// 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.
- Call
GET /v2/timeand store itstimefor use in the next call. Never build the boundary from the client's clock. - 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 returns204 No Content. - After
204, repeat with the same cursor. Repeat this loop until a throw is received. - After a throw, advance the cursor to that throw's time:
after_time=<THROW_TIME>, where<THROW_TIME>is thethrowTimefield 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 fromGET /v2/timewhen 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 samethrowTime; usingafter_timethroughout keeps one cursor type. A throw whosethrowTimeis ahead of server time (device clock skew) is rejected as a future cursor with400: re-arm fromGET /v2/timeand letseenskip that throw when it comes back. - Retry
429(afterRetry-Afterseconds),5xxand network failures with the same cursor and a bounded backoff. A400or404from the wait means the cursor is outside the horizon or unknown: re-arm fromGET /v2/time. A401needs a new token.
// 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.