SDKs Reference
Practical naming and surface guide for exa-py and exa-js.
Canonical Docs Links
- Base docs URL:
https://exa.ai/docs - Python SDK spec:
/sdks/python-sdk-specification - TypeScript SDK spec:
/sdks/typescript-sdk-specification - Python README:
https://github.com/exa-labs/exa-py - JavaScript README:
https://github.com/exa-labs/exa-js
Contents
- Shared guidance
- Python SDK
- TypeScript SDK
- Raw HTTP vs SDK shapes
- Critical pitfalls
Shared Guidance
- Install the latest SDK release with the package manager so it resolves the latest release and all SDK surfaces will be available.
- Use official docs as canonical for behavior
- Use SDK docs and repos to confirm method names, casing, and helper ergonomics
- Distinguish request-shape casing carefully:
- raw HTTP:
camelCase - Python core endpoint methods:
snake_case - TypeScript SDK:
camelCase
- raw HTTP:
- Current Python Monitors and Websets docs often show
params={...}dicts that keep API-shaped field names such asnumResults. Treat those resource families as a surface-specific exception rather than forcing the core search/contents casing rule onto every SDK namespace.
Python SDK (exa-py)
Install:
pip install exa-pyInstantiate:
from exa_py import Exa
exa = Exa(api_key="YOUR_EXA_API_KEY")Current Primary Methods
search(...)stream_search(...)get_contents(...)answer(...)stream_answer(...)agent.runs.create(...)agent.runs.get(...)agent.runs.list(...)agent.runs.poll_until_finished(...)openai.web_search(),anthropic.web_search(),tools.web_search()(LLM tool helpers that ask the model forqueryandobjective)monitors.*websets.*
Naming Rules for Core Endpoint Methods
Use snake_case everywhere, including nested dict keys:
result = exa.search(
"latest AI funding rounds",
contents={"highlights": True},
output_schema={
"type": "object",
"properties": {"summary": {"type": "string"}},
"required": ["summary"]
}
)Documented Default-Contents Caveat
Current Python SDK docs explicitly say search() returns text contents with a 10,000-character default unless you disable contents. If you do not want that default behavior, pass contents=False.
Helper Methods
The Python SDK's search_and_contents(...) helper is deprecated. Use search(...), which returns contents, and get_contents(...).
Monitors and Websets
monitors and websets methods take a params dict shaped like the API request body, with camelCase keys, instead of snake_case keyword arguments. Follow those resources' docs rather than the naming rules above.
TypeScript SDK (exa-js)
Install:
npm install exa-jsInstantiate:
import Exa from "exa-js";
const exa = new Exa();Current Primary Methods
search(...)streamSearch(...)getContents(...)answer(...)streamAnswer(...)agent.runs.create(...)agent.runs.get(...)agent.runs.list(...)agent.runs.pollUntilFinished(...)openai.webSearch(),anthropic.webSearch(),tools.webSearch()(LLM tool helpers that ask the model forqueryandobjective)monitors.*websets.*
Naming Rules
Use camelCase everywhere:
const result = await exa.search("latest AI funding rounds", {
contents: { highlights: true },
outputSchema: {
type: "object",
properties: { summary: { type: "string" } },
required: ["summary"]
}
});Helper Methods
Examples and SDK source may show helpers such as searchAndContents(...). They are valid helpers, but they are not the primary pattern in this skill. Prefer understanding the underlying endpoint family first.
Raw HTTP vs SDK Shapes
| Concern | Raw HTTP | Python SDK | TypeScript SDK |
|---|---|---|---|
| Results count | numResults |
num_results |
numResults |
| Output schema | outputSchema |
output_schema |
outputSchema |
| System prompt | systemPrompt |
system_prompt |
systemPrompt |
| Text cap | maxCharacters |
max_characters |
maxCharacters |
| Freshness | maxAgeHours |
max_age_hours |
maxAgeHours |
| Search contents | nested contents |
nested contents with snake_case keys |
nested contents with camelCase keys |
| Contents endpoint text | top-level text |
top-level text |
top-level text |
Critical Pitfalls
- Do not paste raw JSON keys into core Python SDK methods as top-level keyword arguments;
numResults=andoutputSchema=raiseTypeError. Nested dict keys tolerate either casing, but staysnake_casefor consistency. - Do not assume helper methods define the canonical API shape.
- Remember the Python SDK's documented
search()default-contents behavior.