Request and response format

This page is the reference for /v1/think during Early Access. Both models use the same format.

The request and response follow the OpenAI Chat Completions structure, so most Chat Completions client code carries over. The differences are called out in each section below.

Endpoint and authentication

POST https://agent.deepgram.com/v1/think

Authenticate with your Deepgram API key using the Token scheme:

Authorization: Token <DEEPGRAM_API_KEY>

To authenticate from a browser or other untrusted client, use a short-lived token from token-based authentication with the Bearer scheme: Authorization: Bearer <token>.

Deepgram never forwards your credentials to the model service.

Request body

Send JSON with Content-Type: application/json. The endpoint accepts the eight fields below and rejects any other top-level field.

Unsupported fields

These Chat Completions fields are rejected as unknown fields: max_tokens, max_completion_tokens, top_p, stop, n, seed, tool_choice, response_format, frequency_penalty, presence_penalty, logprobs, and user. Remove them before sending a request.

Messages

messages is an array of message objects. The endpoint identifies each message by its shape. Use the standard roles: system, user, assistant, and tool.

content must be a plain string. The array-of-content-parts form is not supported.

System, user, and assistant messages

Assistant message with tool calls

Each tool call has this shape:

{
  "id": "call_123",
  "type": "function",
  "function": { "name": "get_order_status", "arguments": "{\"order_id\": \"A1234\"}" }
}

function.arguments is a JSON-encoded string.

Tool result message

Conversation history

The endpoint is stateless. Send the full conversation, including earlier tool calls and tool results, on every request.

Generation controls

• temperature sets sampling randomness. Lower values give more consistent replies.
• reasoning_effort sets how much the model reasons before answering. Think-Fast doesn’t reason by default: leave it unset or set it to none, because other values add reasoning tokens and latency.

Streaming

Set stream to true and stream_options to {"include_usage": true}. The response has Content-Type: text/event-stream.

{
  "model": "think-fast",
  "stream": true,
  "stream_options": { "include_usage": true },
  "messages": [{ "role": "user", "content": "Hi, can you check on my order?" }]
}

Each event’s data: line holds a chat.completion.chunk object. The stream then ends in this order:

1. A chunk whose choice has finish_reason set, such as "stop".
2. A final chunk with an empty choices array and a usage object.
3. data: [DONE]

If the model service’s stream breaks off, the response ends without [DONE]. Treat a missing [DONE] as a failed request.

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"Sure"}}]}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"! Could you"}}]}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":32,"completion_tokens":19,"total_tokens":51}}
data: [DONE]

For a full streaming loop, see Build a cascaded agent.

Function calling

Pass function tools in tools. function is the only supported tool type.

{
  "model": "think-fast",
  "messages": [
    { "role": "system", "content": "You help customers check on their orders." },
    { "role": "user", "content": "Where is order A1234?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "Look up the shipping status of an order. Call this when the customer gives an order number.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string", "description": "The order number, such as A1234." }
          },
          "required": ["order_id"]
        }
      }
    }
  ]
}

When the model calls a tool, the response message contains tool_calls. To continue:

1. Run the function in your application.
2. Append the assistant message with its tool_calls to messages.
3. Append a tool message with the result and the matching tool_call_id.
4. Send the request again with the same tools.

The assistant message can contain content as well as tool_calls, such as “Sure, checking on that order.” Speak it, and keep it in the assistant message you append.

The endpoint forwards tool-call history intact, so the model can keep calling tools across turns.

Response format

A successful response returns the model’s status code and body unchanged.

When stream is false, the response is 200 with Content-Type: application/json and a chat.completion object:

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1792786932,
  "model": "think-fast",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Sure! Could you please provide your order number…",
        "refusal": null
      },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 19,
    "total_tokens": 51,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 }
  }
}

Usage

Errors

Errors that Deepgram returns use the standard Deepgram error body, and the same message appears in the dg-error response header:

{
  "err_code": "Bad Request",
  "err_msg": "Model not available.",
  "request_id": "0b2f6c1e-5a7d-4c3e-9f1a-2d8e4b6a7c90"
}

Errors from the model service are relayed unchanged, with their own status code and error body.

A stream that ends without data: [DONE] also means the request failed. The model service’s stream broke off after the response started, so no error status is sent. Treat the response as incomplete and retry.