Before the main agent runs, every generation request passes through a preflight check — a fast, cheap LLM call that reads your prompt and the metadata of any assets you’ve attached. If the request can’t succeed (because a required image, data file, or brand asset is missing), Overten rejects it with a 400 preflight_failed error before any agent work starts — and before any credits are deducted.
What preflight does
The preflight validator answers two questions:
- Is this request fulfillable? If your prompt references something you didn’t provide — “embed product screenshots” with no images attached — the validator catches it and tells you exactly what’s missing.
- What does the agent need to plan for? Preflight tags the request with detected intents (
visual_first, data_heavy, financial_model, etc.) that the downstream agent uses to select sensible defaults.
The tradeoff is deliberately in your favor: a fast, cheap preflight call prevents a full agent run from producing broken output with a [IMAGE MISSING] placeholder — or worse, silently substituting something wrong.
What preflight sees
The validator reads metadata only — names, counts, and tags. It never sees the actual bytes of any uploaded file. Here’s an example of the context it works with:
{
"prompt": "10-slide Q3 investor update with product screenshots",
"format": "slides",
"mode": "action",
"assets_summary": {
"images": { "count": 0, "items": [] },
"data_sources": { "count": 1, "items": [{ "name": "mrr.csv", "kind": "csv" }] },
"reference_files": { "count": 0, "items": [] },
"brand": { "has_logo": false, "has_colors": false, "has_font": false }
}
}
{
"valid": false,
"missing": ["images"],
"reason": "Prompt requests 'product screenshots' but no image assets were provided.",
"detected_intents": ["visual_first", "data_heavy"]
}
Common rejection patterns and fixes
| Prompt fragment | Missing asset | Fix |
|---|
| ”with product screenshots” | images | Upload via POST /images, then include the image_id in image_assets |
| ”using the attached CSV” | data_sources | Upload via POST /files, then reference in data_sources |
| ”based on these contracts” | reference_files | Upload and reference in context_files |
| ”in our brand colors” | brand | Include brand: { primary_color, font, logo_url } in the request body |
Testing requests manually
You can call the preflight endpoint directly to check whether a request will pass before submitting it for real:
POST /api/v1/preflight
Content-Type: application/json
Authorization: Bearer $OVERTEN_API_KEY
{
"prompt": "10-slide investor update with product screenshots",
"format": "slides"
}
Use POST /preflight in your UI to surface validation errors to users before they submit — it’s fast (p50 ~400ms, p95 ~800ms) and free.
When preflight rejects a request
If preflight fails, the generation endpoint returns:
400 Bad Request
{
"success": false,
"error": "preflight_failed",
"message": "Prompt requests 'product screenshots' but no image assets were provided.",
"missing": ["images"],
"detected_intents": ["visual_first", "data_heavy"]
}
Tuning for false positives
If preflight is rejecting requests that should pass (“my prompt wasn’t really asking for images”), a few options:
- Rephrase the prompt. The validator is pattern-sensitive. Softer language like “include visuals where appropriate” won’t trigger a rejection; explicit phrasing like “with product screenshots” will — because the agent would genuinely need those images to succeed.
- Attach a placeholder asset. For visual-first decks, uploading one generic placeholder image lets the validator pass. The agent may or may not use it, depending on your prompt.
- Report the false positive. File an issue — we tune the preflight prompt continuously, and false positives are a direct input into that process.
Failure behavior (preflight LLM unavailable)
If the preflight validator is slow or unavailable, Overten fails open — the request proceeds as if valid: true. This prevents transient validator issues from blocking your API calls. The main agent will still attempt the work in these cases. 
