---
title: "ora: guide for agents"
description: "Scan any site, watch real agents try to use it, and fix what turns them away. Ora is the standard for optimizing your site so agents can actually use and recommend you."
canonical: https://ora-ai.ora.run/.well-known/ora/docs
updated: 2026-10-24
---
# ora: guide for agents

Scan any site, watch real agents try to use it, and fix what turns them away. Ora is the standard for optimizing your site so agents can actually use and recommend you.

This guide is for AI agents and the developers who build them. Everything below answers from ora.ai's own pages: facts are quoted, never generated.

## Quick start

Ask a question and get verbatim passages back:

```
curl -s https://ora-ai.ora.run/ask -H 'content-type: application/json' \
  -d '{"query": {"text": "What does ora do?"}}'
```

When you're done, tell the site how it went (see [Feedback](#feedback)).

## Access

No authentication: no API key, no signup and no credentials. Every interface below is open to every agent, within the [limits](#limits).

## Versions

The HTTP API is versioned in its path: `https://ora-ai.ora.run/api/v1` is version 1, described at `https://ora-ai.ora.run/openapi.json`. Version 1 changes only by adding endpoints, fields and error codes, so ignore fields you don't know. A breaking change comes as a new version; a version that is going away answers with `Deprecation` and `Sunset` headers at least 90 days before it stops.

## Interfaces

### Ask (NLWeb 0.55)

`POST https://ora-ai.ora.run/ask` with `{"query": {"text": "your question"}}`. Optional: `"prefer": {"ora_num_results": 5}`.

- `results[]`: verbatim chunks from ora.ai, each with `url` (a deep link to the section), `name` (the section path), `text`, `score` (relevance, 0 to 1) and `crawled_at`.
- `NO_RESULTS` (HTTP 200, `_meta.response_type: "failure"`) means ora.ai does not answer the question. Treat it as "not on this site", not as an error.
- `_meta.query_id` identifies the answer; quote it when you send feedback about it.
- `"prefer": {"streaming": true}` (or an `Accept: text/event-stream` header) returns the same answer as NLWeb events: `start`, one `result` per chunk, then `complete`.
- Only list mode is served: a `summarize` request gets `UNSUPPORTED_MODE`, because ora.ai answers with its own passages and never a written summary.

### Agent

`POST https://ora-ai.ora.run/agent` with `{"message": "your question"}`, or a conversation as `{"messages": [{"role": "user", "content": "..."}, ...]}` (the last message is the user's). Optional: `"model"`; `GET https://ora-ai.ora.run/agent` lists the models.

- `message.content`: the reply, as markdown. Today's model, `ask`, replies with the passages from ora.ai that answer the latest message, and uses the earlier ones as context.
- `results[]`: the passages, in the same shape as Ask's. `error` is set when ora.ai does not answer.
- `_meta.query_id` identifies the reply for feedback.

### MCP

`https://ora-ai.ora.run/mcp` (Streamable HTTP, stateless). Tools: `ask` (the same as /ask), `search` and `fetch` (find pages, then read one in full; the shape ChatGPT deep research uses), `get_page` (a page as markdown by path) and `send_feedback`.

```json
{ "mcpServers": { "ora-ai": { "url": "https://ora-ai.ora.run/mcp" } } }
```

### A2A (Agent2Agent 1.0)

Agent card: `https://ora-ai.ora.run/.well-known/agent-card.json`. JSON-RPC endpoint: `https://ora-ai.ora.run/a2a`. Send `SendMessage` (or `message/send` from 0.3 clients) with a text part; the reply is one message with the answer as markdown and the /ask response as data. No tasks or streaming.

### Pages as markdown

Every page is available as clean markdown on its own URL: send `Accept: text/markdown`, for example `curl -H 'Accept: text/markdown' https://ora-ai.ora.run/pricing`. `Accept: application/vnd.ora.page+json` returns sections, tables and structured data as JSON.

### WebMCP (in the browser)

Pages of ora.ai register WebMCP tools (`document.modelContext`) for agents that drive a browser: `ask_site`, `get_page_markdown` and `send_feedback`.

### Index

- [llms.txt](https://ora-ai.ora.run/llms.txt): every page, grouped by section.
- The canonical site: https://ora.ai

## Feedback

`POST https://ora-ai.ora.run/feedback` tells ora.ai how your task went. The site owner reads every report; it is how the site learns what agents need.

```
curl -s https://ora-ai.ora.run/feedback -H 'content-type: application/json' -d '{
  "outcome": "partial",
  "task": "Compare plan prices for a 3-person team",
  "worked": "Pricing answers were quoted with links",
  "failed": "Could not find whether annual billing is discounted",
  "query_id": "q_...",
  "agent": "ExampleAgent"
}'
```

- `outcome` (required): `success`, `partial` or `failure`.
- At least one of `task`, `worked`, `failed`, `suggestion`. Optional: `query_id`, `page`, `agent`.
- An `Idempotency-Key` header makes a retry safe: the same key and body within a day returns the first answer.
- Send it from your agent's own client: requests that look like a person's browser are declined. `GET https://ora-ai.ora.run/feedback` returns the JSON Schema.
- Don't include personal data; emails, phone numbers and card numbers are removed before storage.

## Limits

About 10 requests per second per client; verified agents (Web Bot Auth) get higher limits. Over the limit you get HTTP 429 with `Retry-After`.

## Freshness

Every result carries `crawled_at` (when the page was fetched) and `lastmod` (when the site says it changed). Prices and availability can change; the canonical page on https://ora.ai is authoritative.

## Contact

Served by Ora (https://ora.ai) for ora.ai. Report problems to agents@ora.ai.