API conventions

Overview #

The Falcon API is one HTTPS service that fronts every series: LIM, Waymark, Express and Response. It speaks JSON only, authenticates every model call with a Bearer token, wraps every response in the same envelope, and meters calls in five preview quota buckets. This page is the contract shared by all routes; each model page documents its own request and response bodies in its API chapter.

Falcon is in private preview. Self-serve API keys and accounts are paused. See Access for what a preview key covers.

The API itself runs on 2 vCPU / 2 GiB and is kept warm with one minimum instance, so a request carries no wait for the API to start. The in-process models — ELIM, LIM, LIM Nano, LIM3D and LIM3D-XL — answer in well under a second; the proxied routes add the latency of the service behind them, stated on each model page.

Base URL and transport #

• The base URL is issued with your preview key. All paths below are relative to it.
• Every request and response body is JSON; send Content-Type: application/json.
• A trailing slash on a path is ignored (/v1/intention/ is /v1/intention).
• Responses carry Cache-Control: no-store and are never cacheable.
• Model routes are POST. GET is used only for the health, usage and voice-catalogue routes.

Authentication #

Send the key in the Authorization header:

POST /v1/intention HTTP/1.1
Authorization: Bearer fln_…
Content-Type: application/json

• Preview API keys begin with fln_. Session tokens, which begin with fls_, are accepted on the same routes but are short-lived and belong to the account layer rather than to integrations.
• A missing, malformed or revoked token returns 401 with error: "invalid_credentials".
• A token whose account is not in good standing returns 402 with error: "payment_required"; the request is not processed and does not count against quota.
• Keys are checked before the body is read, so an unauthenticated request never consumes quota.

The envelope #

Every JSON response has a boolean ok at the top level.

{ "ok": true, "engine": "waymark", "model": "waymark", "text": "doorway on your right foreground.", "from": "sketch" }

{ "ok": false, "error": "quota_exceeded", "kind": "spatial" }

• On success the remaining fields are route-specific. Model routes name the model that answered in engine (/v1/spatial, /v1/move, /v1/airspace/read, /v1/airspace/plan, /v1/intention3d, /v1/chat, /v1/sound, /v1/speak, /v1/transcribe) or in result.model (/v1/intention). The audio routes return the audio itself as wav_base64, a base64-encoded RIFF/WAVE file.
• On failure error is a stable snake_case code; some errors add a detail field (kind, hint, maxBytes). Never match on HTTP status alone — the code is the contract.
• result is null, with ok: true, when a model was configured but declined to score the input (for example an empty window). Treat null as “no opinion”, not as an error.

Routes #

Body limits apply to the raw request body. A body over the limit is refused; depending on the route that is 400 bad_json or, on the airspace routes, a closed connection with no JSON body.

/v1/intention #

Body: text (required, the current turn) and optional model: "elim" (the default when omitted), "lim" or "lim-nano"; any other value answers 400 unknown_model with models listing the three accepted names. The turn is wrapped as a one-line conversation window, and result.model echoes which model scored it.

{ "text": "what's the difference between etf and mutual fund", "model": "lim" }

{
  "ok": true,
  "result": {
    "action": "allow",
    "trajectory": "research",
    "harm": "none",
    "steer": "none",
    "pAction": 1,
    "pHarm": 1,
    "pTrajectory": 1,
    "model": "lim",
    "rule": "benign-traj≥0.28"
  }
}

pAction, pHarm and pTrajectory are the winning-class probabilities of the corresponding heads (0–1). rule names the threshold rule that decided the action. message, present on some steer and abort results, is a suggested short reply in a casual register, safe to replace. Labels are listed on Output vocabularies.

/v1/intention3d #

Body: sketch (required), steps (required, a non-empty array of observed steps), optional mover (default "you"), optional with_notes, and optional model, "lim3d-xl" (the default) or "lim3d"; any other value answers 400 bad_model. Steps with a non-finite t, x, y or z are dropped; the first 64 are kept. The response repeats the frame sentence, names the size that answered in model and adds a plain-words summary.

{
  "ok": true,
  "engine": "lim3d",
  "frame": "approx m; x right, y ahead, z up; viewer at origin",
  "model": "lim3d-xl",
  "result": {
    "intent": "pass_ahead",
    "pIntent": 1,
    "target": "none",
    "targetIndex": -3,
    "pTarget": 1,
    "phase": "walking",
    "hazard": "obstacle_ahead",
    "pHazard": 0.9994,
    "action": "caution",
    "pAction": 0.9519,
    "advice": "sidestep_left",
    "endpoint": { "dx": 0.246, "dy": 5.246, "dz": 0.205 },
    "eta": 4.648,
    "rule": "action-caution≥0.45",
    "model": "lim3d-xl",
    "summary": "You're just passing straight through, about 5m and 5s to go. Watch: sidestep left around the obstacle."
  }
}

LIM3D-XL answers unless the body carries model: "lim3d", in which case LIM3D answers on the same route and the response carries a warning string — at the top level and inside result — saying that LIM3D is the low-latency option, identifies the target less often than LIM3D-XL and degrades sharply when steps are missing. The sentence is fixed per version and is quoted on the LIM3D page; engine is always lim3d, the name of the route, and model is the size that answered.

/v1/spatial #

Body: either sketch (a scene sketch) or one media field — image, image_base64, video or video_base64, holding base64 or a data:…;base64, URL — plus optional question (alias text, default "what's the layout?"), mimeType (alias mime_type), filename and model — "waymark" (the default) or its alias "waymark-indoor", which selects the same weights; any other value answers 400 bad_model. With media, the service runs server-side vision sketching (third-party model) to produce the sketch first; the response then includes the sketch it built and from is "image" or "video". With a sketch, from is "sketch".

{
  "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"
}

{ "ok": true, "engine": "waymark", "model": "waymark", "text": "doorway on your right foreground.", "from": "sketch" }

Waymark is sampled with at most 72 new tokens at temperature 0.3 (sketch) or 0.35 (media). engine is "waymark" when Waymark answered and model echoes the requested value; when model is waymark-indoor and the organisation's Waymark service predates that alias, the route answers 503 model_unavailable and the call is not counted; if Waymark is unavailable after a media sketch, the sketching model answers from the sketch and engine carries its identifier. Since 2026-09-16 Waymark runs on the same GPU service as Waymark Extra: an answer takes 0.6–1.1 s once the service is warm, but the service scales to zero, so the first call after a quiet period pays a cold start of one to two minutes and the route answers 503 waymark_unavailable or 502 spatial_failed until it is ready.

/v1/move #

Body: sketch (required, a scene sketch, at most 6,000 characters), goal (required, the movement request in plain words, at most 300 characters), optional mover ("you" for the viewer, the default, or a person label from the sketch), optional max_new_tokens (default 400, clamped to 32–480) and temperature (default 0.2, clamped to 0–1). Waymark Extra generates a movement trace; the route parses it into steps and adds a plain-words summary.

{ "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", "mover": "you" }

{ "ok": true, "engine": "waymark-extra", "frame": "approx m; x right, y ahead, z up; viewer at origin", "mover": "you", "trace": "t=0.0s (0.0, 0.0, 0.0) ahead-right | doorway ~6m ahead | ahead: planter box ~2m\n…\narrive t=5.4s (3.0, 6.1, 0.0) doorway | planter box behind", "steps": [ { "t": 0.0, "x": 0.0, "y": 0.0, "z": 0.0, "heading": "ahead-right", "notes": ["doorway ~6m ahead", "ahead: planter box ~2m"], "arrive": false } ], "summary": "You reach the doorway in about 5s, ending ~3m right and ~6m ahead of where the photo was taken." }

trace and steps are abbreviated; the full shape is on the Waymark Extra page. The model runs on a GPU service that scales to zero: the first call after a quiet period pays a cold start of one to two minutes, during which the route answers 503 move_warming with a Retry-After of 60 seconds (503 move_unavailable means no movement service is configured at all). Once warm a twelve-step trace takes about 5–10 s depending on route length, and a CUDA warm-up at start-up means the first trace after a cold start is no slower. 413 text_too_long means the sketch or the goal is over its character limit.

/v1/airspace/read and /v1/airspace/plan #

Both routes take an airspace scene: volumes, at most 24 cylinders or rings in a local east/north frame in nautical miles with altitudes in feet MSL, and mover (drone, light, helicopter or jet). Waymark Flight is decision support and education only and is not certified for navigation; every response carries a notice saying so.

/v1/airspace/read also takes track, 1–12 points {t_s, x_nm, y_nm, alt_ft} in ascending t_s, and returns the model’s reading in model, the exact geometric check of the same input in exact, the more cautious of the two advisories in advisory (at least turn_away when the exact check puts the mover inside an active hazard) and the names of the fields on which they differ in disagreements.

{ "volumes": [ { "id": "R1", "kind": "restricted", "center": { "x_nm": 0, "y_nm": 0 }, "radius_nm": 2, "floor_ft": null, "ceiling_ft": 6000 } ], "track": [ { "t_s": 0, "x_nm": -6, "y_nm": 0, "alt_ft": 2500 }, { "t_s": 30, "x_nm": -5.1, "y_nm": 0, "alt_ft": 2500 } ], "mover": "light" }

{ "ok": true, "engine": "waymark-flight", "model": { "inside": [], "tier": "none", "under_shelf": false, "next_event": { "volume": "R1", "kind": "enter_lateral", "eta_s": 101 }, "hazard_entry": true, "margin_lat_nm": 3.1, "margin_vert_ft": 10000, "ceiling_ft": 18000, "advisory": "turn_away" }, "exact": { "inside": [], "tier": "none", "under_shelf": false, "next_event": { "volume": "R1", "kind": "enter_lateral", "eta_s": 104 }, "hazard_entry": true, "margin_lat_nm": 3.1, "margin_vert_ft": 10000, "ceiling_ft": 18000, "advisory": "turn_away" }, "advisory": "turn_away", "disagreements": [], "notice": "Decision support and education only. Not certified for navigation." }

/v1/airspace/plan takes start {x_nm, y_nm, alt_ft}, goal ({x_nm, y_nm, alt_ft?} or {land_at: volumeId}), optional allow_controlled (default false) and an optional track. It returns source (model when the model’s proposal passed the exact validator, oracle when the exact planner decided), feasible, reason when no route exists, up to 8 waypoints {x_nm, y_nm, alt_ft}, the validator’s verdict in check and latency_ms. Served routes are always valid under the exact checker; an infeasible plan answers 200 with feasible: false. The full shapes and a worked scene are on the Waymark Flight page.

Waymark Flight runs on a CPU service that scales to zero: the first call after a quiet period waits a few seconds and may answer 503 flight_warming with a Retry-After of 20 seconds.

/v1/chat #

Body: text (required, the current turn, at most 2,000 characters), optional history (up to eight prior turns as { "role": "user" | "assistant", "text": "…" }; older turns are dropped), optional max_new_tokens (8–256; the service itself caps generation at 96) and temperature (0–1.5, default 0.7). The route forwards the turn to Cognitio and returns its reply; 503 chat_unavailable when the Cognitio service is not configured.

{ "text": "long day. talk me through dinner ideas that take ten minutes?", "history": [ { "role": "user", "text": "hey" }, { "role": "assistant", "text": "hey — what's up?" } ], "temperature": 0.7 }

{ "ok": true, "engine": "cognitio", "text": "…" }

/v1/sound #

Body: text (required, a description of a sound, at most 400 characters after whitespace is collapsed) and optional seed (an integer that makes the render repeatable). Express Cue predicts a kind and a set of synthesis parameters and a deterministic engine renders them to 24 kHz mono WAV of 0.1–6 s. The response carries the audio and the parameters that produced it, so a host can edit and re-render them.

{ "text": "short bright chime, two notes rising", "seed": 7 }

{ "ok": true, "engine": "express-cue", "duration_seconds": 0.9, "params": { "kind": "chime", "duration": 0.9, "seed": 7 }, "wav_base64": "UklGR…" }

params is abbreviated; the full object, and the kind catalogue, are on the Express Cue page. The route has served Express Cue since 2026-09-13.

/v1/speak #

Body: text (required, English, at most 600 characters after whitespace is collapsed) and optional voice, one of the seven catalogue ids: lj (the LJSpeech voice, the default when the field is absent), female-1, female-2, female-3, male-1, male-2 or male-3 (the six Hi-Fi voices added on 2026-09-14). Express Voice speaks in that voice, echoes its id in voice and names itself in engine. It returns 16 kHz mono WAV. Behind the route is one GPU service (NVIDIA L4) holding all seven voices, kept warm with one minimum instance; the API passes the voice id through. A 14-word sentence renders in about 2.2–2.5 s and a short line in about 0.7 s.

{ "text": "Your table is ready. Please make your way to the front desk.", "voice": "male-3" }

{ "ok": true, "engine": "express-voice", "voice": "male-3", "duration_seconds": 3.5, "wav_base64": "UklGR…" }

A voice outside the catalogue answers 400 unknown_voice, and the body lists the accepted ids in voices. While the voice service is loading — a replacement instance, since the service is kept warm — the route answers 503 speak_warming with a Retry-After: 30 header; 503 speech_unavailable means no voice service is configured.

/v1/transcribe #

Body: audio (required; alias audio_base64, wav, wav_base64), one WAV, FLAC or OGG clip as base64, plain or as a data:…;base64, URL, at most 12 MB decoded; longer clips are transcribed for their first 60 seconds and the response says truncated: true. Any sample rate and channel count are accepted and resampled to 16 kHz mono. Express2Text returns lower-case English text with no punctuation.

{ "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAgD4AAAB9AAACABAAZGF0YQ…" }

{ "ok": true, "engine": "express2text", "text": "your table is ready please make your way to the front desk", "duration_seconds": 3.5 }

A missing or empty clip answers 400 audio_required; a clip that is not decodable audio answers 400 bad_audio; one over 12 MB answers 400 audio_too_large with maxBytes. While the voice service (which hosts Express2Text) is replacing an instance the route answers 503 transcribe_warming with Retry-After: 30; an organisation whose dedicated voice service predates Express2Text answers 503 transcribe_unavailable, and neither is counted. Every successful call counts one unit against the audio bucket.

/v1/voices #

Not metered. Returns the voice catalogue: an object with ok, engine (express-voice), default (the id spoken when voice is omitted, lj) and voices, an array of entries each carrying exactly id, label, gender (F or M), accent and region (the recording source). It comes from the voice service and holds seven entries: lj and the six Hi-Fi voices. The payload carries no licence text; the Hi-Fi corpus's CC BY 4.0 attribution is carried on the Express Voice page and in the Express series notes. Abbreviated:

{ "ok": true, "engine": "express-voice", "default": "lj", "voices": [ { "id": "lj", "label": "en-US female 1", "gender": "F", "accent": "American", "region": "LJSpeech" }, { "id": "male-1", "label": "Male voice 1 (audiobook, en-US)", "gender": "M", "accent": "American", "region": "LibriVox audiobook" } ] }

The reference client also accepts a bare array of entries and drops any entry without an id.

Quotas #

Calls are metered in four preview quota buckets — intention (/v1/intention and /v1/intention3d), spatial (/v1/spatial, /v1/move, /v1/airspace/read and /v1/airspace/plan), complete (/v1/chat) and audio (/v1/sound, /v1/speak and /v1/transcribe; /v1/voices is not metered) — and counted per UTC calendar month. The period is the YYYY-MM of the current UTC date; counters reset when the month changes.

• A call counts once, and only when it reaches the model: validation errors, 401, 402 and 503 do not count.
• When a bucket is exhausted the route returns 429 with error: "quota_exceeded" and kind naming the bucket. The check runs before the body is read.
• GET /v1/usage (authenticated) returns period, the usage counters and the quota allowance per bucket for the key’s account. A fourth counter, complete, appears in both objects and is not used by any route above.

Errors #

The audio codes — text_too_long, unknown_voice, sound_failed, speech_failed, sound_unavailable, speak_warming, speech_unavailable — follow the series pattern and are fixed with the routes.

Supported image types are JPEG, PNG, WebP, GIF, HEIC and HEIF; supported video types are MP4, MPEG, QuickTime, AVI, WebM, WMV, 3GPP and FLV. When mimeType is omitted the type is inferred from the data URL or the filename, defaulting to JPEG for images and MP4 for video.

Retries and loading #

The model services behind the API load their weights when an instance starts. The Falcon API and the Express Voice service are kept warm with one minimum instance each; Express Cue, the Waymark GPU service (Waymark and Waymark Extra), the Waymark Flight CPU service and Cognitio scale to zero after a quiet period. While a service is loading it answers 503; the convention across the series is one retry after 2.5 s, then treat the call as failed. The Falcon API applies this itself when it calls Waymark — a 503 or a timeout (45 s) from the Waymark service triggers a single 2.5 s wait and one retry before the route returns 502 spatial_failed — so a caller sees at most one such delay per request. The reference client applies the same rule to the Express services: a 45 s timeout, one 2.5 s wait and one retry on a 503 or a timeout.

For a 503 returned by the Falcon API itself (lim3d_unavailable, waymark_unavailable, move_unavailable, flight_unavailable, speech_unavailable) the same rule applies: retry once after 2.5 s, and if the second attempt also returns 503, stop; the service is not configured for that model rather than still loading. The exceptions are /v1/spatial and /v1/move, whose shared GPU service scales to zero — a cold start takes one to two minutes, so a host that sees 503 or 502 there after a quiet period should wait and try again after that window — and /v1/speak, where 503 speak_warming carries Retry-After: 30 and means the voice service is loading (only while an instance is replaced, since it is kept warm); wait that interval and try again. /v1/airspace/read and /v1/airspace/plan answer 503 flight_warming with Retry-After: 20 while the Waymark Flight service starts. Do not retry 400, 401, 402, 422 or 429; retrying 429 before the month changes cannot succeed.

Requests are not idempotent with respect to quota: a retried call that reaches the model counts again.

CORS #

The service answers OPTIONS with 204 and allows cross-origin requests only from the Falcon site origin, with the headers Authorization and Content-Type and the methods GET, POST, DELETE and OPTIONS. Browser code on any other origin cannot call the API directly; call it from your own server and keep the key there.

Health #

GET /health (alias /healthz) needs no token and reports which models the service can serve right now:

{
  "ok": true,
  "service": "falcon-api",
  "waymark": true,
  "lim3d": true,
  "limVariants": ["elim", "lim", "lim-nano"],
  "lim3dVariants": ["lim3d-xl", "lim3d"],
  "waymarkExtra": true,
  "expressCue": true,
  "expressVoice": true,
  "spatialImage": true,
  "spatialVideo": true
}

The payload also carries boolean flags for account-side features of the service; they are not model properties and are not documented here. A false for a model predicts the matching 503 code on its route.

Versioning #

Routes and envelope fields are stable within a model’s major version; a label added or removed, a renamed field or a changed frame is a major bump and is announced on the changelog. Fixed weights per version; the model does not learn from requests. See Status & versioning for the status vocabulary and the semver rules.