Quickstart

The gateway gives you access to scraping, search, data, media, and compute services through a single API endpoint. Check the listed price before making a call. Failed calls are not charged.

Use a production API key for these examples. Keys in the OpenRecipe demo workspace are for preview only.

On this page 4 sections

Using the API
Category endpoints and vendor actions
Using the OpenAI SDK
Using MCP

There are three ways to integrate with the gateway, depending on where your agent or application runs:

Approach	Purpose
API	Call services directly from any language that can send HTTP requests.
OpenAI SDK	Drop-in replacement for LLM calls through the model router.
MCP	Let an agent find and call services during a task. See MCP.

Using the 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 structure. 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. The gateway 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 the gateway 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.