Calling the API
Base URL and authentication
https://api.precisioncutarchery.com
Every call to a Connect-scoped route carries the access token as a bearer credential:
Authorization: Bearer pcc_at_...
OpenAPI document
The full request and response shapes for every route your app can reach
(compute:build, compute:analyze, compute:air, and the subscription
check) are published as an OpenAPI 3.1 document,
scoped to exactly what a third-party app can see:
https://api.precisioncutarchery.com/api/v1/openapi-connect.json
It has every field, type, bound and example, and it is the authoritative
source: point your codegen, API client or OpenAPI viewer at it rather than
guessing from these docs. Any origin may read it. Each operation's tag is
its rate-limit area (build, analyze, air or subscription-status).
Every code the API returns is in the Problem schema. To call a route,
get an access token for one of your test accounts through the
authorization flow.
Subscription check
A user's subscription can lapse. Ask before you compute, so your app can show a renew screen instead of a failed call:
const res = await fetch('https://api.precisioncutarchery.com/api/v1/connect/subscription', {
headers: { Authorization: `Bearer ${accessToken}` },
});
const { active } = await res.json(); // { "active": true }
active is false when the user's subscription doesn't entitle them to
compute now. Send that user to renew at
https://www.precisioncutarchery.com/app/account/subscription/. Any access
token can call this route, whatever scopes it holds, and it never answers
402. The answer is never cached (Cache-Control: no-store). A subscription
can lapse after the check, so keep handling 402 too.
Ranges and wind speeds
ranges, and windSpeeds for analyze/wind-drift, are each a list of
values or a sweep from a start to an end an increment apart, and type
says which. A list is strictly increasing. Send only the fields of the
type you chose. A list or sweep is at most 1000 rows, and ranges times
wind speeds is at most 30000; a larger request is refused with a 400
before any computation.
Generated clients
Three things to know if you generate a client from the OpenAPI document:
- Optional request fields can be left out or sent as
null, with the same meaning. - Accept unknown enum values and unknown fields in responses. A
response code that can grow, such as
code,ballisticsErrororlimitType, is a plain string in the schema, with its known values inx-extensible-enum. A strict Pydantic or zod model would reject unknown fields, so check that yours ignores them. - Send
typeto pick aoneOfvariant.AirDensityRequest,LaunchSpeedReference,rangesandwindSpeedseach discriminate ontype, and request bodies reject fields their variant doesn't allow.
Stability
We aim to keep the API backward compatible and to give at least 60 days' notice by email, to your app's contact address, before a change that breaks existing integrations. That is our current intent, not a commitment (Developer Agreement). Every change is in the changelog.
CORS
If your app is a browser app, or a hybrid app in a web view, we serve non-credentialed CORS for the web origin(s) you registered:
Authorizationis an allowed request header, so a browser app with no backend can send the bearer token from its own JavaScript. With a backend, the calls come from your server and need no CORS (Tokens).WWW-Authenticate,Retry-After,X-Request-ID,RateLimitandRateLimit-Policyare exposed response headers (Errors).
/oauth/token and /oauth/revoke are cross-origin endpoints under the same
rule. The two /.well-known/ metadata documents and the OpenAPI document
answer any origin.
On any other route, an origin you haven't registered gets a 403 and no
CORS headers, and the browser blocks the request before your code sees it.
Reproduce the failure outside the browser (curl, without an Origin
header) to see what we returned.