Get Started

Search the web for live results, pull clean content from a result URL, then let the research endpoint do both for you and synthesize an answer with citations. Every step is a copy-paste request — set TELNYX_API_KEY to a key from the portal and they work as-is.

Search the Web

curl -X POST https://api.telnyx.com/v2/web_search \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "telnyx voice api",
    "count": 2
  }'

{
  "data": {
    "results": {
      "web": [
        {
          "url": "https://telnyx.com/products/voice-api",
          "title": "Voice API on the Carrier Network | Telnyx",
          "description": "Programmable voice on infrastructure Telnyx owns. Call control, transfer, record, monitor at the carrier layer.",
          "snippets": ["Deploy seamless communication experiences with developer-friendly APIs..."],
          "thumbnail_url": "https://telnyx.com/static/thumbnail/voice-api.png"
        }
      ]
    }
  }
}

Results come back ranked and structured — title, url, description, snippets — ready to hand to a model. Narrow them with domain, country, freshness, and safe-search filters; see Web Search for how the filters behave.

Read a Page

Search gives you snippets; content retrieval gives you the page. Ask for markdown and feed it straight to a model:

curl -X POST https://api.telnyx.com/v2/web_search/contents \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://en.wikipedia.org/wiki/Telnyx"],
    "formats": ["markdown"]
  }'

{
  "data": {
    "results": [
      {
        "url": "https://en.wikipedia.org/wiki/Telnyx",
        "title": "Telnyx - Wikipedia",
        "markdown": "[Jump to content](https://en.wikipedia.org/wiki/Telnyx#bodyContent)\n\nFrom Wikipedia, the free encyclopedia..."
      }
    ]
  }
}

One request handles up to 20 URLs. See Content Retrieval for formats and per-URL behavior.

Research a Question

For a whole question, skip the orchestration: research runs the searches, reads the sources, and returns a synthesized answer with citations.

curl -X POST https://api.telnyx.com/v2/web_search/research \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is SIP trunking and how does it differ from PSTN?",
    "research_effort": "lite"
  }'

{
  "data": {
    "answer": "SIP trunking is a modern technology that uses the internet to transmit voice, video, and data packets, replacing traditional physical phone lines [[1, 2, 3]]...",
    "citations": [
      {
        "url": "https://www.zayo.com/resources/what-is-sip-trunking-sip-trunking-defined/",
        "title": "What is SIP Trunking? | SIP Trunking Defined - Zayo",
        "snippet": "Maintaining seamless communication..."
      }
    ]
  }
}

Synchronous requests block until the answer is ready. For long-running research, add "background": true to get a task_id back immediately, then poll until status is completed:

curl https://api.telnyx.com/v2/web_search/research/{task_id} \
  -H "Authorization: Bearer $TELNYX_API_KEY"

See Research for sync vs background and the task lifecycle.

Ground Your Agent

Each response is tool output: declare search, retrieval, or research as function tools, run them when the model asks, and feed the JSON back. The [[1, 2, 3]] markers in research answers index into citations, so your agent can quote sources directly.

Next Steps

Web Search

Domain filters, freshness, and live crawling.

Content Retrieval

Formats, caching, and per-URL behavior.

Research

Synchronous vs background mode and polling.

Web Search

Features

API Reference

For AI Agents

Next Steps

Web Search

Content Retrieval

Research

​Next Steps

Web Search

Content Retrieval

Research

Next Steps