NotHolyDocumentation
Open chat

Chat Completions

Text conversations and caller-executed function calls in OpenAI Chat format.

Updated 2026-10-30 · Contract 0.2.0
POST/v1/chat/completions

Request contract

Send 1–128 ordered system, user, assistant or tool messages. Use one of max_tokens or max_completion_tokens, never both. Each request is bounded by the configured model ceiling and shared serialized-input limits.

Function calls

Up to eight declared functions and bounded call results are supported. tool_choice can be auto, none, required or a named function. The caller executes returned functions; a function named shell never authorizes execution on NotHoly hosts.

Streaming

Set stream:true. Chunks preserve a stable ID and indexed tool-argument fragments. include_usage emits a final usage-only chunk. [DONE] appears only after successful completion; partial output may be followed by an error.

Response and limitations

Read choices[0].message and finish_reason. Content can be null for tool-only turns. Unknown fields, malformed tool cycles and unsupported sampling/structured-output controls fail before provider dispatch.

Request example

Use your own customer key. Confirm the model is published and your API wallet is funded. Copying an example never sends a request.

curl
curl https://notholy.com/v1/chat/completions \
  -H "Authorization: Bearer $NOTHOLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "notholy-pulse",
  "messages": [
    {
      "role": "user",
      "content": "Explain least privilege."
    }
  ],
  "max_tokens": 256
}'

HTTP contract fixture. Fixture checks are separate from production availability.

Request fields

Generated from the versioned contract. Refinement rules above still apply.

modelstringrequired

Up to 100 characters.

messagesarray<object | object | object>required

Up to 128 items. At least 1 item.

toolsarray<object>

Up to 8 items.

Show item fields
type"function"required

functionobjectrequired

Unknown fields rejected.

Show object fields
namestringrequired

descriptionstring

Default: "". Up to 1000 characters.

parametersobjectrequired

tool_choice"auto" | "none" | "required" | object

Show accepted variants
Variant 1"auto" | "none" | "required"

Variant 2object

Unknown fields rejected.

Show object fields
type"function"required

functionobjectrequired

Unknown fields rejected.

Show object fields
namestringrequired

max_tokensinteger

Minimum 32. Maximum 4096.

max_completion_tokensinteger

Minimum 32. Maximum 4096.

streamboolean

Default: false.

stream_optionsobject

Unknown fields rejected.

Show object fields
include_usagebooleanrequired

Response schema

idstringrequired

object"chat.completion"required

createdintegerrequired

Minimum -9007199254740991. Maximum 9007199254740991.

modelstringrequired

choicesarray<object>required

Up to 1 items. At least 1 item.

Show item fields
index0required

messageobjectrequired

Unknown fields rejected.

Show object fields
role"assistant"required

contentstring | nullrequired

tool_callsarray<object>

Show item fields
idstringrequired

type"function"required

functionobjectrequired

Unknown fields rejected.

finish_reason"stop" | "tool_calls" | "length"required

usageobjectrequired

Unknown fields rejected.

Show object fields
prompt_tokensinteger | nullrequired

Minimum -9007199254740991. Maximum 9007199254740991.

completion_tokensinteger | nullrequired

Minimum -9007199254740991. Maximum 9007199254740991.

total_tokensinteger | nullrequired

Minimum -9007199254740991. Maximum 9007199254740991.

prompt_tokens_detailsobject

Unknown fields rejected.

Show object fields
cached_tokensintegerrequired

Minimum 0. Maximum 9007199254740991.