Docs menu

Other

GET/ask

Retrieve published website evidence

Ora GET convenience adapter for NLWeb list retrieval. Use POST for the canonical envelope and context. JSON is the default.

PARAMETERS
​
query
string
query
required
​
site
string
query
​
mode
string
query
​
streaming
boolean
query
​
limit
integer
query
​
query_id
string
query
RESPONSES
200NLWeb answer with retrieved evidence and source provenance, or application failure. -> NlwebAskResponse
400Malformed NLWeb request.
403Request Origin is not this website.
404Domain querying is disabled or no eligible publication exists.
406Accept does not allow the requested response transport.
429Shared query allowance exhausted.
503Query service or admission unavailable.
504Query deadline exceeded.
POST/ask

Retrieve published website evidence

NLWeb v0.55 synchronous list/conversational_search profile. JSON by default; prefer.streaming, or an Accept header preferring text/event-stream when prefer.streaming is absent, selects named SSE events. Unsupported modes/formats return HTTP 200 failure envelopes. No promises or await.

REQUEST BODYrequired
​
query
object
required
​
context
object
​
prefer
object
​
meta
object
RESPONSES
200NLWeb answer with retrieved evidence and source provenance, or application failure. -> NlwebAskResponse
400Malformed NLWeb request.
403Request Origin is not this website.
404Domain querying is disabled or no eligible publication exists.
406Accept does not allow the requested response transport.
429Shared query allowance exhausted.
503Query service or admission unavailable.
504Query deadline exceeded.
GET/api/agent-files/{domain}

Draft a domain's own agent discovery files (ard.json, ai-catalog.json, poppy.json)

Drafts the agent discovery files a domain publishes about itself: /.well-known/ard.json (Agentic Resource Discovery), /.well-known/ai-catalog.json (the same catalog at the AI Catalog Standard's path) and /.well-known/poppy.json (Personal Agent Protocol, Draft 0.2). Built from what ora already holds for the domain - no live crawl - so a domain ora never scanned still gets a valid minimal set (a catalog listing its website, a poppy.json for signed-out browsing) with scannedAt null. Every catalog entry is anchored to the domain itself (urn:air:<domain>:..., identity https://<domain>), never to ora, and carries only https URLs on the domain or its subdomains: anything the scan saw on another host is named in the file's notes instead. MCP servers are listed by their server card (the card the scan found, else the reserved <server-url>/server-card location, which the notes ask the owner to serve). The poppy.json is the minimal valid document; what ora saw that a fuller one could name (an OAuth issuer, MCP servers, an OpenAPI description) is listed in that file's notes. Pass ?include= for llms.txt, an edit of the site's robots.txt, an RFC 9727 api-catalog and draft MCP server cards. Review every file before publishing it. A leading www. is dropped, and any spelling other than the canonical domain answers 308 to /api/agent-files/<domain>. Sends Access-Control-Allow-Origin: * and is CDN-cached. Rate limited to 60 requests per minute per IP - returns 429 if exceeded. Also used by the generator page at directory.ora.ai/generate and by `npx ax generate-files <domain>`.

PARAMETERS
​
domain
string
path
required
A public host such as example.com (a full https:// URL without a path is also accepted). IPs, ports, paths and localhost are refused.
​
include
string
query
Extra files to draft beyond the default three, comma-separated: llms.txt, robots.txt (an edit of the site's current robots.txt that keeps every line and only adds what lets AI search crawlers and user-requested agents in, plus a Sitemap line; training crawlers and crawlers the owner blocked by name are never touched), api-catalog (RFC 9727), mcp-server-card (a draft card for each of the domain's MCP servers that has none, served on the server's own host). `all` asks for every one. Unknown names are ignored. Opt-in, so a client built for the three files never receives a path it cannot place. A file Ora cannot draft honestly (the site already publishes it, or Ora never read it) is left out and explained in the bundle `notes`.
RESPONSES
200The drafted files. -> AgentFilesBundle
308The domain was spelled differently from its canonical form (www., upper case, a trailing dot); Location is /api/agent-files/<domain>.
400INVALID_ARGUMENT - not a public domain. -> ArdErrorResponse
429RATE_LIMIT_EXCEEDED - max 60 requests per minute per IP. -> ArdErrorResponse
500INTERNAL_ERROR -> ArdErrorResponse
GET/api/web-bot-auth/directory

Get the Web Bot Auth signature agent card (public keys for verifying ora's crawler)

Returns ora's Web Bot Auth signature agent card: the client name, contact, stated purpose, and the public Ed25519 keys that verify HTTP Message Signatures (RFC 9421) on requests from ora's scanner. Bot-management verifiers resolve a signed request's `keyid` against the `kid` of a key here. Also served at /.well-known/http-message-signatures-directory via a rewrite, which is the path the specification fixes and the one verifiers fetch. `keys` is an empty array when no signing key is configured, so the endpoint is always valid JSON and can be probed unconditionally.

RESPONSES
200The signature agent card ({ client_name, homepage_uri, contact_email, purpose, keys: [...] }).