Automatic model choice

POST /v1/auto takes a request meant for any Falcon model, chooses the model and the route it belongs to, runs that route with the exact bytes you sent, and returns the route’s own answer with one more key, choice, which names the model and the route that ran, how they were chosen and why. Choosing is free: the call is billed as the chosen route, once.

What it does #

/v1/auto stands in front of sixteen model routes. It reads the request, decides which one fits, and hands the received body, unchanged, to that route, which then runs exactly as a direct call would: the same validation, the same quota bucket, the same answer, the same errors. Nothing is rebuilt or rewritten on the way.

It never chooses GET /v1/voices (a free catalogue), itself, a playground route under /v1/try/, or a withdrawn route. /v1/auto needs a key, or an account fls_ session token as every keyed route accepts; the portal sandbox calls it for you with your portal session. There is no keyless playground spelling, and /v1/try/auto answers 404. GET /v1/auto, with no key, describes the rules below as JSON — the routes and their signal fields, the model ids, the instruction words, the wording rules, the picture rule, how Cognitio is asked, the withdrawn routes and models, and every rule id — and counts nothing. GET /health carries auto: true while the route is switched on.

Send a request #

POST /v1/auto with Authorization: Bearer fln_… (or an fls_ session token) and a JSON object of at most 24,000,000 bytes: the body you would send to the route itself, plus, if you like, a few options inside one reserved object, auto.

auto rides along in the forwarded body and is inert: no route reads it and no model service receives it. It must be an object with only those four keys, of those types (null is read as no options); anything else answers 400 bad_auto with field and hint. The options go inside auto: a top-level route, want, dry_run or chooser answers 400 bad_auto, with a hint that shows where it goes, rather than being ignored.

How the choice is made #

The request is read in a fixed order, and the first step that decides ends it:

1. Withdrawn. model: "lim-nano" answers 410 model_withdrawn with successor e-lim, as /v1/intention does; auto.route naming a withdrawn route answers 410 route_withdrawn with that route’s successor. Nothing runs.
2. A named route, auto.route: that route runs.
3. A named model, model: it runs on its route (Naming a route or model).
4. Fields that only one route reads (Fields that decide).
5. The picture rule, when the body carries an image or a video (Pictures and video).
6. Your instruction, auto.want (Your instruction: auto.want).
7. Clear wording in text (Words that decide).
8. Cognitio picks, only when the words are still unclear, and only among /v1/chat, /v1/summarize, /v1/sound and /v1/parse (When Cognitio picks).

An explicit choice always wins, and a contradiction — a model that does not run on the named route, or fields that point where the named model does not run — is refused with 400 choice_conflict, never settled by a guess. Where the request does not say enough, the answer is 422 choice_needed with the routes it could mean, each with the exact send object that picks it.

Once a route is chosen, a body over that route’s own byte limit answers 413 body_too_large with max_bytes and is never forwarded; a dry run answers the choice; anything else runs.

Naming a route or model #

With auto.route you name the route outright. Nothing else is consulted: not the fields, not the picture rule (naming /v1/spatial or /v1/gaze/photo is your choice to make), not auto.want, not the words. If model is also present, it must run on that route, or the answer is 400 choice_conflict with model, route and routes_for_model. A path that is not one of the sixteen, including /v1/voices, /v1/auto and the /v1/try/ paths, answers 400 unknown_route with routes listing them.

With model you name the model. When the body also carries fields that point to routes, the model runs on the first of those routes it serves, in the order of the route table above; if it serves none of them, the answer is 400 choice_conflict with fields_point_to and routes_for_model. Without such fields the model runs on its main route, and that route answers its own 400 if the body does not fit (text_required, for example). Once a model has decided, auto.want is not read.

Ids are matched exactly, as on the routes, except the two Waymark ids, which are trimmed and lower-cased as /v1/spatial does. Any other value — a number, null (which /v1/agent would read as Cognitio) or an unknown id — answers 400 unknown_model with models listing the seventeen and the hint “Leave model out to let the API choose.” A voice condition that would quietly run another model is refused, never resolved: express-voice with a voice_code, or express-voice-blend on /v1/speak without one, answers 400 choice_conflict with the hint “A voice_code is Express Voice Blend; name express-voice-blend, or leave model out.”

A few bodies and where they go: an image_base64 with model: "waymark-gaze" runs on /v1/gaze/photo; with model: "waymark", on /v1/spatial, where a third-party model sketches the picture first, because you named Waymark; with model: "e-lim", 400 choice_conflict. A text and a title with model: "cognitio-infer" is a conflict too (title is /v1/summarize’s, where Cognitio Infer does not run), and messages with model: "cognitio" runs /v1/agent with Cognitio.

Fields that decide #

A field that only one route reads is a signal for that route. The fields present point to a set of routes: one route, and it runs, with rule fields: and the route’s id (fields:move, fields:airspace-read); two or more, and the answer is 422 choice_needed with need "fields" and one choice per route; none, and the next steps decide.

Some fields never decide, because several routes read them or none does: text, model, auto, mover, rate, pitch, max_new_tokens, temperature, mimeType, mime_type, filename, and any field no route reads. They are forwarded and read by the chosen route as usual. “Present” means the key is in the object with a value other than null. The fields only choose; the chosen route still checks the body and answers its own errors, such as 400 consent_required for clips without consent: true.

Pictures and video #

The rule applies when the body carries image, image_base64, video or video_base64 and neither a named route nor a named model decided:

• A scene — question or sketch is present: /v1/spatial with Waymark, rule picture:scene.
• A face — mapping is present, with image or image_base64 and no video field: /v1/gaze/photo with Waymark Gaze, rule picture:face. Waymark Gaze reads still photos only, so a video with a mapping is not a face.
• Neither, or both — 422 choice_needed with need "picture" and both choices, rule picture:no-signal or picture:both, whatever else the body carries.

A scene or a face whose body also carries the fields of another route answers 422 choice_needed with need "fields" and a choice for each route.

These are not signals, on purpose: text (six routes read it, and on /v1/spatial it is only another name for the question), the file format, the MIME type, the file name, and the picture’s content or size. A video alone is refused too: sending a recording to a third-party sketching model must be your choice. To send a picture, name the model or the route, or add question or mapping.

A picture or a video sent as text is refused the same way when nothing else decided, with a hint that it goes in image_base64 or image (video_base64 or video for a video). It is looked for anywhere in the first 64,000 characters of the text, whatever surrounds it (a sentence, Markdown, HTML, JSON or quotes): a data:image/… or data:video/… URL, or a run of at least 64 characters of base64 or base64url that starts like a PNG, JPEG, GIF, WebP, BMP, TIFF, SVG, MP4 or WebM file, whatever type a data: URL names. It is never shown to Cognitio. To send it, first move it out of text into image_base64 (or video_base64); then a choice’s send applies. Merging send into a body whose picture is still in text names a route that finds no picture, and that route answers its own 400. To send such a text as it is, name the route with auto.route.

{
  "ok": false,
  "error": "choice_needed",
  "need": "picture",
  "message": "A picture can be a scene or a face, and the two go to different places. Name one and send again.",
  "choices": [
    {
      "model": "waymark",
      "label": "Waymark",
      "route": "/v1/spatial",
      "bucket": "spatial",
      "send": { "model": "waymark" },
      "note": "A scene: a third-party model first sketches the picture, then Waymark answers about the layout."
    },
    {
      "model": "waymark-gaze",
      "label": "Waymark Gaze",
      "route": "/v1/gaze/photo",
      "bucket": "spatial",
      "send": { "model": "waymark-gaze" },
      "note": "A face: eyes, head pose and gaze features on Falcon's private service; nothing is stored or logged. Still photos only."
    }
  ],
  "choice": {
    "model": null,
    "label": null,
    "route": null,
    "bucket": null,
    "by": "fields",
    "rule": "picture:no-signal",
    "why": "A picture with no question, sketch or mapping could be a scene or a face."
  }
}

Your instruction: auto.want #

auto.want says in words what you want done with the content, kept apart from it, so the instruction is never mistaken for the text. It is read only when no named route, named model, field or picture decided. The words are matched case-insensitively, as whole words or phrases, after curly quotes are made straight and white space is collapsed:

“In a … voice” allows up to six words between “in a” and “voice” (“in a calm, low voice”). “Speech”, “audio”, “read it” and “read this” name the speak job only on their own, with a polite opening, “please”, “for me” or “now” around them (“speech please”, “read it for me”), or inside the phrases listed: “draft a speech”, “transcribe the audio” and “read this and fix the grammar” name no job, and “read it and summarise it” asks for a summary. “A sound” counts only as a noun: at the end, or before “of”, “like”, “for” or a colon (“a sound plan” is not a sound), and “audio” before “cue”, “effect”, “alert” or “tone” is not speech. “Table”, “tabular”, “rows”, “columns” and “records” name the parse job only when no other job is named, since they are as often what a job is done to: “put it in a table” is parse, “summarise the rows” is a summary and “explain the table” is chat. “Write a summary” and “write me a tl;dr” ask for a summary, not for chat.

• One job — its route runs with the route’s default model (E-LIM on /v1/intention, Express Voice on /v1/speak), rule want: and the job (want:speak).
• Two or more — 422 choice_needed with need "want" and the matched routes as choices: “read it aloud and summarise it” names two jobs.
• None — 422 choice_needed with need "want", the six text routes as choices and the message “auto.want did not name a job this API knows.” An instruction you wrote is never replaced by a guess from the text, and Cognitio never reads auto.want.
• Empty — a want that is empty or only white space is no instruction, as null is: the words of text decide.

auto.want is read only when nothing before it decided, and it never overrides what did: with title in the body, /v1/summarize runs whatever auto.want says, and with model: "cognitio", /v1/chat runs. To have an instruction decide, leave out the fields and the model that point elsewhere, or name the route with auto.route; a dry run shows which step decided in choice.by.

The chosen route reads text, never auto.want, so the instruction itself is not spoken, summarised or scored. {"text": "Your table is ready. Please make your way to the front desk.", "auto": {"want": "read it aloud"}} is spoken by Express Voice on /v1/speak; {"text": "what's the difference between etf and mutual fund", "auto": {"want": "check it for harmful intent"}} is read by E-LIM on /v1/intention.

Words that decide #

When nothing above decided, the words of text can. text must then be a string with something in it besides white space; otherwise the answer is 400 nothing_to_route with the hint “Send text, the fields of one route, or name a route in auto.route; GET /v1/auto lists them.” The rules are tried in this order, and the first that matches decides. Cues are looked for at the start of the text — its first 300 characters, trimmed, with curly quotes made straight, white space collapsed and letters lower-cased — and a polite opening (“please”, “kindly”, “can you”, “could you”, “would you”, “will you”) is allowed before most of them. Every length is measured as the route that would run measures it.

1. A scene sketch (text:sketch). A text that starts with kind: scene, or has a line starting objects: and a line starting relations: in its first 256,000 characters, is a sketch sent in the wrong field: 422 choice_needed with need "sketch", the choices /v1/spatial, /v1/move and /v1/intention3d, and the hint “A scene sketch goes in sketch, with question, goal or steps.” The routes read sketch, not text, and the body is never rebuilt to move it.
2. Speech or an intention reading asked for in the text (text:asked-in-text). A text that opens by asking for itself to be said or read aloud (“Read this aloud: …”, “Say this: …”, “tts: …”, or a quoted phrase that ends the text, such as “Say ‘welcome to the lab’”) or for the intention behind a message it names or quotes (“What is the intention behind this message …”, “Check the intent of this: ‘…’”, “Is this message harmful …”) answers 422 choice_needed with need "text" and the message “Speech and intention readings read every word, this request too, so they run only when asked outside the text: add auto.want, model or auto.route.” The choices include /v1/speak with send {"auto": {"want": "read it aloud"}} and /v1/intention with send {"model": "e-lim"}. This answer is free and Cognitio is not asked. Questions that only mention saying or intent are not such requests: “Can you say ‘hello’ in Japanese?” and “What is the intent of this function in my code?” go on to the rules below.
3. A request for a summary (text:summarize). A text that opens with a request for a summary, such as “Summarize”, “Summarise”, “Sum this up”, “TL;DR”, “Give me a short summary” or “Write a brief summary”, followed by at least 60 words, goes to /v1/summarize, which answers its own 413 text_too_long above 12,000 characters. With fewer than 60 words after the cue it is a request to write about a topic, and goes to /v1/chat (text:question) if it is at most 2,000 characters.
4. A sound (text:sound). A text of at most 400 characters that asks for a sound (“Make a sound effect of a creaking wooden door.”, “Create a soft chime”, “Make a sound like a bell”, “Can you make a short chime?”), names one in a short description of at most 12 words and one sentence (“short bright chime, two notes rising”, “a soft whoosh”) or is labelled as one (“sfx: …”, “sound effect: …”) goes to /v1/sound. The sound’s name, or “sound” on its own, must end its phrase: it is followed by the end of the text, punctuation, a dash, or “of”, “like”, “for”, “that” or “with” (“sound”, “noise” or “effect” may follow the name, as in “a beep sound”). Otherwise it describes something else, so “Make a ringtone app for Android”, “Make a beep function in Python”, “Make a whoosh effect in CSS” and “Make a sound decision” are not sounds. A sound named or labelled without a verb is never a question: a text that ends with a question mark is left to the rules below. Neither form is a sound when a question word opens a clause after it (“A beep keeps sounding from my smoke alarm, what should I do”).
5. A question or a request to write (text:question). A text of at most 2,000 characters that opens with a question word or a request, such as what, who, when, where, why, how, which, is, are, do, does, can, could, would, should, will, may, explain, describe, define, compare, translate, list, suggest, recommend, tell me, write, draft or help me, or is a greeting of at most eight words (hi, hello, hey, good morning, thanks) goes to /v1/chat. A data file is data even when its first line starts with such a word: when rule 6 reads the text from its first line as data and that line is a header row, rules 3 to 5 do not read it, and rule 6 decides. A header row has at least two cells of at most four words each; no cell holds a question mark or an exclamation mark, a colon before a space or at its end, or a final full stop; and when a delimiter on it is followed by a space, so is one on a later line. So when,event, Who,Score, How many,Item, List price,Qty,SKU and When | Where start data, while “Hi, who scored most?”, “Explain, briefly:”, “Explain: x,y” and “Compare these prices, cheapest first” above rows of milk,2.50 are requests about the data that follows.
6. Data (text:table). A text whose first lines have the shape of a data file goes to /v1/parse: of its first 20 non-empty lines (at least 3), every line holds the same number of commas, tabs, semicolons or pipes outside double quotes (two or more, or one with digits after the first line), or every line is a JSON object, or every line starts with a date and time (2026-10-01 12:00), or one line is a Markdown table rule; and fewer than half the lines end like sentences. A first line of title or preamble is allowed. This rule reads the text as sent, line breaks included.
7. A question mark, or a request to make something (text:question). A text of at most 2,000 characters that ends with a question mark, ignoring closing quotes, brackets and spaces, or that opens with give me, make, create, compose, generate, plan or show me (“Give me a recipe for lentil soup”, “Make a list of chores for kids”), goes to /v1/chat. A sound asked for that rule 4 could not take, because it is longer than 400 characters or a question follows it, is left to Cognitio.

Speech and intention readings are never chosen from the words: they read every word, a request inside the text included, so they run only when asked for outside it — by voice or voice_code, model, auto.route or auto.want. The rules never strip or rewrite anything: the chosen route receives the whole text exactly as a direct call would.

When Cognitio picks #

Switched off at launch. An offline test of the chooser prompt on 2026-10-06 picked the wrong job for 18 of 45 unclear texts and followed 9 of 10 attempts to steer it from inside the text, so Cognitio is not asked for now: text the rules leave unclear gets 422 choice_needed with the choices and chooser "off", and GET /v1/auto reports the chooser as off. Everything else on this page works as described. The step will be switched on when a stronger chooser passes that test.

Only plain text that every rule above left unclear, sent with a key or an account session token, is shown to Cognitio, and only to choose between the routes that read plain text and can take it:

• The candidates are /v1/chat, /v1/summarize, /v1/sound and /v1/parse, kept only when the text and the body are within that route’s limits. None left answers 413 text_too_long with max_chars 256,000; one left answers 422 choice_needed with need "text" and rule text:one-fit, because a route is never picked by elimination; two or more, and Cognitio is asked. /v1/intention and /v1/speak are never candidates.
• Your quota: Cognitio is asked only among the candidates whose quota bucket you have not used up this month, read and not counted. With fewer than two left the answer is 422 with chooser "limited" and Cognitio is not asked, since the route would answer 429 quota_exceeded.
• What is sent: the trimmed text, cut to its first 1,000 characters, inside a fixed prompt that lists the jobs and says the text is data, not instructions. auto.want, the other fields and any picture are never sent. Cognitio answers with one word.
• To whose Cognitio: your organisation’s dedicated Cognitio when it has one, exactly as /v1/chat chooses; otherwise Falcon’s private shared Cognitio service, which logs no prompts.
• What counts: the word is accepted only when it names one of this request’s candidates. Cognitio is never accepted for speech or an intention reading. Any other answer gives 422 choice_needed with need "text" and chooser "unclear". Cognitio’s own output is never returned, logged or stored.
• Not billed: the pick costs nothing; only the chosen route is billed, as a direct call.
• Remembered for ten minutes: the same text from the same customer gets the same pick for ten minutes, so a dry run and the call after it, or a resend, land on the same route. Only a hash of the text and the word are kept, per customer.
• Bounded: one attempt of at most 3.5 seconds, at most two picks running at once on each API instance, and at most 30 picks a minute and 300 an hour per customer (a remembered pick does not count).
• Shared fairly: each customer has at most one pick running or waiting at a time. When two picks are already running, a request waits for the next one to finish, oldest first, for up to 3.5 seconds, so one customer’s picks never keep another’s out.

Cognitio sleeps after four hours without calls, and a keyed request whose words need a pick may wake it, as a /v1/chat call would. The answer is then 503 auto_warming, which carries the six text routes as choices beside retry_after_s: send the same request again after the interval, or pick a route yourself. The portal sandbox resends by itself, and the call is never quietly sent to chat instead. When Cognitio does not pick, the 422 lists the same six text routes as choices, in this order: /v1/chat, /v1/summarize, /v1/sound and /v1/parse, each picked with send {"auto": {"route": …}}; /v1/speak, with {"auto": {"want": "read it aloud"}}; and /v1/intention, with {"model": "e-lim"}. Each text choice also carries the longest text its route takes, as max_chars (max_bytes for /v1/intention, which is limited by the size of the body).

To keep a text away from Cognitio altogether, name model, auto.route or auto.want, or send "auto": {"chooser": "rules"}.

The answer #

The answer is the chosen route’s own: its status, its Retry-After header and its JSON object, field for field, with one key added, choice.

choice is on every answer given once the request has been read and checked: forwarded answers, the route’s own errors included; the 410 answers; 413 once a route is known; every 422; 400 choice_conflict and nothing_to_route; 503 auto_warming; and dry runs. On a refusal its model, label, route and bucket are null, and the options are in a top-level choices array of {model, label, route, bucket, send, note} (with max_chars or max_bytes on a text route), where send is the exact object to merge into your body to pick that option. No route answers a choice key of its own, so nothing is overwritten, and nothing else is added at the top level. The route’s own engine and model stay authoritative: on /v1/spatial, for example, engine names the third-party model when it wrote the answer.

Every rule id, grouped by by. GET /v1/auto lists each one, with its why, under rules.

A data file sent as plain text, abbreviated:

{
  "ok": true,
  "engine": "tabulate",
  "model": "tabulate",
  "format": "csv",
  "delimiter": ",",
  "quote": "\"",
  "header": true,
  "columns": [ { "name": "sku", "type": "identifier", "role": "id", "p_type": 0.98 } ],
  "rows": [ { "sku": "SKU-0041", "qty": 12, "price": 1204.5, "shipped": true } ],
  "row_count": 2,
  "choice": {
    "model": "tabulate",
    "label": "Tabulate",
    "route": "/v1/parse",
    "bucket": "parse",
    "by": "text",
    "rule": "text:table",
    "why": "The text is rows of data, so Tabulate reads it on /v1/parse."
  }
}

Dry runs #

"auto": {"dry_run": true} makes the whole choice, the byte-limit check included, and answers 200 with {"ok": true, "dry_run": true, "choice": {…}} without running the route. It counts nothing. A dry run of unclear words may ask Cognitio, and may answer 503 auto_warming like any other request; the pick is remembered for ten minutes, so the call you send next with the same text lands on the same route.

What it costs #

/v1/auto has no price, no quota bucket and no allowance of its own. The chosen route is billed exactly as a direct call, once, by that route: one unit in its bucket, or a /v1/agent turn by its size with its billed field. A 429 quota_exceeded comes from the chosen route and names its bucket. Choosing is free: refusals, 410 and 413 answers, dry runs and Cognitio’s pick count nothing. A pick that was not what you meant is billed as the route it reached, exactly as if you had named it; choice says how it was chosen, and naming a route or a model removes the guess. Through the portal sandbox the organisation is billed once. The rate of each bucket is on Portal.

Errors #

The answers /v1/auto gives itself; every other answer is the chosen route’s own, with choice. 401, 402 and 403 are the usual authentication answers. None of these counts against quota.

Only auto_warming invites a resend. Every refusal that says the API will not guess is a 4xx: change the request and send it again.

Examples #

A plain question #

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

{"text": "How far is the Moon from Earth?"}

Rule text:question sends it to Cognitio on /v1/chat, one response unit, and the answer is /v1/chat’s own with choice:

{
  "ok": true,
  "engine": "cognitio",
  "style": "assistant",
  "think": "off",
  "text": "…",
  "choice": {
    "model": "cognitio",
    "label": "Cognitio",
    "route": "/v1/chat",
    "bucket": "response",
    "by": "text",
    "rule": "text:question",
    "why": "The text is a question, a request or a greeting, so Cognitio answers it on /v1/chat."
  }
}

Read a line aloud #

{ "text": "Your table is ready. Please make your way to the front desk.", "auto": { "want": "read it aloud" } }

auto.want names the speak job, so Express Voice speaks the text, and only the text, on /v1/speak, one audio unit; choice reads by: "want", rule: "want:speak", model: "express-voice".

Name a model or a route #

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

LIM reads the turn on /v1/intention, exactly as a direct call with the same body, and choice reads by: "model", rule: "model", model: "lim". Naming the route instead, "auto": {"route": "/v1/summarize"}, runs /v1/summarize on any text, with by: "route" and rule: "route".

Ask first, run no route #

{ "text": "How far is the Moon from Earth?", "auto": { "dry_run": true } }

{
  "ok": true,
  "dry_run": true,
  "choice": {
    "model": "cognitio",
    "label": "Cognitio",
    "route": "/v1/chat",
    "bucket": "response",
    "by": "text",
    "rule": "text:question",
    "why": "The text is a question, a request or a greeting, so Cognitio answers it on /v1/chat."
  }
}

A picture with no signal #

{ "image_base64": "iVBORw0KGgo…", "text": "what is this?" }

text is not a signal for a picture, so the answer is the 422 under Pictures and video. Add "model": "waymark" or "question": "what is this?" for the scene, or "model": "waymark-gaze" or a mapping for a face.

The rules #

GET /v1/auto HTTP/1.1

No key is needed. The answer lists the order, the options, the sixteen routes with their models, limits and signal fields, the seventeen model ids, the instruction words, the wording rules, the picture rule, how Cognitio is asked, the withdrawn routes and models, and every rule id with its by and why.

Not a safety reading #

Automatic model choice is not a safety system, and it is not a safety reading: it adds, removes and bypasses no check of any route. E-LIM and LIM run only when asked for, and then exactly as on /v1/intention. Unclear words that Cognitio places on /v1/chat are treated exactly like a direct /v1/chat call. To read the intention behind a message, name E-LIM: "model": "e-lim", or auto.want such as “check it for harmful intent”.

Private organisation API copies #

An organisation’s private Falcon API address (dedicated hosting) runs the version it was provisioned with: it answers 404 on /v1/auto until the Falcon team provisions it again, and its other routes keep working. On the shared API, dedicated services are honoured as they are for any call: the chosen route uses your organisation’s own endpoint, and Cognitio picks on your organisation’s own Cognitio.