> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Linkup

> Use Linkup web search with Respan via the gateway — sourced answers as template variables, full observability.

[Linkup](https://www.linkup.so/) is a web search API that returns sourced answers grounded in real-time web data. Use it through the Respan gateway to ground LLM completions with fresh information, rendered into your prompts via template variables.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys). For gateway, also add [credits](https://platform.respan.ai/platform/gateway/credits) or a [provider key](https://platform.respan.ai/platform/gateway/api-keys?providers=1).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Gateway

> **Note**
>
> Linkup is a gateway-only integration. Calls run through the Respan gateway and are automatically traced.

## Setup

#### Set environment variables

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export LINKUP_API_KEY="YOUR_LINKUP_API_KEY"
```

#### Add Linkup parameters to your request

Include `linkup_params` in your request body. The Linkup response is rendered into your prompt as `{{ linkup_search_response }}`.

```python
import os
import requests

response = requests.post(
    "https://api.respan.ai/api/chat/completions",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['RESPAN_API_KEY']}",
    },
    json={
        "model": "gpt-4.1-nano",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Please summarize: {% if linkup_search_response %}{{ linkup_search_response.answer }}{% endif %}"},
        ],
        "linkup_params": {
            "api_key": os.environ["LINKUP_API_KEY"],
            "q": "What is Microsoft's 2024 revenue?",
            "depth": "deep",
            "outputType": "sourcedAnswer",
            "includeImages": False,
        },
    },
)
print(response.json())
```

## Template variables

Use Jinja2 syntax to render Linkup responses in your messages. See the [Jinja2 docs](/docs/documentation/features/prompt-management/advanced#variables--jinja-templates).

```
{% if linkup_search_response %}
{{ linkup_search_response.answer }}

Sources:
{% for source in linkup_search_response.sources %}
- {{ source.name }}: {{ source.url }}
  {{ source.snippet }}
{% endfor %}
{% endif %}
```

## Parameters

| Parameter                | Type    | Description                                              | Default           |
| ------------------------ | ------- | -------------------------------------------------------- | ----------------- |
| `q`                      | string  | The search query.                                        | Required          |
| `depth`                  | string  | Search depth: `"standard"` or `"deep"`.                  | `"deep"`          |
| `outputType`             | string  | `"searchResults"`, `"sourcedAnswer"`, or `"structured"`. | `"sourcedAnswer"` |
| `structuredOutputSchema` | string  | Schema for structured output.                            | `null`            |
| `includeImages`          | boolean | Whether to include images in the response.               | `false`           |

## Response structure

```json
{
  "answer": "The answer text",
  "sources": [
    {
      "name": "Source name",
      "url": "Source URL",
      "snippet": "Text snippet from the source"
    }
  ]
}
```

## Error handling

If the Linkup API call fails, the error is added to `warnings_dict` in the response under the key `LINKUP_SEARCH_ERROR`.