# Keenable REST API

Base URL: `https://api.keenable.ai`.

Authentication: API key via the `X-API-Key` header.

Create an API key in the [console](https://keenable.ai/console).

---

## Search Web Pages

Search the web and return ranked results with URLs, titles, and descriptions.

```bash
curl -X POST "https://api.keenable.ai/v1/search" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "typescript best practices" }'
```

**Input**

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | The search query |

**Output**

| Field | Type | Description |
|---|---|---|
| `results` | array | List of search results |
| `results[].title` | string | Page title |
| `results[].url` | string | Page URL |
| `results[].description` | string | Snippet / summary of the page |

**Output example**

```json
{
  "results": [
    {
      "title": "TypeScript Best Practices 2026",
      "url": "https://example.com/ts-best-practices",
      "description": "A comprehensive guide to modern TypeScript patterns and best practices."
    }
  ]
}
```

---

## Fetch Page Content

Retrieve content from a URL as clean markdown. Note that only URLs from our index are supported; we don't offer general web scraping.

```bash
curl "https://api.keenable.ai/v1/fetch?url=https://example.com/ts-best-practices" \
  -H "X-API-Key: <YOUR_API_KEY>"
```

**Input**

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string | yes | URL to fetch |

**Output**

| Field | Type | Description |
|---|---|---|
| `url` | string | The fetched URL |
| `title` | string | Page title (if available) |
| `content` | string | Extracted page content in markdown |

**Output example**

```json
{
  "url": "https://example.com/ts-best-practices",
  "title": "TypeScript Best Practices 2026",
  "content": "# TypeScript Best Practices 2026\n\nUse strict mode, prefer interfaces over type aliases for object shapes..."
}
```

---

## Submit Search Feedback

Submit per-URL relevance scores after a search to improve result quality over time.

```bash
curl -X POST "https://api.keenable.ai/v1/feedback" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "typescript best practices",
    "feedback": {
      "https://example.com/ts-best-practices": 5,
      "https://example.com/old-js-guide": 1
    }
  }'
```

**Input**

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | The original search query |
| `feedback` | object | yes | Map of URL to relevance score (0–5) |
| `feedback_text` | string | no | Additional feedback in free text |

Score scale: 0 = content not loaded, 1 = low relevance, 2 = somewhat relevant, 3 = relevant, 4 = highly relevant, 5 = perfect match.

**Output**

| Field | Type | Description |
|---|---|---|
| `message` | string | Confirmation message |

**Output example**

```json
{
  "message": "Feedback submitted successfully"
}
```