Skip to main content

Chat

OpenAI-compatible chat completions. Reference for API version 2026-11-11.

On this page
CurrentDownload OpenAPI (JSON)Versioning

Create a chat completion

POST /api/v1/llm/v1/chat/completions

OpenAI-compatible chat completions with tool calling, structured output and streaming. Every request is routed to a Nebula model; vendor model ids and retired Nebula ids resolve to nebula-4.5. Requires the llm:access or llm:chat scope. A credit check runs before the model is called (402 when the organization has no spendable credit or its spend cap is reached).

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Headers

  • Idempotency-Key string

    Run this exact request at most once in 24 hours. A replay with the same key and the same body, from the same organization, user and API key, is refused with 409 before any model call. See the Idempotency guide.

    Minimum length
    1
  • X-Request-ID string

    Optional correlation id. Echoed in the X-Request-ID response header and in error bodies.

Request body

application/json Required

  • model string

    nebula-4.5 (text, smart-routed) or nebula-v (vision). Unknown and retired ids resolve to nebula-4.5.

    Default
    nebula-4.5
  • messages array of objects Required
    5 fields in messages
    • role string Required
      One of
      system user assistant tool
    • content string or array of objects or null

      Text, or an array of content parts (text, and image_url for nebula-v).

    • name string or null
    • tool_calls array of objects or null
      3 fields in tool_calls
      • id string
      • type string
        Always
        function
      • function object
        2 fields in function
        • name string
        • arguments string

          JSON-encoded arguments.

    • tool_call_id string or null

      For role: tool, the id of the call being answered.

  • max_tokens integer or null

    Output-token ceiling. An explicit value is clamped to the platform maximum.

    Minimum
    1
  • max_completion_tokens integer or null

    Alias of max_tokens; when both are sent, the smaller wins.

    Minimum
    1
  • temperature number or null
    Default
    0.7
    Minimum
    0
    Maximum
    2
  • top_p number or null
    Default
    1
    Minimum
    0
    Maximum
    1
  • stream boolean or null
    Default
    false
  • stop string or array of strings or null
  • tools array of objects or null

    OpenAI-format function tool definitions.

  • tool_choice string or object or null

    auto, none, required, or { "type": "function", "function": { "name": … } }.

  • parallel_tool_calls boolean or null
  • response_format object or null

    { "type": "json_object" } or { "type": "json_schema", "json_schema": { … } }.

  • reasoning_effort string or null

    Requested reasoning depth. Omit it for adaptive routing.

    One of
    none low medium high max xhigh ultra null
  • user string or null

    A stable session or end-user id. Send the same value on every turn of a conversation so prompt caching can reuse earlier context.

Responses

  • 200 A chat.completion object, or with stream: true a text/event-stream of chat.completion.chunk events ending with data: [DONE]. Errors after the stream opens arrive in-band as a StreamError event.

    application/jsontext/event-stream

    Headers

    • X-Request-ID string

      The request's correlation id (yours, or one BreachLine generated). Quote it to support.

    Body (application/json)

    • id string
    • object string
      Always
      chat.completion
    • created integer
    • model string
      Examples
      nebula-4.5
    • choices array of objects
      3 fields in choices
      • index integer
      • message object
        5 fields in message
        • role string Required
          One of
          system user assistant tool
        • content string or array of objects or null

          Text, or an array of content parts (text, and image_url for nebula-v).

        • name string or null
        • tool_calls array of objects or null
          3 fields in tool_calls
          • id string
          • type string
            Always
            function
          • function object
            2 fields in function
            • name string
            • arguments string

              JSON-encoded arguments.

        • tool_call_id string or null

          For role: tool, the id of the call being answered.

      • finish_reason string
        Examples
        stop length tool_calls
    • usage object
      3 fields in usage
      • prompt_tokens integer
      • completion_tokens integer
      • total_tokens integer
  • 400 The request was malformed or failed a server-side check.Error envelope
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 402 The organization has no spendable credit, or its self-service spend cap is reached. Top up or raise the cap in the console. This status currently carries message: "Error" and code: "INTERNAL_9001"; rely on the HTTP status.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 409 This exact request (same Idempotency-Key and body) already ran, so it was not run again. Send a new Idempotency-Key to run it again.Error envelope
  • 422 The request body or parameters failed schema validation.Error envelope
  • 429 A per-key request limit was exceeded, or the rate limiter could not be reached (it fails closed). There is no Retry-After for a window limit; wait for the next window. A concurrency limit, when configured, also returns 429, with Retry-After.Error envelope
  • 503 A dependency is temporarily unavailable, or a non-streaming completion finished without an answer. Retry with backoff and honour Retry-After when present. The empty-completion case uses an OpenAI-style error object without status or request_id.

    application/json

    Headers

    • X-Request-ID string

      The request's correlation id (yours, or one BreachLine generated). Quote it to support.

    • Retry-After integer

      Seconds to wait before retrying.

    Body (application/json)

Example

cURL
curl -X POST "https://api.breachline.io/api/v1/llm/v1/chat/completions" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nebula-4.5",
    "messages": [
      {
        "role": "system",
        "content": "You are a concise security assistant."
      },
      {
        "role": "user",
        "content": "Explain what a reflected XSS finding means for a login page."
      }
    ]
  }'
Example 200 response
{
  "id": "string",
  "object": "chat.completion",
  "created": 0,
  "model": "nebula-4.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "system",
        "content": "string",
        "name": "string",
        "tool_calls": [
          {
            "id": null,
            "type": null,
            "function": null
          }
        ],
        "tool_call_id": "string"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

Search documentation

Type to search guides, the API reference, the CLI and the console guide.

    Enter open↑ ↓ moveEsc close