Skip to main content

Create a chat completion

POST /projects/:projectid/chat/completions

Generates a response from a supplied conversation. It can return text, structured JSON, or function-tool requests for your application to handle.

Authentication​

Send a project key in Authorization, without Bearer. It needs llm.complete on the requested small, medium, or large tier, or on all tiers.

Replace :projectid with the key's project ID and send Content-Type: application/json.

Request fields​

FieldTypeRequiredBehaviour
modelStringYessmall, medium, or large. There is no default tier for this endpoint.
messagesArrayYesNon-empty conversation history. Each message has a role; supply appropriate content or tool-call fields.
streamBooleanNoDefaults to false. Set true for server-sent events.
max_tokensIntegerNoGenerated-token budget, from 1 to 32,768. Defaults to 16,000 for small and 32,000 for medium/large. This is not the input context limit.
temperatureNumberNoFrom 0 to 2. Omit to use the tier's default behaviour.
reasoning_effortStringNonone, low, medium, or high. Defaults to none for small and medium for medium/large.
toolsArrayNoUp to 128 function-tool definitions, described below.
tool_choiceString or objectNonone, auto, required, or a named function selection. Requires a non-empty tools array.
response_formatObjectNoText, JSON-object, or JSON-schema output, described below.

Reasoning uses part of the generation budget. Allow room for the final answer as well as reasoning, and inspect the finish reason for truncation. The effect of reasoning and sampling controls can vary with the tier and project model policy.

For ordinary conversations, use system for instructions, user for user messages, and assistant for previous responses. Tool results use tool with a matching tool_call_id. Send the relevant history on each request; the endpoint does not retain a conversation for you.

Basic example​

Using the Quickstart environment variables:

curl --include --request POST \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
--header "Content-Type: application/json" \
--data '{"model":"medium","messages":[{"role":"user","content":"Explain what a webhook does in two sentences."}],"max_tokens":2048}' \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/chat/completions"

An illustrative 200 OK response:

{
"id": "chatcmpl-example",
"object": "chat.completion",
"created": 1793354400,
"model": "medium",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "A webhook sends an HTTP request when an event happens. It lets another application react without repeatedly checking for changes."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 24,
"completion_tokens": 38,
"total_tokens": 62
}
}

Text is in choices[0].message.content. IDs, content, and token counts vary; additional fields may be present. A length finish reason means the generation reached its limit, so the content may be incomplete. A tool_calls finish reason requires handling the requested functions rather than treating the message as a final answer.

Function tools​

Describe the functions your application is prepared to offer. This is a complete example request body:

{
"model": "medium",
"messages": [
{"role": "user", "content": "What is the status of order A123?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Read the current status of one order.",
"parameters": {
"type": "object",
"properties": {"orderId": {"type": "string"}},
"required": ["orderId"],
"additionalProperties": false
}
}
}
],
"tool_choice": "auto"
}

tool_choice can be:

  • "auto": let the model decide whether to request tools.
  • "none": do not request a tool.
  • "required": require a tool request.
  • {"type":"function","function":{"name":"get_order_status"}}: request one named tool from the supplied definitions.

A response may contain message.tool_calls instead of useful answer text. Each call has an ID, a function name, and function.arguments as a JSON string.

Your application owns the tool loop:

  1. Parse and validate the arguments against your schema.
  2. Check the user's authorisation and any required approval before executing the function.
  3. Append the returned assistant message, including its tool calls, to the conversation.
  4. Append a tool message for each result, using the corresponding tool_call_id.
  5. Send the expanded conversation for the next response.

For example, the continuation's messages could include:

[
{"role":"user","content":"What is the status of order A123?"},
{
"role":"assistant",
"content":null,
"tool_calls":[
{
"id":"call_example",
"type":"function",
"function":{"name":"get_order_status","arguments":"{\"orderId\":\"A123\"}"}
}
]
},
{"role":"tool","tool_call_id":"call_example","content":"{\"status\":\"shipped\"}"}
]

The API does not execute these functions for you. Treat model-generated arguments as untrusted input, and bound the number of tool rounds.

Structured output​

Set response_format to {"type":"json_object"} to request a JSON object, and instruct the model what it should contain. The default is {"type":"text"}.

For a defined structure, use a JSON schema:

{
"model": "medium",
"messages": [
{"role":"user","content":"Classify this message: My order arrived damaged."}
],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "message_category",
"schema": {
"type": "object",
"properties": {
"category": {"type":"string","enum":["delivery","billing","other"]}
},
"required": ["category"],
"additionalProperties": false
}
}
}
}

The schema name must be 1–64 letters, digits, underscores, or hyphens. json_schema.strict is also accepted as an optional boolean; still validate the result in your application.

The generated JSON is returned as a string in message.content, not as an already-parsed object. Check the finish reason, parse the string, and validate it before using it. An unsupported schema or an interrupted generation can fail or leave incomplete output.

Streaming and errors​

Set stream: true to receive chunks instead of a single JSON response. See Streaming responses for text, tool fragments, and failure handling.

  • 400: unknown tier or invalid request fields. The JSON body uses error: "BAD_REQUEST" and an explanatory message.
  • 401: missing or invalid project credential.
  • 403: the key cannot use the requested tier.
  • 429: a project, key, or AI request-rate limit was reached.
  • 502: generation could not start or complete. The body may identify UPSTREAM_UNAVAILABLE or UPSTREAM_FAILURE.

Once streaming has started, failures can arrive as SSE error events rather than a new HTTP status. See Errors, limits and retries.