Research 2.0

Research 2.0 · upgraded engine

Research 2.0 — faster answers, deeper coverage, more reliable reasoning.

→4× fewer hallucinations
→2× deeper answers
→2× research logic consistency
→Optional reasoning effort — none → xhigh

Migrating from the retired /v1/chat/completions endpoint? Same Bearer auth, same credit balance — just point your client at /v1/responses and move your prompt into the input field.

POST/v1/responses

OpenAI-compatible Responses API for Surf chat. Use Bearer authorization. Hermod handles authentication, credit billing, and proxying to Surf's Responses execution backend. Non-streaming requests return JSON; streaming requests return Server-Sent Events (SSE).

Query Parameters

modelstring (surf-2.0, surf-2.0-instant)required

Model for the Responses API. Use `surf-2.0` for the full research engine, or `surf-2.0-instant` for a faster, lower-latency answer. `surf-2.0-instant` costs 20 credits per call. `surf-2.0` pricing depends on `reasoning.effort`: omitted/none=20, minimal=30, low=50, medium=120, high=150, xhigh=200 credits.

Example: surf-2.0

inputstringrequired

User input for the response. Use a plain string for simple prompts; advanced callers may send Responses-compatible input item arrays.

Example: Summarize today's Bitcoin ETF flows and explain the market impact.

instructionsstring

Optional system or developer instructions that guide the answer style and constraints.

Example: Be concise and include key numbers.

streamboolean

If true, the response is streamed as Server-Sent Events (SSE).

Example: false

includestring[]

Optional extra response fields to include when supported by the backend.

max_output_tokensinteger

Maximum number of output tokens to generate.

metadataobject

Optional client metadata. Reserved Surf identity keys are ignored before proxying.

Example: {"request_id":"req_abc123"}

previous_response_idstring

Previous response ID for continuing a Responses chain.

promptobject

Optional prompt object for reusable prompt configurations.

reasoningobject

Optional reasoning configuration (OpenAI Responses format). Include it to enable extended, multi-step thinking; omit for a fast single-pass answer. The flat reasoning_effort field used by the retired /v1/chat/completions endpoint is not accepted here.

Example: {"effort":"high"}

Choosing a model

Research 2.0 ships in two variants — pick via the model field:

Model	Use it for
`surf-2.0`	Full research engine — deepest coverage and grounding.
`surf-2.0-instant`	Lower-latency answers when speed matters more than depth.

surf-2.0-instant returns a faster, more concise answer at 20 credits per call. Full surf-2.0 pricing scales with reasoning.effort, from 20 credits with no extended reasoning to 200 credits at xhigh (see Credits & Pricing). For latency-sensitive lookups, instant is typically several times faster than the full model.

curl -X POST https://api.asksurf.ai/gateway/v1/responses \
  -H "Authorization: Bearer $SURF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "surf-2.0-instant",
    "input": "What is the current price of BTC?"
  }'

Reasoning & effort

Research 2.0 accepts an optional reasoning object, following the OpenAI Responses format. It controls how deeply Surf thinks before answering — trading latency for depth.

Include reasoning → extended, multi-step analysis.
Omit reasoning → fast, single-pass answer.

curl -X POST https://api.asksurf.ai/gateway/v1/responses \
  -H "Authorization: Bearer $SURF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "surf-2.0",
    "input": "How has BTC ETF flow shifted this week, and what is driving it?",
    "reasoning": { "effort": "high" }
  }'

Effort levels

reasoning.effort accepts six levels, in increasing order of depth and latency:

Effort	Credits / call	Depth
omitted / `none`	20	No extended reasoning — fastest.
`minimal`	30	Very light planning.
`low`	50	Light analysis for straightforward queries.
`medium`	120	Balanced depth and speed.
`high`	150	Deep, multi-step research.
`xhigh`	200	Maximum depth and grounding — slowest.

Start with medium for most questions, drop to low/minimal for latency-sensitive lookups, and reach for high/xhigh on complex, open-ended research.

Effort changes depth, latency, and price for surf-2.0. surf-2.0-instant always costs 20 credits per call.

Templates

The same request in JavaScript and Python — set reasoning.effort to any level above.

const res = await fetch("https://api.asksurf.ai/gateway/v1/responses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SURF_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "surf-2.0",
    input: "How has BTC ETF flow shifted this week, and what is driving it?",
    reasoning: { effort: "high" },
  }),
});
const data = await res.json();

import os, requests
 
res = requests.post(
    "https://api.asksurf.ai/gateway/v1/responses",
    headers={
        "Authorization": f"Bearer {os.environ['SURF_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "surf-2.0",
        "input": "How has BTC ETF flow shifted this week, and what is driving it?",
        "reasoning": {"effort": "high"},
    },
)
data = res.json()

⚠️ Warning

You must nest the level under reasoning.effort. The flat top-level reasoning_effort string (used by the retired /v1/chat/completions endpoint) is not accepted here and returns an error.

Research 2.0

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "model": "surf-2.0",
  "input": "Summarize today's Bitcoin ETF flows and explain the market impact.",
  "instructions": "Be concise and include key numbers.",
  "stream": false,
  "metadata": {
    "request_id": "req_abc123"
  },
  "reasoning": {
    "effort": "high"
  }
})
};

fetch('https://api.asksurf.ai/gateway/v1/responses', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1764312947,
  "status": "completed",
  "model": "surf-2.0",
  "output": [
    {
      "id": "msg_abc123",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Bitcoin ETF flows were net positive today."
        }
      ]
    }
  ],
  "output_text": "Bitcoin ETF flows were net positive today, supporting risk appetite across majors.",
  "usage": {
    "input_tokens": 2380,
    "output_tokens": 420,
    "total_tokens": 2800
  },
  "metadata": {},
  "error": null,
  "incomplete_details": null
}