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

> ## Agent Instructions
> Every page is listed in https://docs.keenable.ai/llms.txt. To pick a product for a job, read https://docs.keenable.ai/choose.md
> Setup steps for agents, covering the SDKs, the MCP server and the CLI: https://docs.keenable.ai/skill.md
> Keenable search and fetch work without an API key. To add them to code, use the official SDK for the project's language: https://docs.keenable.ai/sdks.md
> Without a key, call POST https://api.keenable.ai/v1/search/public or GET https://api.keenable.ai/v1/fetch/public with an X-Keenable-Title header that names your app.
> With a key, send it in the X-API-Key header and read it from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat. Every access method: https://docs.keenable.ai/auth.md
> To get an API key without the console, use device login: https://docs.keenable.ai/authentication.md#device-login
> MCP server: https://api.keenable.ai/mcp (no key, or X-API-Key; keyless Codex uses https://api.keenable.ai/mcp-public), or https://api.keenable.ai/mcp-oauth for OAuth sign-in. These docs are an MCP server at https://docs.keenable.ai/mcp and the OpenAPI spec is at https://docs.keenable.ai/api-reference/openapi.json
> Keenable searches and fetches public web pages. If a question needs no web information, skip the call.
> On 402 with an API key (code insufficient_credits), stop and ask a human to add credits; don't retry. On 429, wait the number of seconds in Retry-After, then retry. Before you ship, follow https://docs.keenable.ai/production.md
> Every error, with its cause and fix, is in https://docs.keenable.ai/errors.md and moving from another search API is covered in https://docs.keenable.ai/migrate.md
> Before you compare Keenable with another search API, read https://docs.keenable.ai/guides/evaluate-search-apis.md

# Go SDK for web search and fetch

> Add the Keenable Go module, run a keyless web search, fetch pages, create Monitors, verify webhooks and handle typed errors with errors.As.

The Keenable Go SDK gives your code web search, page fetch and [Monitors](https://docs.keenable.ai/products/monitors). This page covers version 0.2.0, the latest release on the Go module proxy. For the other languages, see [TypeScript](https://docs.keenable.ai/sdks/typescript.md), [Python](https://docs.keenable.ai/sdks/python.md) and [Rust](https://docs.keenable.ai/sdks/rust.md). For what all four SDKs share, see [SDKs](https://docs.keenable.ai/sdks.md).

## Install

Install the package. The SDK needs Go 1.22 or newer:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
go get github.com/keenableai/keenable-sdk/go@latest
```

Run it inside a Go module. In an empty folder, run `go mod init example.com/demo` first. The package name is `keenable`.

To see which version you have, run `go list -m github.com/keenableai/keenable-sdk/go`.

## Authenticate

Search and fetch work without an API key. An [API key](https://docs.keenable.ai/api-keys.md) raises your rate limit, and Monitors needs one. Set `KEENABLE_API_KEY` and create the client with `keenable.New(nil)`, which reads the variable. To pass the key in code, use `keenable.New(&keenable.Options{APIKey: &key})`. `APIKey` is a pointer, so unset and empty differ. `nil` reads `KEENABLE_API_KEY`. A pointer to an empty string forces the keyless endpoints even when the variable is set.

The constructor takes these settings:

| Setting | Go | Default |
| - | - | - |
| API key, a pointer | `APIKey` | `KEENABLE_API_KEY` |
| Base URL, a pointer | `BaseURL` | `KEENABLE_API_URL`, else `https://api.keenable.ai` |
| Timeout for each attempt | `Timeout` | `30s` |
| Retries after a failed request, a pointer | `MaxRetries` | `2` |
| Headers on every request | `Headers` | none |
| Traffic source, sent as `X-Keenable-Title` | `ClientSource` | `Keenable SDK` |
| Your own `*http.Client`, for a proxy or custom transport | `HTTPClient` | one the SDK creates |

`SearchOptions`, `FetchOptions` and every Monitors params struct embed `RequestOptions`, which sets `Timeout`, `MaxRetries` and `Headers` for one call. Call `client.Close()` when you finish if the SDK created the HTTP client.

## Search

This program runs one keyless search and prints the top 3 results as a citable block:

```go main.go theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/keenableai/keenable-sdk/go"
)

func main() {
	client, err := keenable.New(nil) // keyless: no API key needed to try it
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	results, err := client.Search(context.Background(), "fastest inference providers 2026",
		&keenable.SearchOptions{MaxResults: 3})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(results.ToContext(nil))
}
```

Save it as `main.go` and run `go run .`. You see one `[n] Title (url)` header per result, followed by the page text.

| What it does | Go |
| - | - |
| Search the web | `Search(ctx, query, *SearchOptions)` |
| Render results as a citable block | `ToContext(nil)` |
| List the results the block cites | `Cited(nil)` |

Search options are fields on `keenable.SearchOptions`: `ExcludeDomains`, `PublishedAfter`, `PublishedBefore`, `AcquiredAfter`, `AcquiredBefore`, `SnippetMaxLength`, `MaxResults`, `QueryTime`, `Objective`, `DisableCards`, `Site` and `Mode`. Each one is described under [Search parameters](https://docs.keenable.ai/products/search.md#key-parameters). To change how much text the citable block holds, see [Context size](https://docs.keenable.ai/sdks.md#context-size).

## Fetch

This program fetches one page without a key and prints its title and the first 300 characters of its markdown:

```go main.go theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/keenableai/keenable-sdk/go"
)

func main() {
	client, err := keenable.New(nil) // keyless: no API key needed to try it
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	page, err := client.Fetch(context.Background(), "https://keenable.ai")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(page.Title)

	content := []rune(page.Content)
	if len(content) > 300 {
		content = content[:300]
	}
	fmt.Println(string(content))
}
```

| What it does | Go |
| - | - |
| Fetch one page as markdown | `Fetch(ctx, url)` |
| Fetch with options | `FetchWithOptions(ctx, url, *FetchOptions)` |
| Render the page as a citable block | `ToContext(nil)` |

Pass the fetch options through `FetchWithOptions` and the `MaxChars`, `Live` and `Prompt` fields of `keenable.FetchOptions`. Each one is described under [Fetch parameters](https://docs.keenable.ai/products/fetch.md#key-parameters).

## Monitors

A monitor watches the web for a topic and keeps every new page that matches. The Monitors API is under `client.Monitors`. It needs an API key: without one, a call fails with the SDK's authentication error and sends no request. This program creates a monitor with a webhook, then prints its ID, status and webhook signing secret:

```go main.go theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/keenableai/keenable-sdk/go"
)

func main() {
	// reads KEENABLE_API_KEY from the environment
	client, err := keenable.New(nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	monitor, err := client.Monitors.Create(context.Background(), &keenable.MonitorCreateParams{
		Name:   "Open-weights LLM releases",
		Search: keenable.MonitorSearchParams{Query: "new open-weights LLM releases"},
		Webhook: &keenable.MonitorWebhookParams{
			URL:    "https://hooks.example.com/keenable",
			Events: []string{"monitor.result.found", "monitor.disabled"},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(monitor.ID, monitor.Status)
	if monitor.Webhook != nil && monitor.Webhook.Secret != nil {
		fmt.Println(*monitor.Webhook.Secret) // shown once: store it
	}
}
```

Set `KEENABLE_API_KEY` before you run it. Keep the secret: the API returns it only here and in an update that adds the first webhook, and you need it to verify each delivery. Store it where your webhook handler can read it, and keep it out of logs.

| What it does | Go |
| - | - |
| Create a monitor | `Create(ctx, *MonitorCreateParams)` |
| List monitors | `List, ListAll` |
| Read, change or delete one monitor | `Get, Update, Delete` |
| Pause or resume | `Pause, Resume` |
| Start a run, read runs | `Trigger, Runs, Run` |
| Read a monitor's results | `Results` |
| Webhook deliveries, counts, bulk actions | `Deliveries, Stats, Bulk` |

`ListAll` returns a `*MonitorIterator`. In `MonitorUpdateParams`, `RemoveName`, `RemoveSchedule`, `RemoveOutputSchema`, `RemoveWebhook` and `RemoveMetadata` clear a field. `Create` always sends an `Idempotency-Key`, so the SDK can retry it without creating a second monitor. For queries, schedules and result fields, see [Monitors](https://docs.keenable.ai/products/monitors).

## Verify webhooks

Check each webhook delivery's signature before you act on it. Call `keenable.VerifyWebhook(payload, headers, secret, *WebhookOptions)`, in package `keenable`. It needs no client and no API key.

| Item | Go |
| - | - |
| Function | `keenable.VerifyWebhook(payload, headers, secret, *WebhookOptions)` |
| Returns | a `*WebhookEvent` and an error |
| Failed check | `*WebhookVerificationError` |
| Clock tolerance, 5 minutes by default | `WebhookOptions.Tolerance` |

Pass the raw body as `[]byte` and the request's `http.Header`. Pass `nil` for the options to keep the 5-minute tolerance. Answer a failed check with `400` and don't act on the delivery. Drop repeated deliveries by the event's ID, which stays the same across retries. For a complete handler, see [Verify a webhook](https://docs.keenable.ai/products/monitors#verify-a-webhook).

## Errors

The Go SDK returns typed errors. Before an error reaches your code, the SDK retries the request, by default up to 2 times, when the Retryable column says yes. If the API's error body sets `retryable`, that value decides instead of the status code. The Monitors update, trigger and bulk calls are retried only on a 429, which the API sends before it changes anything, because repeating them after another error could apply the change twice. For what each status code means and how to fix it, see [Errors](https://docs.keenable.ai/errors.md).

| Error | When | Retryable |
| - | - | - |
| `keenable.Error` | The interface every error below implements. `Code()` returns the SDK's code | Depends on the error |
| `*APIError` | A non-2xx response with no more specific type. Read `StatusCode`, `APICode`, `Fix` and `RequestID` | Yes for 408 and 5xx, no for other codes |
| `*AuthError` | HTTP 401 or 403, the API key was rejected | No |
| `*InsufficientCreditsError` | HTTP 402, out of funds. Alias `CreditsError` | No |
| `*RateLimitError` | HTTP 429, rate limit exceeded. Read `RetryAfter` and `RateLimit` on the wrapped `*APIError` | Yes, unless `Retry-After` is over 60 seconds |
| `*ConnectionError` | The API could not be reached. `Timeout()` reports a deadline | Yes |
| `*InvalidRequestError` | Bad arguments. No request was sent | No |
| `*WebhookVerificationError` | A webhook delivery failed `VerifyWebhook` | Not a request |

`*AuthError`, `*RateLimitError` and `*InsufficientCreditsError` wrap an `*APIError`, so `errors.As(err, &apiErr)` matches every non-2xx response.

An API error carries what the API said about the failure: `StatusCode`, `APICode`, `Type`, `Fix`, `Retryable`, `RetryAfter`, `RequestID`, `Param`, `Value` and `Reason`. Branch on the code, not on the message. This program sends a search that the API rejects with `400` and prints what the error carries:

```go main.go theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
package main

import (
	"context"
	"errors"
	"fmt"
	"log"

	"github.com/keenableai/keenable-sdk/go"
)

func main() {
	client, err := keenable.New(nil) // keyless: no API key needed to try it
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	// A path is not a valid ExcludeDomains entry, so the API returns 400.
	_, err = client.Search(context.Background(), "postmortem template",
		&keenable.SearchOptions{ExcludeDomains: []string{"example.com/blog"}})
	if err == nil {
		return
	}

	var apiErr *keenable.APIError
	if !errors.As(err, &apiErr) {
		log.Fatal(err)
	}
	fmt.Println(apiErr.StatusCode, apiErr.APICode)
	fmt.Println(apiErr.Param, apiErr.Value)
	if apiErr.Retryable != nil {
		fmt.Println("retryable:", *apiErr.Retryable)
	}
	fmt.Println(apiErr.Fix)
}
```

You see the status, the code, the rejected parameter and value, and the fix:

```text Output theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
400 invalid_parameter
exclude_domains example.com/blog
retryable: false
Fix "exclude_domains" and retry: paths are not supported; give only the host, such as example.com.
```

## Notes

* The Go SDK has no separate async client. `Search`, `Fetch` and every Monitors method take a `context.Context` as their first argument. Cancel the context to stop a call, including the wait between retries.
* To give a model web search as a tool, pass `keenable.Tools` to your chat completions client and run each call with `keenable.RunToolCall(ctx, client, name, arguments)`. See [Tool calling](https://docs.keenable.ai/tool-calling.md).
* Reuse one `Client` for the whole process.
* Monitors and webhook verification arrived in version 0.2.0. To see what the version you installed includes, read the [Go changelog](https://github.com/keenableai/keenable-sdk/blob/main/go/CHANGELOG.md).
* Source and package: [README](https://github.com/keenableai/keenable-sdk/blob/main/go/README.md), [pkg.go.dev](https://pkg.go.dev/github.com/keenableai/keenable-sdk/go).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.