# 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](#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](/documentation/developers/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:

```js
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`, `ballisticsError` or
  `limitType`, is a plain string in the schema, with its known values in
  `x-extensible-enum`. A strict Pydantic or zod model would reject unknown
  fields, so check that yours ignores them.
- **Send `type` to pick a `oneOf` variant.** `AirDensityRequest`,
  `LaunchSpeedReference`, `ranges` and `windSpeeds` each discriminate on
  `type`, 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](/developer-agreement/#changes)). Every change is in
the [changelog](/documentation/developers/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:

- `Authorization` is 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](/documentation/developers/tokens/#browser-apps)).
- `WWW-Authenticate`, `Retry-After`, `X-Request-ID`, `RateLimit` and
  `RateLimit-Policy` are exposed response headers
  ([Errors](/documentation/developers/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.
