OpenAI-Compatible Endpoint

Direct access to the underlying LLM via an OpenAI-compatible endpoint (/v1/chat/completions, streaming supported), backed by SearchAI Native Inference (or whichever provider is console-active) for client-side and MCP tool-calling integrations.

URL

https://localhost:8443/rest/v2/api/ai/openai/v1/chat/completions

Note: localhost:8443 is just the local reference config. Replace it with your own console/server domain (e.g. https://your-searchblox-server.com).

Method
POST

Media Type
application/json

Headers

Header	Required	Required
Content-Type	Yes	application/json
SB-PKEY	Yes	Your SearchBlox user private key

Request Fields

Field	Description	Type	Required
messages	Conversation history (system / user / assistant / tool roles).	array	Yes
model	Model id to use. Omit to use the console-active model. Available on the SearchBlox server: q35-4b, gemma-4-E4B-it, qwen38-27b.	string	No
stream	Return Server-Sent Events instead of a single JSON body.	boolean	No
tools	OpenAI-style function tools. Client-executed - the endpoint returns tool_calls and your client runs them, replying as role:"tool".	array	No
searchblox_tools	Names of built-in SearchBlox tools (search, collections, KG). Server-executed - the endpoint runs the tool call itself and returns only the final answer.	string[]	No
mcp_servers	MCP servers to expose to the model. Also server-executed.	array	No

Response Codes

Code	Description
200	Success - completion returned (or SSE stream started).
401	Missing or invalid SB-PKEY / Authorization.
400	Malformed request body.
413 / context_length_exceeded	Prompt + tool definitions exceed the active model's max context

Example 1 - Gibberish Classifier

Request:

curl -sk -X POST 
"https://localhost:8443/rest/v2/api/ai/openai/v1/chat/completions" \
  -H "Content-Type: application/json" -H "SB-PKEY: YOUR_PKEY" \
  -d '{
    "model": "q35-4b",
    "messages": [
      { "role": "system", "content": "You are a text classifier that determines   whether a given input is gibberish or meaningful text. Respond with ONLY a JSON object in the form {\"gibberish\":\"yes\"} or {\"gibberish\":\"no\"} — no explanation." },
      { "role": "user", "content": "dsfgds dsdfgdd" }
    ]
  }'

Response:

{
  "choices": [
    { "message": { "role": "assistant", "content": "{\"gibberish\":\"yes\"}" } }
  ]
}

Example 2 - Tool calling

Mode A (client-executed)

Supply OpenAI tools; the endpoint returns tool_calls. Your client runs the tool and replays results as role:"tool" messages.

Request:

curl -sk -X POST 
"https://localhost:8443/rest/v2/api/ai/openai/v1/chat/completions" \
  -H "Content-Type: application/json" -H "SB-PKEY: YOUR_PKEY" \
  -d '{"messages":[{"role":"user","content":"Weather in Paris?"}],
       "tools":[{"type":"function","function":{"name":"get_weather",
         "parameters":{"type":"object","properties":{"city":{"type":"string"}}}}}]}'
# → response.choices[0].message.tool_calls[...]

Response - the model asks to call the tool instead of answering directly:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_1",
            "type": "function",
            "function": { "name": "get_weather", "arguments": "{\"city\":\"Paris\"}" }
          }
        ]
      }
    }
  ]
}

Your client runs get_weather("Paris"), then sends the result back as a role:"tool" message on the same conversation to get the final answer:

curl -sk -X POST 
"https://localhost:8443/rest/v2/api/ai/openai/v1/chat/completions" \
  -H "Content-Type: application/json" -H "SB-PKEY: YOUR_PKEY" \
  -d '{"messages":[
        {"role":"user","content":"Weather in Paris?"},
        {"role":"assistant","tool_calls":[
          {"id":"call_1","type":"function",
           "function":{"name":"get_weather","arguments":"{\"city\":\"Paris\"}"}}
        ]},
        {"role":"tool","tool_call_id":"call_1",
         "content":"{\"temperature\":\"15°C\",\"condition\":\"Cloudy\"}"}
      ],
      "tools":[{"type":"function","function":{"name":"get_weather",
        "parameters":{"type":"object","properties":{"city":{"type":"string"}}}}}]}'

Final response - the model now answers using the tool result you supplied:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "It's currently 15°C and cloudy in Paris."
      }
    }
  ]
}

Mode B (server-executed / agentic)

Pass searchblox_tools and/or mcp_servers; the endpoint runs the full agentic loop server-side (via McpToolBridge) and returns only the final answer. This is the way to give a model SearchBlox search/collection/KG tools without wiring an agent.

Request:

curl -sk -X POST 
"https://localhost:8443/rest/v2/api/ai/openai/v1/chat/completions" \
  -H "Content-Type: application/json" -H "SB-PKEY: YOUR_PKEY" \
  -d '{"messages":[{"role":"user","content":"Find vitamin c serums under $30 in ulta_1000."}],
       "searchblox_tools":["searchblox_search"]}'

Response - the tool already ran server-side, so you get the final answer directly, with no tool_calls to handle:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Here are a few vitamin C serums under $30 in ulta_1000: ... [1][2]"
      }
    }
  ]
}