How do agents discover this API?

Root-site machine surfaces, Agent Card, OpenAPI, and MCP server metadata — the discovery documents an agent fetches before making any business call.

Discovery endpoints

Document	URL	Purpose
Root site	`GET https://hostrail.dev/`	Public landing page, markdown negotiation, and machine-facing links
llms.txt	`GET https://hostrail.dev/llms.txt`	Short machine-readable index for retrieval-oriented runtimes
llms-full.txt	`GET https://hostrail.dev/llms-full.txt`	Expanded factual hotel, room-plan, and policy context
Capabilities	`GET https://hostrail.dev/capabilities.json`	Supported flows, payment methods, machine surfaces, and limits
Coverage	`GET https://hostrail.dev/coverage.json`	Live hotel and city rollout status
API catalog	`GET https://hostrail.dev/.well-known/api-catalog`	RFC 9727 linkset for API discovery
ACP discovery	`GET https://hostrail.dev/.well-known/acp.json`	Agentic Commerce Protocol capability map for the current platform
OpenID configuration	`GET https://hostrail.dev/.well-known/openid-configuration`	OIDC-style auth discovery
OAuth authorization server	`GET https://hostrail.dev/.well-known/oauth-authorization-server`	RFC 8414 auth metadata
OAuth protected resource	`GET https://hostrail.dev/.well-known/oauth-protected-resource`	RFC 9728 resource metadata
Agent Card	`GET https://api.hostrail.dev/.well-known/agent-card.json`	Capabilities, flows, auth, and contracts
A2A Agent Card	`GET https://api.hostrail.dev/.well-known/agent.json`	Gemini and A2A discovery
AI Plugin manifest	`GET https://api.hostrail.dev/.well-known/ai-plugin.json`	ChatGPT-style plugin/app import
Error Catalog	`GET https://api.hostrail.dev/.well-known/errors`	All error codes with remediation and next_actions
Delegation Issuers	`GET https://api.hostrail.dev/.well-known/delegation-issuers`	Trusted JWT issuers for traveler delegation
OpenAPI Spec	`GET https://api.hostrail.dev/openapi.json`	Full request/response schemas (OpenAPI 3.1)
MCP Server Card	`GET https://hostrail.dev/.well-known/mcp/server-card.json`	Transport metadata for `https://mcp.hostrail.dev/mcp`

Recommended cold-start sequence:

GET https://hostrail.dev/llms.txt or GET https://hostrail.dev/capabilities.json → discover public machine surfaces
GET https://hostrail.dev/.well-known/api-catalog or GET https://hostrail.dev/.well-known/acp.json → understand standards-oriented discovery metadata
GET https://api.hostrail.dev/.well-known/agent-card.json → understand exact capabilities and contracts
GET https://api.hostrail.dev/.well-known/errors → build error lookup table
GET https://api.hostrail.dev/openapi.json → learn exact request/response schemas
If the runtime wants standards-based auth, fetch root-site OAuth metadata before the first protected call

Which discovery surface should I start from?

Runtime style	Best first document	Why
Retrieval-first assistant	`https://hostrail.dev/llms.txt`	Small, cheap machine index
Long-context planner	`https://hostrail.dev/llms-full.txt`	Richer factual grounding
Capability-aware agent	`https://hostrail.dev/capabilities.json`	Explicit supported flows and limitations
Standards-oriented agent	`https://hostrail.dev/.well-known/api-catalog`	Well-known linkset and auth metadata
Tool-calling runtime	`https://api.hostrail.dev/.well-known/agent-card.json`	Exact operation and auth contract
SDK / backend integration	`https://api.hostrail.dev/openapi.json`	Typed request and response schemas

ACP discovery

/.well-known/acp.json is a truthful summary of what the platform already supports today:

catalog
pricing
reservation
booking

It is intentionally narrower than a full ACP-native checkout stack. Use it as a high-level capability map, then switch to the Agent Card and OpenAPI for exact route-level integration detail.

Agent Card

The Agent Card lists every operation, canonical flows, and auth schemes:

Capabilities

Each capability declares method, href, idempotent, and next_rel (what to do next):

{
  "capabilities": [
    {
      "id": "search_availability",
      "method": "POST",
      "href": "/v1/search",
      "idempotent": false,
      "next_rel": "quote"
    }
  ]
}

Canonical flows

Flow	Steps	When to use
`book_a_room`	search → quote → hold → book	Golden path
`rebook_after_hold_expiry`	quote → hold → book	Recovery from `hold_expired` (410)
`cancel_with_refund`	get_booking → cancel	Guest cancellation
`abandon_and_retry`	release_hold → quote → hold → book	Agent changes selection mid-flow
`prove_what_happened`	get_booking → get_audit	Reconstruct booking timeline

Auth schemes

Header	Required	Purpose
`X-Tenant-Id`	API lane	Identifies the hotel tenant
`Authorization: Bearer <key>`	Protected calls	Agent credential or OAuth bearer
`X-Delegated-User: <jwt>`	Booking/cancel	Traveler consent JWT

OAuth-aware runtimes can discover the issuer and resource metadata from the root site, then mint client_credentials access tokens from https://api.hostrail.dev/oauth/token.

Pagination

The Agent Card declares the platform's pagination strategy under pagination:

{
  "pagination": {
    "strategy": "complete",
    "description": "All list endpoints return the complete result set in a single response..."
  }
}

Value	Meaning
`complete`	List endpoints return the full result set in one response. No `cursor`, `offset`, or `page` query params are accepted today.
`cursor`	Future: responses will carry `next` / `prev` links. Backward-compatible — agents ignoring the links continue to work on the first page.
`offset`	Reserved. Not in use.

Today's contract: agents do not need to implement pagination. Read pagination.strategy from the Agent Card at startup; if it flips to cursor, follow the next link from the response envelope until absent.

Error catalog endpoint

GET /.well-known/errors returns every error code the API can return. Agents should fetch this once at startup and build a local lookup table keyed on code.

See the full Error Catalog for all 44 codes.

Cache behavior

All discovery documents return Cache-Control: public, max-age=300. Delegation issuers use max-age=60.

How do agents discover this API?

On this page