Plan — · Period — · counters reset at the start of the next UTC calendar month
Usage against quota
One count per successful call, per preview quota bucket. A bucket whose allowance is not yet fixed shows its count alone.
intention—
spatial—
complete—
audio—
Hosting
Where your organisation’s requests run. The shared tier is included with preview access; a dedicated tier keeps private capacity warm for you and is provisioned by a Falcon administrator: Dedicated Warm within one business day of approval, a GPU tier when GPU capacity is available. Dedicated hosting lists the tiers, what each includes and the limits.
SharedSigned out
Sign in to see the hosting tier of your organisation.
Web hosting
A static site for your organisation at https://<site>.falconlab.app, with TLS and a global CDN, for 9 CAD a month. Upload a zip of the site here; a Falcon administrator publishes it within one business day. The add-on is independent of the hosting tier above. Web Hosting has the price, the zip requirements and the limits.
Web hostingSigned out
Sign in to see the web hosting of your organisation.
API keys
A key is shown once, when it is created; the portal keeps only its prefix. Revoking a key takes effect on the next request.
Label
Prefix
Created
Last used
Status
Actions
Loading keys…
curl recipes
One command per public route against https://falcon-api-854266395503.us-central1.run.app. Select a key to fill in its prefix; paste the full key you saved in place of it.
bash
export FALCON_API_KEY="fln_…" # the full key you saved when it was created
Intention POST /v1/intention
ELIM, LIM or LIM Nano reads the turn and returns action, trajectory, harm and steer labels; model selects one of elim (the default), lim or lim-nano, and the result names which scored. · bucket intention
bash
curl -sS https://falcon-api-854266395503.us-central1.run.app/v1/intention \
-H "Authorization: Bearer $FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "what'\''s the difference between etf and mutual fund", "model": "lim"}'
Intention 3D POST /v1/intention3d
LIM3D-XL reads a scene sketch and an observed track and returns intent, phase, hazard and advice labels with an endpoint estimate; set model: "lim3d" for the low-latency LIM3D, whose response carries a warning. · bucket intention
bash
curl -sS https://falcon-api-854266395503.us-central1.run.app/v1/intention3d \
-H "Authorization: Bearer $FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sketch": "kind: scene\nviewer: standing at curb looking along roadway\nobjects: maple tree (center foreground, colour green foliage); two-lane road (center-right background, colour dark asphalt, size wider-than-frame); curb (center-right midground); ramp (center foreground, colour grey concrete, ground on-ground)\nrelations: maple tree next to ramp; ramp in front of two-lane road", "steps": [{"t": 0.0, "x": 0.0, "y": 0.0, "z": 0.0, "heading": "ahead"}, {"t": 1.0, "x": 0.1, "y": 1.2, "z": 0.0, "heading": "ahead"}, {"t": 2.0, "x": 0.2, "y": 2.5, "z": 0.0, "heading": "ahead"}], "mover": "you", "model": "lim3d-xl"}'
Spatial, from a sketch POST /v1/spatial
Waymark answers a spatial question about a scene sketch in the viewer frame. · bucket spatial
bash
curl -sS https://falcon-api-854266395503.us-central1.run.app/v1/spatial \
-H "Authorization: Bearer $FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sketch": "kind: scene\nviewer: eye-level on sidewalk\nobjects: doorway (right foreground); retaining wall (center background)\nrelations: doorway in front of retaining wall; doorway right of center; retaining wall behind doorway\nrelative: doorway closer than retaining wall", "question": "what'\''s in front"}'
Move POST /v1/move
Waymark Extra walks a person through a sketched scene toward a goal and returns a timed trace, parsed steps and a plain summary; the GPU service scales to zero, so the first call can take a minute or two. · bucket spatial
bash
curl -sS https://falcon-api-854266395503.us-central1.run.app/v1/move \
-H "Authorization: Bearer $FALCON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sketch": "kind: scene\nviewer: eye-level on sidewalk\nobjects: planter box (center foreground); doorway (right midground); hedge (left midground)\nrelations: planter box in front of doorway; hedge left of doorway", "goal": "walk to the doorway"}'
Airspace read POST /v1/airspace/read
Waymark Flight reads an airspace scene (up to 24 volumes) and a flight track and returns its reading beside the exact geometric check, the more cautious advisory and any disagreements. Decision support only, not for navigation; the CPU service scales to zero, so the first call can wait a few seconds. · bucket spatial
Waymark Flight proposes a route of up to 8 waypoints from start to goal around restricted, prohibited and TFR volumes (and controlled airspace unless allow_controlled); the exact checker validates it and the exact planner decides when it fails. Decision support only, not for navigation. · bucket spatial
The hosting tiers with their monthly CAD prices, the services a dedicated tier can host, and the organisation’s current tier and status. · portal route, session token, not metered
Request dedicated hosting POST /v1/portal/hosting/request
Asks an administrator for a dedicated tier; models names the GPU models to host on a GPU tier. Answers 409 hosting_active while a dedicated tier is already active; DELETE on the same path cancels a pending request. · portal route, session token, not metered
The Web Hosting add-on with its monthly CAD price and the organisation’s site: status, its https://<site>.falconlab.app address once published, the last upload and the date it was published. · portal route, session token, not metered
Replaces the organisation’s static site with the zip in the body: at most 25 MB, with index.html at the top level or in one top-level folder; an administrator publishes it within one business day. Answers 409 web_not_requested before a site is requested, 413 upload_too_large, 400 bad_zip or 400 no_index. · portal route, session token, not metered
Every model call carries a preview key as a bearer token: Authorization: Bearer fln_…. A key is shown once, when it is created; the portal keeps only its prefix.
Keep keys on your own server. Browser code on any origin other than the Falcon site cannot call the API directly, and a key in a client build cannot be revoked without a release.
An organisation holds at most eight keys. Revoke a key from the dashboard the moment it is exposed; revocation takes effect on the next request.
A missing, malformed or revoked token answers 401 invalid_credentials; the request is not processed and does not count.
The envelope
Every JSON response carries a boolean ok. On success the remaining fields are route-specific and name the model that answered in engine or result.model.
On failure error is a stable snake_case code, sometimes with a detail field (kind, hint, maxBytes). Match on the code, never on the HTTP status alone.
result: null with ok: true means the model declined to score the input (for example an empty window). Treat it as no opinion, not as an error.
Quota buckets
Calls are metered in four preview quota buckets — intention (/v1/intention, /v1/intention3d), spatial (/v1/spatial, /v1/move, /v1/airspace/read, /v1/airspace/plan), complete (/v1/chat) and audio (/v1/sound, /v1/speak) — per UTC calendar month. /v1/voices is not metered.
A call counts once, and only when it reaches the model: validation errors, 401, 402 and 503 do not count. Sandbox calls count like any other.
When a bucket is exhausted the route answers 429 quota_exceeded with kind naming the bucket. Counters reset when the month changes; retrying earlier cannot succeed.
Rate and retries
The model services load their weights on first use and answer 503 while loading. Retry once after 2.5 s, then treat the call as failed. /v1/spatial and /v1/move share a GPU service that scales to zero: the first call to either after a quiet period can take one to two minutes. The Waymark Flight service behind /v1/airspace/read and /v1/airspace/plan also scales to zero; its first call waits a few seconds and may answer 503 flight_warming with Retry-After.
Do not retry 400, 401, 402, 422 or 429. A retried call that reaches the model counts again.
Send requests from one place and pace them; a burst that exhausts a bucket in the first days of the month leaves the organisation without the route until the counters reset.
Body limits
/v1/intention: 64,000 bytes. /v1/intention3d: 256,000 bytes and at most 64 steps. /v1/move: 64,000 bytes, sketch at most 6,000 characters and goal at most 300. /v1/airspace/read and /v1/airspace/plan: 64,000 bytes, at most 24 volumes and 12 track points. /v1/spatial: 24,000,000 bytes, with a decoded image of at most 6,000,000 bytes or a decoded video of at most 15,000,000 bytes.
/v1/sound: text of at most 400 characters after whitespace is collapsed. /v1/speak: at most 600. A body over its limit answers 400 bad_json.
Send Content-Type: application/json; the body is read as JSON only.
500 internal; 502 spatial_failed, move_failed, flight_failed, sound_failed, speech_failed; 503 lim3d_unavailable, waymark_unavailable, move_unavailable, flight_unavailable, flight_warming, sound_unavailable, speak_warming, speech_unavailable. The full table is on API conventions.
Content policy
Do not use the voice routes to impersonate a real person or organisation, or to present generated speech as a recording of one. The voices are a fixed catalogue; the models cannot clone a voice.
Model outputs are advisory. Intention labels are not medical, legal or crisis advice, and the spatial readings, movement traces, airspace readings and 3D readings are estimates, never measurements and not a safety system; combine them with your own checks.
Do not send content you have no right to process. Requests must not carry personal data of people who have not agreed to it.
Audio licensing
Audio returned by /v1/sound and /v1/speak may be used in your application. Express Voice's default voice lj is trained on LJSpeech, a public-domain corpus; its six other voices are trained on the Hi-Fi Multi-Speaker English TTS corpus, CC BY 4.0.
The six Hi-Fi voices of Express Voice are trained on a CC BY 4.0 corpus; the attribution is carried on the Express Voice page and the Express series notes, not in the GET /v1/voices payload, and it stays with audio in those voices wherever it is used or redistributed.
The base models and vocoders are MIT-licensed and the speaker encoder Apache-2.0; their notices are listed on the Express series page.
Data retention
Requests are not stored beyond usage counters. The service keeps, per organisation and per bucket, the number of calls in the current UTC month, and, per key, the time of its last use.
Request bodies, media and rendered audio are processed in memory for the duration of the call and are not written to storage or used for training. Fixed weights per version; the model does not learn from requests.
Dedicated hosting
An organisation that needs private, always-warm capacity can request a dedicated tier from the Hosting panel of the dashboard; an administrator provisions Dedicated Warm within one business day of approval, and a GPU tier when GPU capacity is available. Once active, Express Cue and the GPU models the tier hosts answer from the organisation’s own services with the same keys and routes; the in-process models (ELIM, LIM, LIM Nano, LIM3D, LIM3D-XL) run privately only for requests sent to the private API address listed under Endpoints on the dashboard. Dedicated hosting lists the tiers and prices.
The same guidelines, with the sign-in and key steps, are on the Portal page of the documentation.
