Chat completions

Full reference for the POST /v1/chat/completions endpoint — request parameters, response format, streaming, and tool calling.

The Chat Completions endpoint generates model responses from a conversation. It follows the OpenAI Chat Completions format, so any library or tool that works with OpenAI also works with the Cline API.

Endpoint

POST https://api.cline.bot/api/v1/chat/completions

Request headers

Authorization · string · required

Bearer token for authentication. Format: Bearer YOUR_API_KEY.

Content-Type · string · required

Must be application/json.

HTTP-Referer · string

Your application’s URL. Used for usage tracking in logs.

X-Title · string

Your application’s name. Appears in usage logs.

Request body

model · string · required

Model ID in provider/model-name format. For example: anthropic/claude-sonnet-4-6, openai/gpt-4o, google/gemini-2.5-pro. See Models for available options.

messages · object[] · required

Array of conversation messages. Each message has a role and content.

Show Message object

role · string · required

One of system, user, or assistant. Use tool when returning a tool result.

content · string | object[] · required

The message text, or an array of content parts for multimodal messages (text + images).

stream · boolean · default: "true"

When true, the response is delivered as a stream of Server-Sent Events. When false, a single JSON object is returned after the model finishes generating.

tools · object[]

Tool definitions in OpenAI function-calling format. When provided, the model may respond with a tool_calls array instead of a text reply.

Show Tool object

type · string · required

Must be "function".

function · object · required

Show properties

name · string · required

The function name.

description · string

What the function does. The model uses this to decide when to call it.

parameters · object

JSON Schema describing the function’s parameters.

temperature · number · default: "Model default"

Sampling temperature between 0.0 and 2.0. Lower values produce more deterministic output; higher values produce more varied output.

Message roles

Role	Purpose
system	Sets the model’s behavior and persona. Place first in the array.
user	The human’s input.
assistant	Previous model responses, used to maintain conversation context.
tool	The result of a tool call, returned after the model calls a function.

Streaming response

When stream: true (the default), the response is a series of Server-Sent Events. Each line starts with data: and contains a JSON chunk. The stream ends with data: [DONE].

data: {"id":"gen-abc123","choices":[{"delta":{"role":"assistant"},"index":0}],"model":"anthropic/claude-sonnet-4-6"}

data: {"id":"gen-abc123","choices":[{"delta":{"content":"The capital"},"index":0}],"model":"anthropic/claude-sonnet-4-6"}

data: {"id":"gen-abc123","choices":[{"delta":{"content":" of France is Paris."},"index":0,"finish_reason":"stop"}],"model":"anthropic/claude-sonnet-4-6","usage":{"prompt_tokens":14,"completion_tokens":8,"cost":0.000066}}

data: [DONE]

Streaming chunk fields

id · string

Generation ID, consistent across all chunks in a stream.

model · string

The model ID that generated the response.

choices · object[]

Show properties

delta.content · string

The new text in this chunk. Accumulate these across chunks to get the full response.

delta.reasoning · string

Reasoning/thinking content for models that support extended thinking.

delta.reasoning_details · object

Encrypted reasoning blocks from some providers. Can be passed back in subsequent requests to preserve the reasoning trace.

finish_reason · string

stop when generation is complete. tool_calls when the model wants to call a tool. error when a mid-stream error occurs.

usage · object

Token counts and cost. Included in the final chunk only.

Show properties

prompt_tokens · number

Total input tokens.

completion_tokens · number

Total output tokens.

prompt_tokens_details.cached_tokens · number

Tokens served from cache. Cached tokens reduce cost.

cost · number

Total cost of the request in USD.

Mid-stream errors do not produce an HTTP error code — the connection was already 200 OK. Always check finish_reason in your streaming handler. See Errors for details.

Non-streaming response

When stream: false, the API waits for the model to finish and returns a single JSON object:

{
  "id": "gen-abc123",
  "model": "anthropic/claude-sonnet-4-6",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 8
  }
}

Multi-turn conversations

Include previous messages in the messages array to maintain context across turns:

{
  "model": "anthropic/claude-sonnet-4-6",
  "messages": [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": "What is a closure in JavaScript?"},
    {"role": "assistant", "content": "A closure is a function that retains access to its outer scope..."},
    {"role": "user", "content": "Can you show me an example?"}
  ]
}

Tool calling

Define tools that the model can call using the OpenAI function-calling format. When the model decides to use a tool, it responds with a tool_calls array instead of a text reply.

1. Define tools in the request

{
  "model": "anthropic/claude-sonnet-4-6",
  "messages": [
    {"role": "user", "content": "What's the weather in San Francisco?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City and state, e.g. San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    }
  ]
}

2. Receive the tool call

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"San Francisco, CA\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

3. Return the tool result

Send the result back as a tool role message to continue the conversation:

{
  "messages": [
    {"role": "user", "content": "What's the weather in San Francisco?"},
    {
      "role": "assistant",
      "tool_calls": [{"id": "call_abc123", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\": \"San Francisco, CA\"}"}}]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temperature\": 62, \"condition\": \"foggy\"}"
    }
  ]
}

Reasoning models

Some models support extended thinking, where the model reasons through a problem before generating a reply. Reasoning content streams in the delta.reasoning field:

{"choices":[{"delta":{"reasoning":"Let me think about this step by step..."}}]}

Reasoning tokens are counted separately from output tokens. Not all models support reasoning — check model capabilities before using this feature.

Image input

Models that support images accept base64-encoded content in the messages array:

{
  "model": "anthropic/claude-sonnet-4-6",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What's in this image?"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
      ]
    }
  ]
}

Complete example

curl

curl -X POST https://api.cline.bot/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "messages": [
      {"role": "system", "content": "You are a concise assistant. Answer in one sentence."},
      {"role": "user", "content": "Explain what an API is."}
    ],
    "stream": false
  }'

Authentication

Set up your API key.

Errors

Handle errors and implement retry logic.