Agent Quickstart

Step 1: Discover the API

Start with the public machine surfaces on the root site:

curl https://agenthotel.dev/.well-known/api-catalog | jq '.'
curl https://agenthotel.dev/.well-known/acp.json | jq '.'
curl https://agenthotel.dev/.well-known/openid-configuration | jq '.'

Then fetch the Agent Card — a machine-readable manifest that describes all capabilities, flows, auth schemes, and contracts:

curl https://api.agenthotel.dev/.well-known/agent-card.json | jq '.'

The Agent Card contains:

• capabilities[] — every operation with method, href, idempotent, and next_rel
• flows[] — canonical step sequences (book_a_room, cancel_with_refund, etc.)
• contracts.envelope — success and error field lists
• contracts.idempotency — which endpoints accept Idempotency-Key
• contracts.delegation — JWT requirements for traveler-context routes

Also fetch the error catalog to build a local lookup table:

curl https://api.agenthotel.dev/.well-known/errors | jq '.'

Returns all error codes with status, remediation, next_actions, and docs_url.

Use /.well-known/acp.json as the high-level commerce capability map if your runtime starts from ACP-style discovery. Then switch to the Agent Card and OpenAPI for exact request contracts.

Step 2: Authenticate

Public discovery does not require a credential. Protected API and MCP calls do.

You have two supported execution lanes:

1. Operator-managed agent secret:
   • Authorization: Bearer hsk_live_...
2. OAuth access token minted via client_credentials:
   • POST https://api.agenthotel.dev/oauth/token
   • Authorization: Bearer eyJ...

Direct API calls still require the tenant context header:

curl -H "X-Tenant-Id: <tenant-uuid>" \
     -H "Authorization: Bearer <agent-api-key>" \
     https://api.agenthotel.dev/v1/properties

If your runtime is MCP-native, it can call https://mcp.agenthotel.dev/mcp with the same bearer token family instead of speaking REST directly.

Step 3: Search availability

curl -X POST https://api.agenthotel.dev/v1/search \
  -H "X-Tenant-Id: <tenant-uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "Ho Chi Minh City",
    "check_in": "2026-05-01",
    "check_out": "2026-05-03",
    "guests": { "adults": 2, "children": [] }
  }'

Response carries next_actions[rel=quote] — follow it to create a quote for the selected room.

Treat quote output, not published markdown or hotel page copy, as the current source of truth for price and cancellation terms.

Step 4: Create a quote

Lock a price and policy snapshot for a specific room + rate plan.

curl -X POST https://api.agenthotel.dev/v1/quotes \
  -H "X-Tenant-Id: <tenant-uuid>" \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "hotel_id": "prop_abc",
    "room_type_id": "rt_123",
    "rate_plan_id": "rp_456",
    "stay": { "check_in": "2026-05-01", "check_out": "2026-05-03" },
    "guests": { "adults": 2, "children": [] }
  }'

The quote freezes pricing and cancellation policy. The quote has a TTL — hold before expires_at. If quote_expired (410) is returned, call POST /v1/quotes again.

Step 5: Hold inventory

Reserve rooms for a short window (default 15 minutes).

curl -X POST https://api.agenthotel.dev/v1/holds \
  -H "X-Tenant-Id: <tenant-uuid>" \
  -H "Authorization: Bearer <key>" \
  -H "Idempotency-Key: hold_attempt_1" \
  -H "Content-Type: application/json" \
  -d '{ "quote_id": "q_789" }'

Idempotent: retries with the same Idempotency-Key return the cached response.

Possible errors:

• quote_expired (410) → requote with POST /v1/quotes
• allocation_failed (409) → inventory changed, search alternatives
• allotment_exhausted (409) → daily ceiling reached, try different room/date

Step 6: Confirm booking

curl -X POST https://api.agenthotel.dev/v1/bookings \
  -H "X-Tenant-Id: <tenant-uuid>" \
  -H "Authorization: Bearer <key>" \
  -H "Idempotency-Key: book_attempt_1" \
  -H "X-Delegated-User: <traveler-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "hold_id": "h_abc",
    "quote_id": "q_789",
    "guest": {
      "primary": { "full_name": "Nguyen Van A", "email": "a@example.com", "phone": "+84901234567" }
    },
    "payment": {
      "method": "card",
      "provider_token": "tok_stripe_xxx",
      "billing_country": "VN"
    }
  }'

Idempotent: retries return the cached result — including sealed business errors like payment_failed.

Delegation required: X-Delegated-User JWT must be present. Without it → delegation_required (401).

Success response includes a signed receipt for auditability. Keep it — verify later via POST /v1/receipts/verify.