OpenAI Chat Completions API

Generate a response from a public model or your private deployment.

POST /v1/chat/completions

Authorization

Authorizationheader · string: Bearer $BOARDWALK_API_KEY. Requires inference:write and sufficient credits.

Content-Typeheader · stringrequired: application/json

Request

Install: pip install openai or npm install openai. Replace your-api-key with your app’s server-side key and support-agent with your model name.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.boardwalk.cloud/v1",
    api_key="your-api-key",
)

response = client.chat.completions.create(
    model="support-agent",
    messages=[{"role": "user", "content": "Say hello in five words."}],
    max_completion_tokens=1024,
)
print(response.choices[0].message.content)
print(response.usage)

Request body

modelstringrequired

Callable model ID or a supported revision pin.

messagesobject[]required

Conversation messages. At least one message is required.

Child fields

rolestringrequired

One of system, developer, user, assistant, or tool.

contentstring | object[] | nulloptional

Text or ordered content parts. Qualified vision models accept image_url parts and audio models input_audio parts in user messages; other roles accept text only.

Child fields

type"text" | "image_url" | "input_audio"required: Content part type.
textstring: Required on text parts.
image_urlobject: Required on image_url parts: {url: "https://… or data:image/png;base64,…", detail?: "auto"}. JPEG data URLs use image/jpeg. Inference bodies are limited to 32 MiB.
input_audioobject: Required on input_audio parts: {data: "<base64>", format: "wav" | "mp3" | "flac"}. At most four clips, each 10 MiB and 30 seconds; longer audio goes to /v1/audio/transcriptions.

namestringoptional

Name of the message author.

tool_callsobject[]optional

Calls returned in an assistant message.

Child fields

idstringrequired

Identifier of the tool call.

type"function"required

Tool type.

functionobjectrequired

Function invocation.

Child fields

namestringrequired: Function name.
argumentsstringrequired: JSON-encoded function arguments.

tool_call_idstringoptional

Call answered by a tool message.

reasoningstring | nulloptional

Reasoning from a previous assistant turn, when required by the model.

reasoning_contentstring | nulloptional

Legacy alias for reasoning. Accepted only on assistant messages.

streambooleanoptional

Return server-sent events instead of a single JSON response.

stream_optionsobjectoptional

Streaming options.

Child fields

include_usagebooleanoptional: Boardwalk includes final usage in successful streams even when this is omitted or false.

max_tokensintegeroptional

Positive output-token limit, which must leave room for the prompt within the model’s context: a limit at or above the context is rejected. If omitted, the remaining context is available for output, including reasoning.

temperaturenumberoptional

Sampling temperature from 0 to 2.

top_pnumberoptional

Nucleus sampling threshold, greater than 0 and at most 1.

nintegeroptional

Number of choices. Only 1 is supported.

stopstring | string[]optional

Stop sequence or up to four stop sequences.

presence_penaltynumberoptional

Presence penalty from −2 to 2.

frequency_penaltynumberoptional

Frequency penalty from −2 to 2.

seedintegeroptional

Sampling seed. Identical output is not guaranteed.

logprobsbooleanoptional

Include output-token log probabilities when supported.

top_logprobsintegeroptional

Number of alternative token probabilities, from 0 to 20.

logit_biasobjectoptional

Map of token IDs to numeric sampling biases.

prompt_cache_keystringoptional

Names a conversation, up to 256 characters. Routing prefers a compatible cached conversation; a cache hit is not guaranteed. Scoped to your organization.

max_completion_tokensintegeroptional

Positive output-token limit, including reasoning. Takes precedence over max_tokens when both are supplied.

toolsobject[]optional

Function tools on configurations with verified tool support.

Child fields

type"function"required

Tool type.

functionobjectrequired

Function definition.

Child fields

namestringrequired: Function name.
descriptionstringoptional: What the function does.
parametersobjectoptional: JSON Schema for its arguments.
strictbooleanoptional: Request strict schema adherence when supported.

tool_choicestring | objectoptional

none, auto, required, or a named function.

Child fields

type"function"required

Type for a named tool choice.

functionobjectrequired

Selected function.

Child fields

namestringrequired: Name of a supplied function.

parallel_tool_callsbooleanoptional

Allow parallel function calls on supported configurations.

reasoning_effort"none" | null

Disables thinking only when reasoning_controls.thinking_toggle is true. Other effort levels are rejected.

reasoningobject

Compatibility controls: enabled toggles thinking where supported; effort follows reasoning_effort; exclude hides reasoning text without reducing billed tokens. Conflicting controls are rejected.

include_reasoningboolean

Set false to hide reasoning output. Does not disable thinking or reduce billed tokens. Conflicts with reasoning.exclude are rejected.

chat_template_kwargsobject

Engine extension: {enable_thinking: true|false}. Requires thinking_toggle; unknown fields and conflicting reasoning_effort are rejected.

response_formatobjectoptional

Output format on supported configurations.

Child fields

typestringrequired

text, json_object, or json_schema.

json_schemaobjectoptional

Required when type is json_schema.

Child fields

namestringrequired: Schema name.
descriptionstring: Description of the output schema.
schemaobjectrequired: Bounded object-root JSON Schema. See the structured-output guide for supported keywords and limits.
strictbooleanoptional: Request strict schema adherence.

Response

Example response. IDs, token counts, and rates are illustrative.

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1789516800,
  "model": "support-agent",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help?" },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20 }
}

idstring

Completion identifier from the serving engine. Use x-request-id for Boardwalk receipts and support.

objectstring

Response object type.

createdinteger

Creation time in Unix seconds.

modelstring

Model name reported by the serving engine.

choicesobject[]

Generated choices.

Child fields

indexinteger

Choice index.

messageobject

Generated assistant message.

Child fields

role"assistant"

Message role.

contentstring | null

Generated text.

tool_callsobject[]

Function calls, when generated.

Child fields

idstringrequired

Identifier of the tool call.

type"function"required

Tool type.

functionobjectrequired

Function invocation.

Child fields

namestringrequired: Function name.
argumentsstringrequired: JSON-encoded function arguments.

reasoningstring | null

Reasoning text, when reported by the engine.

reasoning_contentstring | null

Engine-dependent alias for reasoning text.

finish_reasonstring | null

Why generation ended, such as stop, length, or tool_calls.

logprobsobject | null

Token probabilities, when requested and supported.

usageobject

Engine token counts. Use the receipt for billable categories and cost.

Child fields

prompt_tokensinteger

Total prompt tokens, including cached input.

completion_tokensinteger

Generated tokens, including reasoning.

total_tokensinteger

Sum of prompt and completion tokens, when reported.

prompt_tokens_detailsobject | null

Cache counts, when reported by the engine.

Child fields

cached_tokensinteger | null: Prompt tokens read from cache.
created_cache_tokensinteger | null: Prompt tokens written to cache.

See image inputs and structured output, tools, and reasoning controls for examples and limits.

Streaming

Set stream: true to receive text/event-stream. Each chunk uses choices[].delta for incremental message fields. A successful stream ends with a usage-only chunk and [DONE].

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1789516800,"model":"support-agent","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello!"},"finish_reason":null}]}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1789516800,"model":"support-agent","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1789516800,"model":"support-agent","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":3,"total_tokens":15}}

data: [DONE]

Closing the connection cancels generation. Interrupted streams may lack final usage; retrieve the receipt using x-request-id. Retrying starts a new request.

Errors

Errors use the shared error format. Save the x-request-id response header for receipts and support.