sema-exa

Search the web and retrieve page contents through the Exa neural search API.

Install

sema pkg add sema-exa

Quick start

(import "sema-exa")

(define c (exa/client))                     ;; reads EXA_API_KEY from the env
(define r (exa/search c "latest research in language models"
                      {:num-results 3}))

(map (fn (x) (:title x)) (:results r))
;; => ("Sparse Attention ..." "Scaling Laws ..." "Retrieval-Augmented ...")

Auth setup

Get a key from https://dashboard.exa.ai/api-keys, then either export it:

export EXA_API_KEY="your-key"

or pass it explicitly:

(define c (exa/client {:api-key "your-key"}))

The key is sent as the x-api-key header and is never logged.

API

exa/client

(exa/client) / (exa/client {:api-key "..." :base-url "..."})

Builds a client map. The key falls back to EXA_API_KEY; if absent, it errors naming the env var.

(exa/client {:api-key "sk-..."})
;; => {:api-key "sk-..." :base-url "https://api.exa.ai"}

exa/search

(exa/search client query opts?)

Search the web for a query string. Options (keyword keys, all optional):

(exa/search c "AI coding agents 2026" {:type "neural" :num-results 5 :highlights #t})
;; => {:results (... ) :requestId "..." ...}

exa/get-contents

(exa/get-contents client urls opts?)

Retrieve page contents for a list of URLs. Options: :text (default #t), :highlights, :summary.

(exa/get-contents c (list "https://arxiv.org/abs/1706.03762") {:summary #t})
;; => {:results ({:url "https://arxiv.org/abs/1706.03762" :text "..." :summary "..."})}

exa/find-similar

(exa/find-similar client url opts?)

Find links similar to a URL. Options: :num-results, :exclude-source-domain (#t to drop results from the source URL's domain), :include-domains, :exclude-domains, plus the content flags from exa/search.

(exa/find-similar c "https://arxiv.org" {:num-results 5 :exclude-source-domain #t})
;; => {:results (...)}

exa/request

(exa/request client method path body)

Low-level request used by every wrapper. Sends body (a map, auto-JSON) to path, returns the decoded 2xx body, and raises on non-2xx with the method, path, status, and the API's error message.

(exa/request c "POST" "/search" {:query "hello" :contents {:text #t}})

Testing

sema tests.sema

Offline tests cover client construction, input validation, and error mapping. Live tests hit api.exa.ai and only run when EXA_API_KEY is set.

License

MIT