Lightning Rod's Foresight docs are a small, recently rebuilt GitBook portal (6 guide pages, 3 API-reference pages) with good agent affordances (llms.txt, llms-full.txt, .md endpoints) — but the reference lags the live API badly: two-thirds of the live OpenAPI operations are undocumented, the embedded spec disagrees with the published spec on paths and constraints, and the enum in the reference contradicts the values every guide tells you to send.
1. Entire Files and Batches APIs are undocumented — 8 of 12 live operations missing from the docs (critical)
Problem: The live OpenAPI spec — the one https://www.lightningrod.ai/llms.txt tells agents is canonical ("OpenAPI spec: https://api.lightningrod.ai/openapi.json") — exposes 12 operations, including a complete Files API (POST /v1/files, GET /v1/files/{file_id}, GET /v1/files/{file_id}/content, DELETE /v1/files/{file_id}) and Batches API (POST /v1/batches, GET /v1/batches, GET /v1/batches/{batch_id}, POST /v1/batches/{batch_id}/cancel). The docs portal contains zero occurrences of "batch" or "files": they're absent from the llms.txt index, the API reference pages, and every guide.
Consequence: Batch processing is exactly what a forecasting API's heaviest users need ("Use ensemble predictions. Send the same request multiple times" — the Recipes page even prescribes a batch-shaped workflow without mentioning the Batch API). Developers who only read the docs will hand-roll request loops against a 120 rpm rate limit; agents that read the spec will discover endpoints with no prose on file formats, batch lifecycle, pricing, or limits. 8 of 12 operations (67%) is not a gap, it's a second product.
The fix: Add a Batches + Files section to the API reference (generated from the same spec) covering the input file format, batch states, completion windows, and billing; link it from the Recipes ensemble advice.
2. Three different API base URLs in circulation, and the two published OpenAPI specs disagree on every path (significant)
Problem: The quickstart, OpenAI guide, marketing site, and GitHub README all say base_url="https://api.lightningrod.ai/v1/openai". The marketing llms.txt says "Base API URL: https://api.lightningrod.ai/v1". The live openapi.json defines paths as /v1/chat/completions, /v1/completions, /v1/models (its own x-guidance says "Call the forecasting product at POST /v1/chat/completions"), while the OpenAPI document embedded in the GitBook API reference defines the same operations as /v1/openai/chat/completions, /v1/openai/completions, /v1/openai/models. Live probes show all three prefixes are routed (/v1/…, /v1/openai/…, and the legacy /api/public/v1/openai/… all return 401 "Invalid or inactive API key" on an invalid key), but no page says which is canonical or that the others are aliases.
Consequence: A human copy-pasting the quickstart is fine; an agent reconciling the two specs is not — codegen from the GitBook spec and codegen from the live spec produce clients that hit different paths, and a strict agent will conclude one of the two specs is wrong. Anyone constructing raw URLs from the marketing llms.txt plus the agentic-payments guide (POST /v1/openai/chat/completions) gets a third answer.
The fix: Pick one canonical base URL, document the others as supported aliases in one sentence in the quickstart and API reference, and publish the same OpenAPI document to both GitBook and api.lightningrod.ai.
3. AnswerTypeEnum in the API reference contradicts every guide: uppercase enum values, a fifth undocumented type, and auto missing from the enum (significant)
Problem: The schema published in the reference is "AnswerTypeEnum":{"type":"string","enum":["BINARY","MULTIPLE_CHOICE","CONTINUOUS","CONTINUOUS_VALUE_ONLY","FREE_RESPONSE"]}, with answer_type typed as anyOf: [AnswerTypeEnum, const "auto", null]. Every guide — and the schema's own description ("One of binary, multiple_choice, continuous, free_response, or auto") — uses lowercase values. So the machine-readable contract says UPPERCASE-or-auto, the prose says lowercase, and CONTINUOUS_VALUE_ONLY appears in the enum but in no guide, no answer-format table, and no example anywhere.
Consequence: An agent or codegen tool validating requests against the schema will reject the lowercase values every example uses (or emit uppercase values the examples never show), and developers who spot CONTINUOUS_VALUE_ONLY have no way to learn what it returns or when to use it. Structured-output parsing is the product's headline feature; its type enum shouldn't be self-contradictory.
The fix: Make the enum values match the documented lowercase strings, include auto in the enum (or document the casing rule), and either document CONTINUOUS_VALUE_ONLY's response shape in the answer-format table or remove it from the public schema.
4. The Python SDK page never tells you how to install the SDK or what the package is called (significant)
Problem: The page opens with "## Minimal example" and import lightningrod as lr. There is no install command anywhere on docs.lightningrod.ai (pip install appears zero times in the full llms-full.txt export). The package name, lightningrod-ai — which notably differs from the import name lightningrod — is published only in the GitHub README.
Consequence:pip install lightningrod is the obvious guess and it's wrong. A developer or agent following the docs alone hits ModuleNotFoundError and has to leave the docs site to learn the package name. The quickstart has the same gap for openai.
The fix: Add pip install lightningrod-ai as step one of the SDK page (and pip install openai to the quickstart), noting that the PyPI name differs from the import name.
5. Top-up amount limits: the GitBook reference says "$1.00–$10,000.00", the live spec has no limits, the guide says "clamped" without saying to what (significant)
Problem: The GitBook reference's MppTopupRequest declares "minimum":100,"maximum":1000000 and "Range $1.00–$10,000.00". The live openapi.json defines the same object with no minimum, no maximum, and no range in the description ("Top-up size in cents. Defaults to 500 ($5.00). Must be identical on the challenge call and the paid retry."). The guide hedges with "clamped to the credit-purchase limits" and never states the limits.
Consequence: This endpoint is explicitly designed for autonomous agents moving real money with no human in the loop. An agent reading the live spec has no way to know a $15,000 top-up will be rejected (or clamped — the docs don't even say which); an agent reading the GitBook spec gets constraints the canonical spec doesn't confirm. Payment-adjacent contracts are the last place two specs should disagree.
The fix: Add the min/max constraints to the live openapi.json, state the range in the guide's prose, and document whether out-of-range amounts are rejected or clamped.
6. Metered, credit-based billing with zero pricing documentation (significant)
Problem: The API is prepaid and metered — the Usage schema exposes cost_usd, inference_cost_usd, research_cost_usd, classification_cost_usd; research sources are "billed as a separate RESEARCH event"; ResearchOptions warns "Each provider is billed separately." But no docs page states a single price: no per-token rates, no research-event price, no classification price. The only published number is on the marketing site ("Foresight $6 / 1M" output tokens), and even the spec's x-guidance shrugs: "these endpoints do not carry a fixed price."
Consequence: Developers (and paying agents, who literally top up credits through the API) cannot estimate cost before spending. You can't compare "turn on research" vs "curate your own context" — advice the Recipes page gives — without knowing what a research event costs. The only discovery mechanism is spending money and reading usage afterwards.
The fix: Publish a pricing page in the docs with per-model token rates, per-source research event pricing, and classification cost; link it from the usage field docs and the Recipes cost section.
7. Official SDK README links to a docs page that 404s, and legacy doc URLs redirect into 404s (significant)
Problem: The README (repo homepage is docs.lightningrod.ai, pushed as recently as 2026-07-10) says "See the forecasting guides for how to write good forecasting prompts" — that URL returns 404. Meanwhile the old docs tree still half-exists: /python-sdk/forecasting/overview 307-redirects to /forecasting/overview, which 404s, and .md not-found responses are served with HTTP 200 "Page Not Found" bodies.
Consequence: The GitHub README is most developers' first touchpoint, and its one deep link into the guides is dead. The redirect-into-404 chains mean search results and AI caches (which still surface old pages claiming "foresight-v3 is Lightning Rod's latest forecasting model" and "$50 of free credits") land users nowhere, and the 200-status 404 bodies make dead links invisible to link checkers and agents alike.
The fix: Point the README link at /forecasting/recipes, fix redirect targets for the old /python-sdk/* tree, and return real 404 status codes on .md not-found responses.
8. No error reference: only 429 is documented; the 401 response shape appears nowhere (minor)
Problem: Error handling documentation consists of one blockquote sentence about rate limits ("Exceeded requests receive a 429; check Retry-After and X-RateLimit-* headers") and a passing mention that exhausted credits return 402. A live request with a bad key returns 401 {"detail":"Invalid or inactive API key"} — a response shape documented nowhere. There is no error page listing statuses, bodies, or retry guidance.
Consequence: Developers writing error handling for a paid, credit-metered API have to discover the error contract empirically — including the 402-on-empty-balance flow their agents are supposed to recover from automatically.
The fix: Add an Errors page enumerating 401/402/422/429 with example JSON bodies and recommended handling, and reference it from the quickstart.
9. reasoning_effort usage contradicts its own schema note (minor)
Problem: The schema for reasoning_effort says "With raw OpenAI clients pass via extra_body", but the OpenAI API guide's example passes it as a top-level kwarg (reasoning_effort="low") — the opposite of what the same page's reference material instructs, and inconsistent with answer_type and research, which the guide does route through extra_body.
Consequence: Works with current OpenAI Python clients (which accept reasoning_effort natively) but breaks with older clients and other-language SDKs that reject unknown kwargs; a reader can't tell which extensions need extra_body and which don't.
The fix: Use extra_body consistently in examples, or add one sentence explaining that reasoning_effort is a native OpenAI parameter while answer_type and research are not.
What they do well
First-class agent affordances: llms.txt, llms-full.txt, .md versions of every page, and an OpenAPI spec advertised to agents — plus a genuinely novel no-signup MPP key flow.
Honest, practical guidance: the Recipes page documents a real footgun (low max_tokens truncating reasoning before the answer) and tells you to use reasoning_effort instead.
The agentic-payments guide documents the full 402-challenge → pay → retry loop with real headers and response bodies.
Top 3 recommendations
Document the Files and Batches APIs — two-thirds of the live API surface has no docs at all.
Unify the two OpenAPI documents (paths, AnswerTypeEnum casing, MppTopupRequest limits) so the machine-readable contract matches the guides.
Publish pricing and an error reference — a prepaid, metered API where agents pay real money needs both.