# API Reference

Complete reference for the Context Link API.

## Base URL

```
https://context-link.ai/api/v1
```

## Authentication

All requests require an API key in the `Authorization` header:

```bash
Authorization: your-api-key-here
```

Get your API key from [Settings](https://context-link.ai/user/settings).

## Endpoints


### Context

Query your connected knowledge sources.

```
GET /api/v1/context?query=your-topic&mode=optional-mode&connection_type=optional-comma-separated-types&response_format=structured
```

Set `response_format=structured` to receive the retrieved chunks with citation metadata alongside the rendered markdown. If the parameter is absent or has any other value, the existing markdown response is unchanged.

[View full documentation →](/docs/context-endpoint)

### Question

Ask a question and receive a concise, cited answer (Pro plan).

```
GET /api/v1/question?query=your-question&mode=optional-mode&connection_type=optional-comma-separated-types&response_format=structured
```

Set `response_format=structured` to receive the generated answer and its cited sources in the same structured schema as `/context`. If the parameter is absent or has any other value, the existing response is unchanged.

[View full documentation →](/docs/question-endpoint)

### Save

Save content to Context Link's memory for later retrieval.

```
POST /api/v1/context/save?namespace=your-namespace
```

[View full documentation →](/docs/save-endpoint)

### Custom Connections

Push content from any external service into Context Link (write/push direction). Your AI fetches data, converts it to markdown, and upserts it by uid. Requires a separate bearer token.

[View full documentation →](/docs/custom-connections)

## Common responses

### Success response (query)

For `/context`, by default and for every `response_format` value other than `structured`:

```json
{
    "message": "Response content",
    "format": "markdown"
}
```

Both `/context` and `/question` use this schema with `response_format=structured`:

```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://context-link.ai/assets/connections/website.svg"
          }
        }
      ]
    }
  ]
}
```

For `/context`, `markdown` is the same string returned as `message` by default, and `results` contains the retrieved chunks, each with one source. For `/question`, `markdown` is the generated answer returned as `answer` by default, and `results` contains at most one result whose `content` is that answer and whose `sources` contains its cited sources.

### Success response (save)

```json
{
    "message": "Saved",
    "namespace": "your-namespace"
}
```

### Error response

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

## Status codes

| Code | Description |
|------|-------------|
| `200` | Request successful |
| `201` | Content saved successfully |
| `400` | Bad request - missing required parameters |
| `401` | Unauthorized - invalid or missing API key |
| `402` | Payment required - Pro plan needed (question endpoint only) |
| `404` | Not found - invalid API key or resource |
| `422` | Unprocessable entity - empty request body |
| `429` | Too many requests - rate limit or monthly LLM allowance exceeded |