Choose an endpoint
If this is your first request, follow the quickstart.
To control how old a cached page can be, set
max_age on Contents.
Base URL and authentication
Every request goes tohttps://api.valyu.ai and carries your API key in the x-api-key header. Request and response bodies are JSON.
cURL
x-api-key, not Authorization: Bearer. Keep the key on the server; do not expose it in browser code.
Errors
Error bodies always includeerror. Search, Contents and Datasources errors usually add "success": false. Requests rejected before they reach an endpoint (a missing or disabled key, or a rate limit) return error and message, and DeepResearch errors return error only. Some errors add a machine-readable code; branch on the status and code rather than the message text.
Search and Contents return
206 when the request succeeded only in part, for example when some sources or URLs failed. Treat it as a success and inspect the individual results.
Warnings
A request that succeeds with something skipped or adjusted, such as a named dataset outside your plan, returns awarnings list of {type, message, detail} objects. A plan limit never fails a request that can still return something. See warnings for every type.
Rate limits
Limits apply per organisation and per endpoint. Search, Contents, and creating or polling DeepResearch tasks each have their own limit. The limit is lower on cheaper plans and higher on paid plans. See pricing and plans for the rate on each plan. There is no daily quota. A request over the limit returns429 Too Many Requests with a Retry-After header, in seconds. The body names the limit you hit and how to raise it:
Wait
retry_after seconds, then retry with backoff. A 429 is temporary and clears on its own: it is not a billing or credit problem, and a rate-limited request is never charged.
Pricing
You pay per use from your credit balance. Search is priced per result returned, Contents per extracted URL, and DeepResearch per task by mode. Cost fields in a response (price, total_deduction_dollars, total_cost_dollars, cost) report what each request was charged. See pricing for rates and plans.
Versioning
All endpoints are under/v1. New optional parameters and response fields are added within v1, so ignore fields your client doesn’t recognise. Changes are announced in the API changelog.
OpenAPI specification
Use the OpenAPI 3.0 specification to inspect request and response shapes, generate a client or import requests into an API tool. Open the OpenAPI specification to view or save the raw JSON.1
Import the specification
In Postman, choose Import and enter
https://docs.valyu.ai/api-reference/openapi.json.2
Configure authentication
Set the API key used by the imported collection’s
x-api-key header. Keep the value in a private environment variable.3
Send a small request
Start with Search and inspect the returned results. Use the async lifecycle documented for research tasks and extraction jobs.
Machine-readable documentation
Documentation index
Find the guide or reference page for a particular integration task.
Documentation MCP
Search the documentation from an MCP client.
Page Markdown
Append
.md to a documentation URL to retrieve its text.