vaaya / docs / reference

Quickstart

Vaaya gives you access to scraping, search, data, media, and compute services through a single API endpoint. Every call is billed at the provider’s list price, and failed calls are not charged.

There are three ways to integrate with Vaaya, depending on how much control you want:

Using the Vaaya API

Send HTTP requests directly to the /api/run/{service}/{action} endpoint. It works with any language or framework. Get a key at /api-keys.

curl -X POST https://vaaya.ai/api/run/scraping/scrape \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}'

Python:

import requests

response = requests.post(
  url="https://vaaya.ai/api/run/scraping/scrape",
  headers={"Authorization": "Bearer <VAAYA_API_KEY>"},
  json={"url": "https://example.com", "formats": ["markdown"]},
)
print(response.json()["data"])

TypeScript:

const response = await fetch('https://vaaya.ai/api/run/scraping/scrape', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <VAAYA_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://example.com', formats: ['markdown'] }),
});
const result = await response.json();
console.log(result.data);

Every response uses the same envelope. charged_cents is what the call actually cost. Failed calls are not charged.

{
  "ok": true,
  "data": { "provider": "crw", ... },
  "charged_cents": 1,
  "balance_remaining_cents": 199,
  "transaction_id": "..."
}

Category endpoints and vendor actions

scraping/scrape is a category endpoint. It gives you one request shape that works across scraping providers. Vaaya picks the provider unless you pin one with provider. The response names the provider that served the call in data.provider.

Vendor actions work the same way. Call firecrawl/scrape, exa/search, or e2b/create_session with the vendor’s own params. Substitute services and actions freely. The endpoint shape does not change. Explore the catalog at /catalog, or programmatically via POST /api/run/vaaya/discover (free). A GET on any action URL returns its schema and price.

Using the OpenAI SDK

For LLM calls, point the OpenAI SDK at Vaaya as a drop-in replacement. The model is a parameter. See LLMs for the model list.

from openai import OpenAI

client = OpenAI(
  base_url="https://vaaya.ai/api/llm/v1",
  api_key="<VAAYA_API_KEY>",
)

Using MCP

Add the hosted MCP server to your client and authenticate with the same key:

{ "mcpServers": { "vaaya": {
    "url": "https://vaaya.ai/mcp",
    "headers": { "Authorization": "Bearer vaaya_sk_..." }
} } }

See MCP for OAuth setup in interactive clients. See Errors & billing for the error contract.