POST /v1/chat/completions

​

Overview

​

Quick Start

Supported models: surf-ask, surf-research, surf-1.5, surf-1.5-instant, surf-1.5-thinking.

surf-ask and surf-research are legacy models. surf-1.5, surf-1.5-instant, and surf-1.5-thinking are the new models. Legacy models remain available and the request format is unchanged.

Note: When using surf-research and surf-1.5, it is recommended to set the timeout to 10 minutes.

​

What’s new in surf-1.5

• Enhanced performance: Delivers superior response quality with significantly reduced latency in surf-1.5-instant, providing faster and more accurate results compared to legacy models.
• Custom tool calls (function calling): Better support for defining tools via tools and orchestrating multi-step tool-augmented tasks.
• Configurable reasoning depth: Use reasoning_effort (low / medium / high) to trade off speed vs. deeper analysis.
• Built for agent-style workflows: Works well with Surf extensions like ability (capability constraints) and citation (citation formats) in the same request shape.

​

Model variants: surf-1.5, surf-1.5-instant, surf-1.5-thinking

• surf-1.5-instant: A lightweight model optimized for fast responses to simple queries.
• surf-1.5-thinking: A more powerful model with deeper reasoning capabilities, designed to handle complex problems that require thorough analysis and multi-step reasoning.
• surf-1.5: An adaptive model that automatically selects between surf-1.5-instant and surf-1.5-thinking based on the request parameters and problem complexity. This provides an optimal balance between speed and depth without requiring manual model selection.

​

Summary (What you can do)

• OpenAI-compatible: Use the OpenAI Chat Completions shape (model, messages, optional stream) and standard Authorization: Bearer <API_KEY>.
• Streaming (SSE): Set stream=true to receive incremental chunks (text/event-stream) and terminate on data: [DONE].
• Custom tool calls: Provide tools (OpenAI function calling). The model may request tool executions during generation.
• Reasoning depth: Control analysis strength with reasoning_effort: low / medium / high.
• Surf extensions: Use ability to constrain available capability domains and citation to request output citation formats.
• Errors: This endpoint may return 400, 401, or 502 (both streaming and non-streaming).

​

Examples

{
  "model": "surf-ask", // Required: model identifier. Options: surf-ask / surf-research / surf-1.5 / surf-1.5-instant / surf-1.5-thinking
  "messages": [ // Required: list of chat messages (recommended: at least one role=user message)
    {
      "role": "system", // Required: system / user / assistant
      "content": "You are Surf, an analysis assistant focused on crypto markets and on-chain data." // Required: message content
    },
    {
      "role": "user", // Required: user input
      "content": "Summarize today's BTC market conditions and list the key drivers." // Required: your question/task
    }
  ],
  "stream": false, // Optional: enable streaming output. true -> SSE(text/event-stream), false -> JSON
  "reasoning_effort": "medium", // Optional: reasoning strength low / medium / high
  "ability": [ // Optional: Surf extension: capability-domain constraints/hints
    "evm_onchain", // search / evm_onchain / solana_onchain / market_analysis / calculate
    "market_analysis"
  ],
  "citation": [ // Optional: Surf extension: citation formats to include
    "source", // source / chart
    "chart"
  ],
  "tools": [ // Optional: tool definitions (OpenAI tools/function calling)
    {
      "type": "function", // Required: currently fixed to function
      "function": { // Required: function tool definition
        "name": "calculate_portfolio_value", // Required: tool name (function name)
        "description": "Calculate total portfolio value", // Optional: tool purpose
        "parameters": { // Optional: parameters JSON Schema
          "type": "object",
          "properties": {
            "symbols": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["symbols"]
        }
      }
    }
  ]
}

​

Non-streaming response example (with field annotations)

{
  "id": "chatcmpl-abc123", // Unique identifier for this completion
  "object": "chat.completion", // Object type (non-streaming responses are typically chat.completion)
  "created": 1699890366, // Creation timestamp (seconds)
  "model": "surf-ask", // Model identifier actually used
  "choices": [ // List of generated results (usually only 1)
    {
      "index": 0, // Choice index
      "finish_reason": "stop", // Finish reason: stop/length/tool_calls/content_filter/error (may also be null)
      "message": { // Final message (assistant)
        "role": "assistant", // Role (typically assistant)
        "content": "BTC is trading flat in the last 24h with rising open interest.", // Model output text
        "reasoning": "Internal chain-of-thought or brief rationale" // (If returned) reasoning/rationale field
      }
    }
  ],
  "usage": { // Token usage statistics
    "prompt_tokens": 23, // Input tokens
    "completion_tokens": 12, // Output tokens
    "total_tokens": 35 // Total tokens (input + output)
  }
}

​

Request fields (model.CompletionsRequest)

Note: This endpoint follows the overall structure of OpenAI chat.completions, and additionally provides Surf extension fields such as ability and citation.

​

Single message in messages[] (model.Message)

​

Tool definitions in tools[] (model.Tool / model.ToolFunction)

​

Response fields (non-streaming JSON: model.CompletionsProxyResponse)

​

choices[] (model.CompletionsChoice)

​

message (model.CompletionsMessage)

​

usage (model.CompletionsUsage)

​

Streaming response (SSE: text/event-stream)

data: { ...json... }

data: [DONE]

Note: The current OpenAPI spec does not define a dedicated schema for streaming chunks. In the examples, each chunk’s object is typically chat.completion.chunk, and incremental output is delivered via choices[].delta (e.g., role / content). finish_reason is usually null until the stream ends.

​

Error response (model.BaseResponse)

[
  "[\"evm_onchain\"",
  "\"market_analysis\"",
  "\"calculate\"]"
]

["[\"source\"", "\"chart\"]"]