Developer Quickstart

Get a tenant credential, discover the auth metadata, and make your first protected call.

Prerequisites

An agent credential or OAuth client configured for your tenant
A tenant UUID for the hotel you're integrating with
curl or any HTTP client

1. Verify connectivity

curl https://api.agenthotel.dev/healthz

2. Discover the contracts and auth metadata

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 '.'
curl https://api.agenthotel.dev/openapi.json | jq '.info'

Import the OpenAPI spec into Postman, Insomnia, or any compatible client.

3. Make your first authenticated request

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

If you prefer the OAuth lane, mint a token first:

curl -X POST https://api.agenthotel.dev/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=<agent-id>&client_secret=<agent-secret>"

4. Run the golden path

# export BASE=https://api.agenthotel.dev
# export TENANT_ID=<tenant-uuid>
# export API_KEY=<hsk_live_or_test_secret>

# Search
curl -X POST $BASE/v1/search \
  -H "X-Tenant-Id: $TENANT_ID" -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination":"test","check_in":"2026-06-01","check_out":"2026-06-03","guests":{"adults":2,"children":[]}}'

# Quote (use IDs from search results)
curl -X POST $BASE/v1/quotes \
  -H "X-Tenant-Id: $TENANT_ID" -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hotel_id":"<id>","room_type_id":"<id>","rate_plan_id":"<id>","stay":{"check_in":"2026-06-01","check_out":"2026-06-03"},"guests":{"adults":2,"children":[]}}'

# Hold
curl -X POST $BASE/v1/holds \
  -H "X-Tenant-Id: $TENANT_ID" -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: test-hold-001" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"<quote_id>"}'

# Confirm
curl -X POST $BASE/v1/bookings \
  -H "X-Tenant-Id: $TENANT_ID" -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: test-book-001" \
  -H "Content-Type: application/json" \
  -d '{"hold_id":"<hold_id>","quote_id":"<quote_id>","guest":{"primary":{"full_name":"Test","email":"test@example.com","phone":"+84900000000"}},"payment":{"method":"card","provider_token":"tok_test","billing_country":"VN"}}'

5. Connect via MCP

{
  "mcpServers": {
    "hospitality-commerce": {
      "url": "https://mcp.agenthotel.dev/mcp",
      "transport": "streamable-http"
    }
  }
}

Use the same Authorization: Bearer ... lane for MCP that you use for protected API calls.