exa

Documentation

Overview

Package exa is a minimal REST client for Exa Search (https://api.exa.ai). No third-party SDK — stdlib HTTP only.

Index

• type Client
  • func NewClient(apiKey string) *Client
  • func (c *Client) Contents(ctx context.Context, req ContentsRequest) (*ContentsResponse, error)
  • func (c *Client) Search(ctx context.Context, req SearchRequest) (*SearchResponse, error)
• type ContentsOptions
• type ContentsRequest
• type ContentsResponse
• type ContentsURLStatus
• type HighlightsOptions
• type SearchRequest
• type SearchResponse
• type SearchResult
• type SynthesisOutput
• type TextOptions

Types

type Client

type Client struct {
	APIKey     string
	BaseURL    string
	HTTPClient *http.Client
}

Client calls Exa’s Search and Contents APIs.

func NewClient

func NewClient(apiKey string) *Client

NewClient builds a client for the given API key.

func (*Client) Contents

func (c *Client) Contents(ctx context.Context, req ContentsRequest) (*ContentsResponse, error)

Contents performs POST /contents for known URLs (or prior result ids). Provide at least one of URLs or IDs.

func (*Client) Search

func (c *Client) Search(ctx context.Context, req SearchRequest) (*SearchResponse, error)

Search performs POST /search. req.Query must be non-empty.

type ContentsOptions

type ContentsOptions struct {
	Highlights  any  `json:"highlights,omitempty"` // bool or HighlightsOptions
	Text        any  `json:"text,omitempty"`       // bool or TextOptions
	MaxAgeHours *int `json:"maxAgeHours,omitempty"`
}

ContentsOptions controls extraction and freshness on each result.

type ContentsRequest

type ContentsRequest struct {
	URLs        []string `json:"urls,omitempty"`
	IDs         []string `json:"ids,omitempty"`
	Text        any      `json:"text,omitempty"`       // bool or TextOptions
	Highlights  any      `json:"highlights,omitempty"` // bool or HighlightsOptions
	MaxAgeHours *int     `json:"maxAgeHours,omitempty"`
}

ContentsRequest is POST /contents (known URLs or prior result ids). Provide urls or ids, not both. Content options are top-level (not nested).

type ContentsResponse

type ContentsResponse struct {
	RequestID string              `json:"requestId"`
	Results   []SearchResult      `json:"results"`
	Statuses  []ContentsURLStatus `json:"statuses,omitempty"`
}

ContentsResponse is the body for a successful POST /contents call.

type ContentsURLStatus

type ContentsURLStatus struct {
	ID     string `json:"id"`
	Status string `json:"status"` // success | error
	Source string `json:"source,omitempty"`
	Error  *struct {
		Tag            string `json:"tag,omitempty"`
		HTTPStatusCode *int   `json:"httpStatusCode,omitempty"`
	} `json:"error,omitempty"`
}

ContentsURLStatus reports per-URL fetch outcome from /contents.

type HighlightsOptions

type HighlightsOptions struct {
	Query         string `json:"query,omitempty"`
	MaxCharacters int    `json:"maxCharacters,omitempty"`
}

HighlightsOptions steers highlight extraction.

type SearchRequest

type SearchRequest struct {
	Query              string           `json:"query"`
	Type               string           `json:"type,omitempty"`
	NumResults         int              `json:"numResults,omitempty"`
	Category           string           `json:"category,omitempty"`
	IncludeDomains     []string         `json:"includeDomains,omitempty"`
	ExcludeDomains     []string         `json:"excludeDomains,omitempty"`
	StartPublishedDate string           `json:"startPublishedDate,omitempty"`
	EndPublishedDate   string           `json:"endPublishedDate,omitempty"`
	UserLocation       string           `json:"userLocation,omitempty"`
	SystemPrompt       string           `json:"systemPrompt,omitempty"`
	Contents           *ContentsOptions `json:"contents,omitempty"`
}

SearchRequest is the subset of POST /search we use for agent tools. JSON names match Exa’s camelCase wire format.

type SearchResponse

type SearchResponse struct {
	RequestID string           `json:"requestId"`
	Results   []SearchResult   `json:"results"`
	Output    *SynthesisOutput `json:"output,omitempty"`
}

SearchResponse is the JSON body for a successful non-streaming /search call.

type SearchResult

type SearchResult struct {
	Title         string   `json:"title"`
	URL           string   `json:"url"`
	PublishedDate string   `json:"publishedDate,omitempty"`
	Author        string   `json:"author,omitempty"`
	ID            string   `json:"id,omitempty"`
	Text          string   `json:"text,omitempty"`
	Highlights    []string `json:"highlights,omitempty"`
	Summary       string   `json:"summary,omitempty"`
}

SearchResult is one hit from Exa.

type SynthesisOutput

type SynthesisOutput struct {
	Content json.RawMessage `json:"content,omitempty"`
}

SynthesisOutput holds optional deep-search / schema synthesis. Content may be a string or a JSON object depending on outputSchema.

type TextOptions

type TextOptions struct {
	MaxCharacters int    `json:"maxCharacters,omitempty"`
	Verbosity     string `json:"verbosity,omitempty"` // compact | standard | full
}

TextOptions steers full-page text extraction.