AI Query

Ask a natural-language question about a website. Orsa scrapes the homepage, builds a context payload from the cached brand record + page markdown, and answers via Claude. Returns a free-form text response — prompt for JSON output explicitly if you want structured data.

Endpoint: POST /v1/brand/ai/query Credits: 20 per request

Request Body

Field	Type	Required	Description
`domain`	string	Yes	Domain to analyze
`data_to_extract`	string	Yes	Natural-language question or extraction prompt

{
  "domain": "stripe.com",
  "data_to_extract": "Return the pricing plans as a JSON array with name, price, and key features."
}

Response Schema

{
  "data": {
    "domain": "stripe.com",
    "prompt": "Return the pricing plans as a JSON array with name, price, and key features.",
    "result": "[\n  { \"name\": \"Integrated\", \"price\": \"2.9% + 30¢\", \"features\": [...] }\n]",
    "usage": {
      "input_tokens": 1240,
      "output_tokens": 312
    }
  },
  "_meta": { "timing": { "llm_ms": 2840, "total_ms": 4120 } }
}

Code Examples

cURL

curl -X POST "https://api.orsa.dev/v1/brand/ai/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "stripe.com",
    "data_to_extract": "Return the pricing plans as a JSON array."
  }'

TypeScript

const { data } = await client.ai.query({
  domain: 'stripe.com',
  dataToExtract: 'Return the pricing plans as a JSON array.',
});
 
console.log(data.result);               // model answer (string)
console.log(data.usage.input_tokens);

Python

res = client.ai.query(
    domain="stripe.com",
    data_to_extract="Return the pricing plans as a JSON array.",
)
 
print(res["data"]["result"])
print(res["data"]["usage"]["input_tokens"])

Error Codes

Code	Status	Description
`INPUT_VALIDATION_ERROR`	400	Missing `domain` or `data_to_extract`
`UNAUTHORIZED`	401	Missing or invalid API key
`SERVICE_UNAVAILABLE`	503	Anthropic key not configured on the server
`RATE_LIMITED`	429	Rate limit exceeded
`USAGE_EXCEEDED`	402	Insufficient credits

Tips

result is always a string. If you want structured data, ask the model to return JSON explicitly and parse it client-side.
The system prompt is cached (5-minute Anthropic ephemeral cache), so repeat calls within that window only pay for the user-message tokens.
The model has access to the cached brand record (title, description, industries, socials, contact info) plus a Readability-stripped markdown snapshot of the homepage.
Be specific in data_to_extract — “pricing plans with prices” works better than “tell me about the company.”

Transaction Identifier Extract Products