> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started

> Search the web, read a page, and run deep research -- three requests with one API key.

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](https://portal.telnyx.com/#/api-keys) and they work as-is.

<Steps>
  <Step title="Search the Web">
    ```bash theme={null}
    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
      }'
    ```

    ```json theme={null}
    {
      "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](/docs/web-search/web-search) for how the filters behave.
  </Step>

  <Step title="Read a Page">
    Search gives you snippets; content retrieval gives you the page. Ask for `markdown` and feed it straight to a model:

    ```bash theme={null}
    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"]
      }'
    ```

    ```json theme={null}
    {
      "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](/docs/web-search/contents) for formats and per-URL behavior.
  </Step>

  <Step title="Research a Question">
    For a whole question, skip the orchestration: research runs the searches, reads the sources, and returns a synthesized answer with citations.

    ```bash theme={null}
    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"
      }'
    ```

    ```json theme={null}
    {
      "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`:

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

    See [Research](/docs/web-search/research) for sync vs background and the task lifecycle.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Web Search" href="/docs/web-search/web-search">
    Domain filters, freshness, and live crawling.
  </Card>

  <Card title="Content Retrieval" href="/docs/web-search/contents">
    Formats, caching, and per-URL behavior.
  </Card>

  <Card title="Research" href="/docs/web-search/research">
    Synchronous vs background mode and polling.
  </Card>
</CardGroup>