Create a text completion

Generate text from a prompt without applying a chat template.

POST /v1/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/completions \
  -H "Authorization: Bearer $BOARDWALK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "support-agent",
  "prompt": "The capital of France is",
  "max_tokens": 32
}'

Request body

modelstringrequired

Callable model ID or revision pin.

promptstring | string[]required

Text prompt or prompts.

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.

echobooleanoptional

Include the prompt in the returned text.

suffixstringoptional

Text following the completion, when supported.

Response

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

{
  "id": "cmpl_example",
  "object": "text_completion",
  "created": 1789516800,
  "model": "support-agent",
  "choices": [
    { "index": 0, "text": " Paris.", "finish_reason": "stop", "logprobs": null }
  ],
  "usage": { "prompt_tokens": 6, "completion_tokens": 2, "total_tokens": 8 }
}

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.

textstring

Generated text.

finish_reasonstring | null

Why generation ended.

logprobsobject | null

Token probabilities, when requested and supported.

usageobject

Engine token counts.

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

With stream: true, chunks contain incremental choices[].text. A successful stream includes final usage and ends with data: [DONE]. Closing the connection cancels the request.

Errors

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