# Context Endpoint

Retrieve context-aware responses from your connected knowledge sources.

## Quick reference

| Property | Value |
|----------|-------|
| **Endpoint** | `GET /api/v1/context` |
| **Authentication** | API key via `Authorization` header |
| **Rate limit** | 5 requests per 10 seconds |
| **Response format** | JSON |
| **Cache duration** | 1 hour per unique query + mode combination |

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | The question or search query. Dashes and underscores are converted to spaces. |
| `mode` | string | No | Optional mode name to weight results (e.g. `customer-support`). Spaces and underscores are normalized to dashes. |
| `connection_type` | string | No | Comma-separated list of connection types to restrict retrieval to (e.g. `site,email`). Only content from those sources is returned. Valid types: `site`, `email`, `files`, `notion`, `google_doc`, `one_drive`, `basecamp`, `monday`, `youtube`, `webmention`, `custom`, `memory`. |
| `response_format` | string | No | Set to `structured` to include the retrieved chunks, source metadata, and scores. If omitted or set to any other value, the response remains the default Markdown payload. |

### Status codes

| Code | Description |
|------|-------------|
| `200` | Query successful |
| `400` | Query parameter is missing, or `connection_type` names an unknown type |
| `401` | API key is missing or subscription required |
| `404` | API key is invalid |
| `429` | Rate limit exceeded |

## Examples

### Basic usage

Query your connected knowledge sources with a simple GET request:

```bash
curl -X GET "https://www.context-link.ai/api/v1/context?query=what-is-RAG" \
     -H "Authorization: your-api-key-here"
```

**Response:**

```json
{
    "message": "RAG (Retrieval-Augmented Generation) is...",
    "format": "markdown"
}
```

### With mode

Weight results toward a specific mode configured on your Connections page:

```bash
curl -X GET "https://www.context-link.ai/api/v1/context?query=what-is-RAG&mode=customer-support&connection_type=site,notion" \
     -H "Authorization: your-api-key-here"
```

Modes let you create named weighting profiles so the same connections can be prioritized differently depending on use case.

### Query formatting

Dashes and underscores in queries are automatically converted to spaces:

```bash
# These queries are equivalent:
?query=hello-world
?query=hello_world
?query=hello%20world

# All become: "hello world"
```

### Python example

```python
import requests

api_key = "your-api-key-here"
query = "what is context link"

response = requests.get(
    "https://context-link.ai/api/v1/context",
    params={"query": query},
    headers={"Authorization": api_key}
)

data = response.json()
print(data["message"])
```

### JavaScript example

```javascript
const axios = require('axios');

const apiKey = 'your-api-key-here';
const query = 'what is context link';

axios.get('https://context-link.ai/api/v1/context', {
    params: { query },
    headers: { 'Authorization': apiKey }
})
.then(response => {
    console.log(response.data.message);
})
.catch(error => {
    console.error('Error:', error.response.data);
});
```

### Ruby example

```ruby
require 'net/http'
require 'json'
require 'uri'

api_key = 'your-api-key-here'
query = 'what is context link'

uri = URI('https://context-link.ai/api/v1/context')
uri.query = URI.encode_www_form(query: query)

request = Net::HTTP::Get.new(uri)
request['Authorization'] = api_key

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
end

data = JSON.parse(response.body)
puts data['message']
```


## Response format

By default, successful responses return JSON with this structure:

```json
{
    "message": "The response content in Markdown format",
    "format": "markdown"
}
```

The `message` field contains the context-aware response generated from your connected knowledge sources. It's formatted as Markdown and may include:

- Headings and paragraphs
- Lists (bulleted and numbered)
- Code blocks
- Links to source material
- Emphasis and formatting

Set `response_format=structured` to receive the same Markdown content together with the retrieved chunks and their sources:

```bash
curl -X GET "https://www.context-link.ai/api/v1/context?query=ticket%20deflection%20benchmarks&response_format=structured" \
     -H "Authorization: your-api-key-here"
```

```json
{
    "format": "structured",
    "query": "ticket deflection benchmarks",
    "markdown": "## Support benchmarks\n\nTeams using guided self-service deflect 42% of repeat tickets.",
    "results": [
        {
            "content": "Teams using guided self-service deflect 42% of repeat tickets.",
            "position": 3,
            "rank": 1,
            "score": 0.82,
            "content_sha": "f09d847fc7a20ac8598c5042abd58663ee52d3878bca7693416bb5d4124d5151",
            "sources": [
                {
                    "citation": null,
                    "uid": "support-benchmarks-2026",
                    "title": "Support benchmarks",
                    "url": "https://docs.example.com/support-benchmarks",
                    "source_updated_at": "2026-08-12T03:14:15Z",
                    "connection": {
                        "uid": "support-site",
                        "type": "Site",
                        "name": "docs.example.com",
                        "logo_url": "https://www.google.com/s2/favicons?sz=256&domain=docs.example.com"
                    }
                }
            ]
        }
    ]
}
```

The `markdown` value is the same content returned in `message` by the default response. Each item in `results` represents one retrieved chunk and includes its content, original position, rank, similarity score, content hash, and `sources` array. For this endpoint, each result normally has one source and its `citation` is `null`. `sources[].connection.uid` is the same connection UID returned by `GET /api_accounts/:uid/connections`, and `sources[].connection.logo_url` is always absolute. When the endpoint resolves directly to a namespace document, `results` contains one item with `rank` and `score` set to `null`.

Only the exact value `structured` opts in. Omitting `response_format` or using any other value returns the unchanged default payload with `message` and `format`.

## Error responses

Errors follow this format:

```json
{
    "message": "Error description"
}
```

**Common errors:**

```json
// 400 Bad Request - Missing query
{
    "message": "A query is required"
}

// 401 Unauthorized - Missing API key
{
    "message": "API key required"
}

// 401 Unauthorized - Subscription required
{
    "message": "You need to be subscribed to access that page"
}

// 404 Not Found - Invalid API key
{
    "message": "Not found"
}
```