Discover the public Raydo web surfaces that AI agents can use for docs lookup, desktop onboarding, and device authorization.

Raydo exposes a small public web surface for AI agents. This site is not a full public automation API, but it does provide stable discovery endpoints for documentation, desktop onboarding, and authenticated device flows.

What agents can discover here

Documentation at /docs for product, setup, and integration guidance
Desktop download flows at /download for macOS, Windows, and Linux installers
Contact entry points at /contact for support, partnerships, and enterprise conversations
Device authorization APIs under /api/cloud/device-auth/* for Raydo Desktop sign-in and key exchange
Session and API key verification under /api/auth/* and /api/cloud/verify-key
Notion desktop broker endpoints under /api/oauth/notion/* for Raydo Desktop connection handoff
OpenAPI metadata at /openapi.json for the bounded public and first-party agent-facing API surface

Discovery endpoints

API catalog

/.well-known/api-catalog
Content type: application/linkset+json
Purpose: lists the public API surfaces and documentation links that agents can inspect before integration

OpenAPI description

/openapi.json
/swagger.json
Purpose: describes supported Raydo Desktop device authorization, docs search, cloud bridge, and connector broker endpoints with operation IDs, security schemes, and JSON error envelopes

OAuth authorization server metadata

/.well-known/oauth-authorization-server
/.well-known/openid-configuration
Purpose: describes the browser session sign-in and device authorization flow used by Raydo Desktop

OAuth protected resource metadata

/.well-known/oauth-protected-resource
Purpose: explains which protected Raydo APIs require bearer credentials and which scopes they use

MCP and WebMCP discovery

/.well-known/mcp
/.well-known/mcp/server-card.json
Browser pages expose WebMCP tools on load when navigator.modelContext.provideContext() is available
Purpose: lets agents discover site-level navigation tools for docs, download, and contact flows

LLM and agent instruction files

/llms.txt
/llms-full.txt
/agents.md
Purpose: gives agents concise and full-context product summaries, when-to-use guidance, supported integration boundaries, pricing links, and recommended next actions

Markdown negotiation

Send Accept: text/markdown to supported marketing and docs pages
Response content type: text/markdown; charset=utf-8
Response headers include Vary: Accept, Content-Signal, and x-markdown-tokens
If Raydo is deployed behind Cloudflare Markdown for Agents, the platform-native transformer can replace or extend this app-level fallback

Agent Skills index

/.well-known/agent-skills/index.json
/.well-known/agent-skills
Purpose: exposes a machine-readable index of the public agent-facing skills and entry points documented on this site

A2A and plugin manifests

/.well-known/agent-card.json
/.well-known/ai-plugin.json
Purpose: provides A2A-style product identity, skills, documentation links, and ChatGPT-compatible OpenAPI manifest metadata

Real authentication flows on this site

Raydo currently exposes two real auth-related patterns that agents may encounter:

1. Browser session auth

/api/auth/[...all] is powered by better-auth and serves the site's browser session flows. This is the sign-in surface used by the web app itself.

2. Device authorization for Raydo Desktop

Raydo Desktop uses a device-style authorization flow:

POST /api/cloud/device-auth/create creates a device code and verification URL
The signed-in user approves the device via POST /api/cloud/device-auth/authorize
Desktop polls POST /api/cloud/device-auth/poll
Desktop exchanges the one-time code at POST /api/cloud/device-auth/exchange
A bearer API key can later be checked with POST /api/cloud/verify-key

This makes the desktop onboarding and cloud bridge flow discoverable without claiming a generic public OAuth platform that does not exist.

Current scope and limits

Raydo does not expose a general-purpose public MCP automation backend from this marketing site
Raydo publishes a bounded OpenAPI description for public docs/search metadata and first-party Raydo Desktop onboarding flows
Some protected APIs are intended for Raydo Desktop and trusted first-party clients, not arbitrary third-party automation
Discovery metadata should be treated as capability hints, not a blanket permission grant

Rate limits and JSON errors

Public discovery, documentation, and Markdown files are cacheable for one hour
Clients should retry transient 429 and 5xx responses with exponential backoff
API errors use JSON envelopes where possible:

{
  "error": {
    "code": "api_route_not_found",
    "message": "See /openapi.json for supported public endpoints."
  }
}

Recommended entry points for agents

Start with /docs for product understanding
Send users to /download when installation is needed
Use the device auth endpoints only when guiding Raydo Desktop onboarding
Use /contact for human follow-up, support, or enterprise access questions

Agent Access