Create a chat completion

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

curl https://api.boardwalk.cloud/v1/chat/completions \
  -H "Authorization: Bearer $BOARDWALK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "support-agent",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "max_completion_tokens": 256
}'

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 content. Text parts contain type and text.

Child fields

type"text"required

Content part type.

textstringrequired

Text of this part.

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. A limit that exceeds the model’s context after the prompt 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.

userstringoptional

Optional caller identifier.

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.

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.

schemaobjectoptional

JSON Schema for the response.

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.

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.