Web search

Add the built-in syntic_web_search tool and the model can search the web while it answers. Syntic runs the searches, feeds the results to the model and returns an answer with citations to the pages it used. You do not run anything yourself and there is no extra round trip: one request in, one cited answer out.

When to use it

• Questions about recent events, prices, releases or anything after the model’s training.
• Research summaries that must link their sources.
• Checking facts before an agent acts on them.

For a page you already know the address of, use web fetch instead.

Endpoint and auth

POST https://app.syntic.ai/v1/chat/completions (and Messages), Authorization: Bearer sk_live_.... The model must list syntic_web_search in capabilities.server_tools. Organisation admins can turn web search off in the Console; requests then return 403 tool_disabled.

Tool definition

Add it to tools next to your own functions:

How it works

1. The model decides a search would help and writes a query.
2. Syntic runs the search and passes the top results (title, address, snippet, page text extract) to the model.
3. The model may search again, up to max_uses, then writes its answer with citations.

If the loop reaches its step limit before the model finishes, the reply ends with finish_reason: "pause"; send the conversation back unchanged to let it continue (see Stop reasons).

Response

{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The council confirmed on 3 October that garden waste collections move to fortnightly from 1 November.",
      "annotations": [{
        "type": "citation",
        "start_index": 0,
        "end_index": 98,
        "source": { "url": "https://www.example.gov.uk/news/garden-waste", "title": "Garden waste changes" },
        "location": { "type": "char", "start_char": 120, "end_char": 260 },
        "quote": "From 1 November, garden waste will be collected every two weeks."
      }],
      "server_tool_calls": [
        { "id": "srv_01", "type": "syntic_web_search", "query": "Leeds garden waste collection change November 2026", "results": 8, "status": "ok" }
      ]
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 5120, "completion_tokens": 64, "total_tokens": 5184,
    "server_tool_use": { "web_search_requests": 1 }
  }
}

Streaming

While a search runs, the stream sends a progress delta so your UI can show it:

data: {"choices":[{"index":0,"delta":{"server_tool_call":{"id":"srv_01","type":"syntic_web_search","query":"Leeds garden waste collection change November 2026","status":"running"}}}]}

followed by the same object with "status": "ok" and then the answer text. Keep-alive comments are sent during long searches.

Examples

curl https://app.syntic.ai/v1/chat/completions \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Amara S1.2",
    "stream": false,
    "tools": [{
      "type": "syntic_web_search",
      "max_uses": 3,
      "user_location": { "country": "GB", "city": "Leeds" },
      "freshness": "month"
    }],
    "messages": [{ "role": "user", "content": "Are Leeds garden waste collections changing this winter?" }]
  }'

const resp = await fetch('https://app.syntic.ai/v1/chat/completions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'Amara S1.2',
    stream: false,
    tools: [{ type: 'syntic_web_search', max_uses: 3, allowed_domains: ['gov.uk'] }],
    messages: [{ role: 'user', content: 'What is the current UK VAT registration threshold?' }],
  }),
})
const data = await resp.json()
const msg = data.choices[0].message
console.log(msg.content)
for (const a of msg.annotations ?? []) console.log('source:', a.source.title, a.source.url)

import os, requests
 
data = requests.post(
    "https://app.syntic.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}"},
    json={
        "model": "Amara S1.2",
        "stream": False,
        "tools": [{"type": "syntic_web_search", "max_uses": 3, "allowed_domains": ["gov.uk"]}],
        "messages": [{"role": "user", "content": "What is the current UK VAT registration threshold?"}],
    },
    timeout=180,
).json()
msg = data["choices"][0]["message"]
print(msg["content"])
for a in msg.get("annotations", []):
    print("source:", a["source"]["title"], a["source"]["url"])

Web search can be combined with your own function tools in the same tools array. Function calls are returned to you as usual; searches are run by Syntic.

Errors

Unified envelope. A failed individual search does not fail the request; it shows status: "failed" and the model carries on.

Pricing and limits

Search fees appear as their own line on the cost report.

Build notes for the platform team

• Engine exists (web-search function, used by chat-proxy). Needs a server-side tool loop inside api-proxy: run model, execute server tools, loop, then return.
• Never pass the provider name of the search backend to the client.
• Bill searches as separate usage lines (web_search) so they never mix with token counts.

Related

• Web fetch
• Citations
• Tool calling