The docs cover a real, OpenAI-compatible forecasting API with a Quickstart, an OpenAI/SDK guide, Recipes, an enterprise overview, and a three-page API reference backed by an OpenAPI spec — but the single most important value for any first request (the base URL) is documented three different ways, the research-source example is invalid, the answer_type enum disagrees with itself by case, and there is no Authentication, Errors, Rate-limits, or Pricing page at all.
1. Three contradictory base URLs for the same endpoint (critical)
Problem: The base URL a client must point at is documented three incompatible ways. The Quickstart, SDK page, and GitHub README all use https://api.lightningrod.ai/v1/openai. The API reference Chat Completions description says: "point base_url at https://api.lightningrod.ai/api/public/v1/openai." The OpenAPI servers block (in both models.md and mpp-machine-payments-protocol.md) declares {"url":"https://api.lightningrod.ai/v1"}. That is three distinct prefixes — /v1/openai, /api/public/v1/openai, and /v1 — for the same OpenAI-compatible surface.
Consequence: This is the one field a developer cannot guess. Whichever page they land on first, a different page contradicts it, and a wrong prefix returns a connection/404 error before authentication or any parameter even matters. For an AI coding agent, this is worse: an agent that ingests the OpenAPI spec will build .../v1/openai/chat/completions against a /v1 server, while one that reads the reference prose builds /api/public/v1/... — and both fail silently with no way to reconcile.
The fix: Pick one canonical base URL, assert it once, and make the OpenAPI servers value, the reference prose, the Quickstart, the SDK page, and the README all render from (or match) that single source of truth.
2. Documented research source google_news is not a valid enum value (critical)
Problem: Both the OpenAI guide and the SDK guide use the research source value . The API reference and the schema list the only valid sources as (Perplexity web search), (recent news articles), and (Google web results). appears in no enum anywhere.
Code verification
Runtime snippet checks
Run the public examples from this audit in an isolated sandbox and attach the pass, fixed, skipped, and failed counts to the report.
Consequence: A developer (or agent) who copies the canonical research example verbatim hits a 422 validation error on their first research-enabled call — and the docs document 422 only as a bare "Validation Error" with no body schema, so there is no message telling them google_news was the offending token. The example that is supposed to demonstrate the flagship feature does not run.
The fix: Replace google_news with google_search (or news) in both guide examples, and add a test that lints code samples against the live ResearchOptions enum.
3. answer_type enum disagrees with its own prose by casing, plus an undocumented value (significant)
Location:/api-reference/models.md (AnswerTypeEnum) vs. /api-reference, /forecasting/*, /forecasting/recipes.md
Problem: Every prose description, table, and example uses lowercase values — binary, multiple_choice, continuous, free_response, auto. The AnswerTypeEnum schema in models.md is UPPERCASE and additionally contains CONTINUOUS_VALUE_ONLY, a value that is never mentioned in any prose, table, or example anywhere in the docs. (auto is also modeled as a separate const, not part of the enum.)
Consequence: A developer who reads the schema cannot tell whether the API wants "binary" or "BINARY", and an agent generating from the schema will emit uppercase values that the prose examples imply are wrong — or vice versa. CONTINUOUS_VALUE_ONLY is a documented-but-unexplained capability: nobody can use it because nothing says what it does or when to pass it.
The fix: Make the schema enum and the prose use identical casing for the same accepted values, document CONTINUOUS_VALUE_ONLY (its shape and when to use it) or remove it from the public schema, and state explicitly whether answer_type matching is case-sensitive.
4. No Authentication, Errors, Rate-limits, or Pricing pages exist (critical)
Problem: The entire docs surface is 5 guide pages plus 3 API-reference pages. There is no Authentication page, no Errors/status-codes page, no Rate-limits page, no Pricing page, and no Changelog — despite the API issuing Bearer API keys, supporting credit top-ups, returning cost_usd/*_cost_usd usage fields, and serving versioned models (foresight-v4). The Chat Completions endpoint documents only 200 and 422 responses; 401, 403, 429, and 5xx are nowhere.
Consequence: A developer who ships against this API has no documented contract for the failure cases they will actually hit in production: an expired/invalid key (401/403), exhausted credits, or being rate-limited (429). They cannot write correct retry/backoff or error-handling code because the error shapes and status codes are undocumented. Pricing — for an API that bills per request and per RESEARCH event — has to be reverse-engineered from usage fields at runtime.
The fix: Add an Authentication page (how to get a key, header format, expiry/rotation), an Errors page enumerating every status code and the JSON error body, a Rate-limits page, and a Pricing page that ties cost_usd/research-event billing to dollar amounts. At minimum, document 401/403/429/5xx responses on the endpoints.
5. The SDK page never shows how to install the package (significant)
Location:/forecasting/sdk.md (vs. GitHub README)
Problem: The Python SDK guide jumps straight to a lr.predict() example but never contains pip install lightningrod-ai. The install command appears only in the GitHub README. Worse, the install name and the import name differ: you pip install lightningrod-ai but import lightningrod as lr.
Consequence: A developer following the docs SDK page in isolation has working example code and no way to get the package — and if they guess the install name from the import (pip install lightningrod), they install the wrong (or a nonexistent) package. Agents that scaffold a project from the docs page will emit code with no install step.
The fix: Put pip install lightningrod-ai at the top of the SDK page and call out explicitly that the install name is lightningrod-ai while the import is lightningrod.
6. top_k and min_p are documented as ordinary fields but are non-standard params (significant)
Location:/api-reference (Chat Completions body)
Problem: The reference is careful to flag answer_type, research, and reasoning_effort as Lightning Rod extensions that "with raw OpenAI clients pass inside extra_body." But top_k and min_p are listed as plain body fields with no such note — even though neither is a standard OpenAI Chat Completions parameter and both would need the same extra_body treatment with a stock OpenAI client.
Consequence: A developer using a raw OpenAI SDK sets top_k/min_p as top-level kwargs (as the table implies), the OpenAI client rejects or silently drops them, and the sampling behavior they intended never takes effect — with no error pointing at the cause.
The fix: Mark top_k and min_p with the same "pass via extra_body in raw OpenAI clients" note used for the other extensions, or move them into a clearly labeled extensions group.
7. reasoning_effort is restricted to three values in prose but unconstrained in the schema (significant)
Location:/api-reference (prose) vs. /api-reference/models.md (schema)
Problem: The endpoint prose says reasoning_effort is "low, medium, or high," and Recipes builds an entire cost-optimization tip around "low". But in the models.md schema, reasoning_effort is typed as a free-form string with no enum.
Consequence: An agent generating a client or validation layer from the schema will treat reasoning_effort as an arbitrary string and may emit invalid values like "min" or "none"; a developer reading only the schema has no idea the field is actually a closed set. The two sources disagree on what is acceptable input.
The fix: Add the ["low","medium","high"] enum to the schema so it matches the prose (and so generated clients validate correctly).
8. The "REST API reference" link is a dead deep-link, and two different URLs name the same page (significant)
Problem: The OpenAI guide links to https://docs.lightningrod.ai/rest-api#post-openai-chat-completions. /rest-api 301-redirects to /api-reference, and the #post-openai-chat-completions anchor does not exist on that GitBook page. Separately, the same reference is linked two different ways across the docs: /rest-api#... here and /api-reference in the Quickstart.
Consequence: A developer clicking the deep-link lands on the API reference scrolled to nowhere (or the top), defeating the point of the anchor, and the inconsistent URLs make it ambiguous which is canonical. Agents resolving links will record a redirecting URL with a non-existent fragment.
The fix: Point both links at the canonical /api-reference (or a real, stable anchor on it) and standardize on one URL for the reference everywhere.
9. MPP credit-purchase limits are never stated, and the auth/credit story is split across pages (significant)
Problem: The MPP top-up flow says the amount "defaults to $5.00; pass amount_cents to choose a size (clamped to the credit-purchase limits)" — but the actual min/max limits are never stated anywhere. The payment-method wording is also inconsistent: the description says "payable via card/Link Shared Payment Token" while the 402 schema says "payable with a Stripe Shared Payment Token." And this top-up/key-minting flow is the de-facto credit/auth mechanism, yet it is not referenced from the Quickstart or any auth guidance, so how you get and fund an API key is split across unconnected pages.
Consequence: A developer (or an autonomous agent paying via MPP) cannot know whether a chosen amount_cents will be silently clamped, because the bounds are undocumented; they may also be unsure whether the credential is a Stripe token, a card, or Link. Someone starting at the Quickstart never learns MPP exists.
The fix: State the explicit min and max amount_cents limits, standardize the payment-method description between the prose and the 402 schema, and link the MPP flow from the Quickstart / a new Authentication page.
10. The enterprise platform — cross-linked everywhere as "custom models" docs — is a sales page (significant)
Location:/platform-enterprise/overview.md (linked from Quickstart, Recipes, SDK)
Problem: The Quickstart, Recipes, and SDK all cross-link to the Enterprise Platform for custom/fine-tuned models. The destination is a single high-level page describing Generate / Fine-tune / Evaluate / Serve as capabilities, with no API, no SDK methods, no dataset-format spec, and no self-serve instructions — the only call to action is a Calendly link ("Book a call →").
Consequence: A developer who follows an in-docs link expecting technical documentation for fine-tuning lands on a demo-booking page. There is nothing to copy, integrate, or evaluate against — the "documentation" cross-reference resolves to sales.
The fix: Either build real platform docs (dataset schema, fine-tune/evaluate/serve API or SDK calls, an example end-to-end) or relabel the cross-links so they clearly point to a "talk to us" page rather than implying technical reference material.
11. max_tokens is a footgun with no documented default (minor)
Location:/forecasting/recipes.md, /api-reference
Problem: Recipes warns: "avoid setting low max_tokens as this can result in the response being truncated during reasoning and no final prediction captured." But max_tokens is exposed as a standard body field with no documented default value, so a developer has no baseline for what "low" means or what the model needs to finish reasoning.
Consequence: A developer tuning max_tokens for cost has to discover by trial and error that they truncated the model mid-reasoning and silently lost the prediction — exactly the failure the note warns about — because no safe floor or default is given.
The fix: Document the default max_tokens and a recommended minimum that leaves room for the reasoning-plus-<answer> output.
12. SDK predict() default model and the n ensemble alternative are undocumented (minor)
Problem: The SDK minimal example passes model="foresight-v4", but predict()'s behavior when model is omitted (which model it defaults to) is undocumented. Separately, Recipes' "Use ensemble predictions" tells users to "send the same request multiple times and use the median response," without mentioning that the API already exposes n (number of choices) as a single-call alternative.
Consequence: Developers can't tell whether omitting model is safe or what version they'd silently get, and they implement client-side request fan-out for ensembling when one request with n may achieve the same thing more cheaply.
The fix: Document predict()'s default model (and pin/version guidance), and mention n as the built-in way to get multiple samples in one call.
13. "enteprise" typo in a cross-linked sentence (minor)
Location:/forecasting/recipes.md
Problem: The fine-tuning bullet reads "see our enteprise platform" — "enteprise" is misspelled.
Consequence: Low functional impact, but it sits directly on the link to the paid platform — the highest-intent CTA in the guide — where a typo is most visible.
The fix: Correct to "enterprise."
What they do well
The OpenAI-compatibility framing is clear and consistent in spirit — extensions (answer_type, research, reasoning_effort) are explained with concrete <answer> output shapes per type.
Clean .md source is published for most pages plus a /llms.txt index and a GitBook ?ask= query mechanism, so the docs are genuinely agent-readable in structure (even where the content disagrees with itself).
Recipes gives practical, opinionated guidance on question design (clear resolution criteria, thresholds, deadlines) that goes beyond bare API reference.
Top 3 recommendations
Collapse the base URL to one canonical value rendered from a single source across the OpenAPI servers block, the reference prose, the Quickstart, the SDK page, and the README (fixes the most damaging first-request failure).
Add the missing platform pages: Authentication, Errors/status codes, Rate limits, and Pricing — and document 401/403/429/5xx on every endpoint so production error handling is possible.
Make examples and schemas agree: fix google_news → google_search, reconcile answer_type casing (and document or drop CONTINUOUS_VALUE_ONLY), add the reasoning_effort enum, and flag top_k/min_p as extra_body params — then lint code samples against the live enums in CI.