Skip to main content
The Keenable Go SDK gives your code web search, page fetch and Monitors. This page covers version 0.2.0, the latest release on the Go module proxy. For the other languages, see TypeScript, Python and Rust. For what all four SDKs share, see SDKs.

Install

Install the package. The SDK needs Go 1.22 or newer:
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 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: 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. This program runs one keyless search and prints the top 3 results as a citable block:
main.go
Save it as main.go and run go run .. You see one [n] Title (url) header per result, followed by the page text. 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. To change how much text the citable block holds, see Context size.

Fetch

This program fetches one page without a key and prints its title and the first 300 characters of its markdown:
main.go
Pass the fetch options through FetchWithOptions and the MaxChars, Live and Prompt fields of keenable.FetchOptions. Each one is described under Fetch 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:
main.go
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. 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.

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. 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.

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. *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:
main.go
You see the status, the code, the rejected parameter and value, and the fix:
Output

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.
  • 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.
  • Source and package: README, pkg.go.dev.