> For the complete documentation index, see [llms.txt](https://docs.lightningrod.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lightningrod.ai/rest-api/lightningrod-api.md). # LightningRod API ## Chat Completions > OpenAI-compatible chat/completions endpoint for Lightning Rod's \*\*Foresight\*\* forecasting models. Point an OpenAI client at \`. Use \`extra\_body\` for Lightning Rod fields such as \`answer\_type\` and \`research\`. ```json {"openapi":"3.1.0","info":{"title":"LightningRod API","version":"1.0.0"},"servers":[{"url":"https://api.lightningrod.ai/api/public/v1/openai"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"ChatCompletionRequest":{"properties":{"model":{"type":"string","title":"Model","description":"ID of the model to use"},"messages":{"items":{"$ref":"#/components/schemas/ChatMessage"},"type":"array","title":"Messages","description":"A list of messages comprising the conversation so far"},"temperature":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Temperature","description":"Sampling temperature between 0 and 2","default":0.6},"max_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Tokens","description":"Maximum number of tokens to generate"},"top_p":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top P","description":"Nucleus sampling parameter"},"top_k":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top K","description":"Number of top tokens to consider"},"min_p":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min P","description":"Minimum probability for a token to be considered"},"reasoning_effort":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reasoning Effort","description":"OpenAI-compatible reasoning budget: `low`, `medium`, or `high`. Defaults to `medium`; `high` is accepted and treated as `medium`."},"stream":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Stream","description":"Whether to stream back partial progress","default":false},"n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N","description":"Number of chat completion choices to generate","default":1},"stop":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Stop","description":"Up to 4 sequences where the API will stop generating"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seed","description":"Deterministic sampling seed"},"research":{"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/ResearchOptions"},{"type":"null"}],"title":"Research","description":"Opt-in web research before forecasting. Pass `true` for default sources, or a `ResearchOptions` object to select sources."},"answer_type":{"anyOf":[{"$ref":"#/components/schemas/AnswerTypeEnum"},{"type":"string","const":"auto"},{"type":"null"}],"title":"Answer Type","description":"Structured answer format. One of `binary`, `multiple_choice`, `continuous`, `free_response`, or `auto`. When set, the response content includes a machine-readable answer in `` tags."}},"type":"object","required":["model","messages"],"title":"ChatCompletionRequest"},"ChatMessage":{"properties":{"role":{"type":"string","title":"Role","description":"The role of the message author (system, user, or assistant)"},"content":{"type":"string","title":"Content","description":"The content of the message"}},"type":"object","required":["role","content"],"title":"ChatMessage"},"ResearchOptions":{"properties":{"sources":{"items":{"type":"string","enum":["perplexity","google_news","google_search"]},"type":"array","title":"Sources","description":"Which research providers to query in parallel: `perplexity` (Perplexity web search), `google_news` (recent news articles), `google_search` (Google web results). Each provider is billed as a separate RESEARCH event."}},"type":"object","title":"ResearchOptions","description":"Opt-in research enrichment for forecasting requests.\n\nWhen set, the API fetches web-grounded context from the requested sources\nand injects it into the prompt before calling the model. Each successful\nsource produces a billable RESEARCH event."},"AnswerTypeEnum":{"type":"string","enum":["BINARY","MULTIPLE_CHOICE","CONTINUOUS","CONTINUOUS_VALUE_ONLY","FREE_RESPONSE"],"title":"AnswerTypeEnum"},"ChatCompletionResponse":{"properties":{"id":{"type":"string","title":"Id","description":"A unique identifier for the chat completion"},"object":{"type":"string","const":"chat.completion","title":"Object","description":"The object type","default":"chat.completion"},"created":{"type":"integer","title":"Created","description":"Unix timestamp of when the completion was created"},"model":{"type":"string","title":"Model","description":"The model used for the chat completion"},"choices":{"items":{"$ref":"#/components/schemas/Choice"},"type":"array","title":"Choices","description":"A list of chat completion choices"},"usage":{"anyOf":[{"$ref":"#/components/schemas/Usage"},{"type":"null"}],"description":"Usage statistics for the completion request"}},"type":"object","required":["id","created","model","choices"],"title":"ChatCompletionResponse"},"Choice":{"properties":{"index":{"type":"integer","title":"Index","description":"The index of this choice"},"message":{"$ref":"#/components/schemas/ResponseMessage","description":"The message generated by the model"},"finish_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finish Reason","description":"The reason the model stopped generating tokens"}},"type":"object","required":["index","message"],"title":"Choice"},"ResponseMessage":{"properties":{"role":{"type":"string","title":"Role","description":"The role of the message author"},"content":{"type":"string","title":"Content","description":"The model's full response. When `answer_type` was set on the request, a machine-readable answer is embedded between `` tags at the end (e.g. `0.62` for a binary probability). See the request's `answer_type` field for the per-type shapes."},"thinking":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thinking","description":"The model's reasoning/thinking chain, when returned by the model."},"annotations":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/UrlCitationAnnotation"}},{"type":"null"}],"title":"Annotations","description":"Source citations from web research, present only when `research` ran. Each entry is a `url_citation` referencing a source the model used."}},"type":"object","required":["role","content"],"title":"ResponseMessage"},"UrlCitationAnnotation":{"properties":{"type":{"type":"string","const":"url_citation","title":"Type","description":"The annotation type. Always `url_citation`.","default":"url_citation"},"url_citation":{"$ref":"#/components/schemas/UrlCitation","description":"The cited source."}},"type":"object","required":["type","url_citation"],"title":"UrlCitationAnnotation"},"UrlCitation":{"properties":{"url":{"type":"string","title":"Url","description":"URL of the cited source."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Title of the cited source, when available."}},"type":"object","required":["url"],"title":"UrlCitation"},"Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","description":"Number of tokens in the prompt"},"completion_tokens":{"type":"integer","title":"Completion Tokens","description":"Number of tokens in the completion"},"total_tokens":{"type":"integer","title":"Total Tokens","description":"Total number of tokens used"},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Lightning Rod total cost of the call in USD, summing inference and any research/classification costs."},"inference_cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Inference Cost Usd","description":"Lightning Rod cost in USD attributable to model inference."},"research_cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Research Cost Usd","description":"Lightning Rod cost in USD for web research, when `research` was enabled. Each source is billed as a separate RESEARCH event."},"classification_cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Classification Cost Usd","description":"Lightning Rod cost in USD for question classification, when `answer_type` was `auto`."}},"type":"object","required":["prompt_tokens","completion_tokens","total_tokens"],"title":"Usage","description":"Token counts plus Lightning Rod cost fields. The `*_cost_usd` fields are present when applicable (research and classification costs only appear when those steps ran)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/chat/completions":{"post":{"summary":"Chat Completions","description":"OpenAI-compatible chat/completions endpoint for Lightning Rod's **Foresight** forecasting models. Point an OpenAI client at `https://api.lightningrod.ai/api/public/v1/openai`. Use `extra_body` for Lightning Rod fields such as `answer_type` and `research`.","operationId":"chat_completions_openai_chat_completions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## List Models > List available models. ```json {"openapi":"3.1.0","info":{"title":"LightningRod API","version":"1.0.0"},"servers":[{"url":"https://api.lightningrod.ai/api/public/v1/openai"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"ModelListResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"The object type","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ModelObject"},"type":"array","title":"Data","description":"A list of model objects"}},"type":"object","required":["data"],"title":"ModelListResponse"},"ModelObject":{"properties":{"id":{"type":"string","title":"Id","description":"The model identifier"},"object":{"type":"string","const":"model","title":"Object","description":"The object type","default":"model"},"created":{"type":"integer","title":"Created","description":"Unix timestamp of when the model was created","default":0},"owned_by":{"type":"string","title":"Owned By","description":"The organization that owns the model","default":"lightningrodlabs"},"name":{"type":"string","title":"Name","description":"Display name of the model","default":""},"description":{"type":"string","title":"Description","description":"Description of the model","default":""},"context_length":{"type":"integer","title":"Context Length","description":"Maximum context length in tokens","default":0},"max_completion_tokens":{"type":"integer","title":"Max Completion Tokens","description":"Maximum number of tokens to generate","default":0},"pricing":{"additionalProperties":true,"type":"object","title":"Pricing","description":"Per-token pricing"}},"type":"object","required":["id"],"title":"ModelObject"}}},"paths":{"/models":{"get":{"summary":"List Models","description":"List available models.","operationId":"list_models_openai_models_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelListResponse"}}}}}}}}} ``` ## Completions > OpenAI-compatible text completion endpoint for Lightning Rod's \*\*Foresight\*\* forecasting models. Prefer chat/completions for new integrations. Use \`extra\_body\` for Lightning Rod fields such as \`answer\_type\` and \`research\`. ```json {"openapi":"3.1.0","info":{"title":"LightningRod API","version":"1.0.0"},"servers":[{"url":"https://api.lightningrod.ai/api/public/v1/openai"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CompletionRequest":{"properties":{"model":{"type":"string","title":"Model","description":"ID of the model to use"},"prompt":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}],"title":"Prompt","description":"The prompt(s) to generate completions for"},"temperature":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Temperature","description":"Sampling temperature between 0 and 2","default":0.6},"max_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Tokens","description":"Maximum number of tokens to generate"},"top_p":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top P","description":"Nucleus sampling parameter"},"top_k":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top K","description":"Number of top tokens to consider"},"min_p":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min P","description":"Minimum probability for a token to be considered"},"reasoning_effort":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reasoning Effort","description":"OpenAI-compatible reasoning budget: `low`, `medium`, or `high`. Defaults to `medium`; `high` is accepted and treated as `medium`."},"stream":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Stream","description":"Whether to stream back partial progress","default":false},"n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N","description":"Number of completions to generate","default":1},"stop":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Stop","description":"Up to 4 sequences where the API will stop generating"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seed","description":"Deterministic sampling seed"},"research":{"anyOf":[{"type":"boolean"},{"$ref":"#/components/schemas/ResearchOptions"},{"type":"null"}],"title":"Research","description":"Opt-in web research before forecasting. Pass `true` for default sources, or a `ResearchOptions` object to select sources."},"answer_type":{"anyOf":[{"$ref":"#/components/schemas/AnswerTypeEnum"},{"type":"string","const":"auto"},{"type":"null"}],"title":"Answer Type","description":"Structured answer format. One of `binary`, `multiple_choice`, `continuous`, `free_response`, or `auto`. When set, the response text includes a machine-readable answer in `` tags."}},"type":"object","required":["model","prompt"],"title":"CompletionRequest"},"ResearchOptions":{"properties":{"sources":{"items":{"type":"string","enum":["perplexity","google_news","google_search"]},"type":"array","title":"Sources","description":"Which research providers to query in parallel: `perplexity` (Perplexity web search), `google_news` (recent news articles), `google_search` (Google web results). Each provider is billed as a separate RESEARCH event."}},"type":"object","title":"ResearchOptions","description":"Opt-in research enrichment for forecasting requests.\n\nWhen set, the API fetches web-grounded context from the requested sources\nand injects it into the prompt before calling the model. Each successful\nsource produces a billable RESEARCH event."},"AnswerTypeEnum":{"type":"string","enum":["BINARY","MULTIPLE_CHOICE","CONTINUOUS","CONTINUOUS_VALUE_ONLY","FREE_RESPONSE"],"title":"AnswerTypeEnum"},"CompletionResponse":{"properties":{"id":{"type":"string","title":"Id","description":"A unique identifier for the completion"},"object":{"type":"string","const":"text_completion","title":"Object","description":"The object type","default":"text_completion"},"created":{"type":"integer","title":"Created","description":"Unix timestamp of when the completion was created"},"model":{"type":"string","title":"Model","description":"The model used for the completion"},"choices":{"items":{"$ref":"#/components/schemas/CompletionChoice"},"type":"array","title":"Choices","description":"A list of completion choices"},"usage":{"anyOf":[{"$ref":"#/components/schemas/Usage"},{"type":"null"}],"description":"Usage statistics for the completion request"}},"type":"object","required":["id","created","model","choices"],"title":"CompletionResponse"},"CompletionChoice":{"properties":{"index":{"type":"integer","title":"Index","description":"The index of this choice"},"text":{"type":"string","title":"Text","description":"The generated text"},"finish_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finish Reason","description":"The reason the model stopped generating tokens"}},"type":"object","required":["index","text"],"title":"CompletionChoice"},"Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","description":"Number of tokens in the prompt"},"completion_tokens":{"type":"integer","title":"Completion Tokens","description":"Number of tokens in the completion"},"total_tokens":{"type":"integer","title":"Total Tokens","description":"Total number of tokens used"},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Lightning Rod total cost of the call in USD, summing inference and any research/classification costs."},"inference_cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Inference Cost Usd","description":"Lightning Rod cost in USD attributable to model inference."},"research_cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Research Cost Usd","description":"Lightning Rod cost in USD for web research, when `research` was enabled. Each source is billed as a separate RESEARCH event."},"classification_cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Classification Cost Usd","description":"Lightning Rod cost in USD for question classification, when `answer_type` was `auto`."}},"type":"object","required":["prompt_tokens","completion_tokens","total_tokens"],"title":"Usage","description":"Token counts plus Lightning Rod cost fields. The `*_cost_usd` fields are present when applicable (research and classification costs only appear when those steps ran)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/completions":{"post":{"summary":"Completions","description":"OpenAI-compatible text completion endpoint for Lightning Rod's **Foresight** forecasting models. Prefer chat/completions for new integrations. Use `extra_body` for Lightning Rod fields such as `answer_type` and `research`.","operationId":"completions_openai_completions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.lightningrod.ai/rest-api/lightningrod-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.