{
  "name": "Golda Trip Agent Commerce",
  "description": "Machine-readable capability manifest for the Golda Trip agent API. This file is the single source of truth: if a capability is not listed here with status \"live\", it does not exist yet. The human page /{locale}/agents renders from this exact file.",
  "version": "0.6.0",
  "updated_at": "2026-10-12",
  "api_base": "https://goldatrip.com/api/v1",
  "auth": {
    "type": "api_key",
    "header": "X-API-Key",
    "idempotency_header": "Idempotency-Key",
    "idempotency_policy": "Required on all write tools. Replaying the same key returns the original result instead of creating a duplicate.",
    "key_policy": "Scoped keys minted by GoldaTrip per integrator — request only the scopes you need."
  },
  "scopes": [
    {
      "id": "catalog.read",
      "description": "Read the published tour catalog: products, options, schedules, pickup zones."
    },
    {
      "id": "availability.read",
      "description": "Check authoritative real-time availability for products and service dates."
    },
    {
      "id": "pricing.read",
      "description": "Get server-computed price estimates. Always non-binding; quotes are the binding document."
    },
    {
      "id": "itinerary.create",
      "description": "Build and validate draft day plans (itineraries) against hard rules — no customer data involved."
    },
    {
      "id": "itinerary.read",
      "description": "Read itineraries the integration created or owns — frame, items, validation state."
    },
    {
      "id": "itinerary.write",
      "description": "Create, update and delete server-persisted itineraries shared with the website planner."
    },
    {
      "id": "concierge.plan",
      "description": "Ask the server-side AI concierge to plan a trip: it searches, validates and quotes via the same agent tools — output is always server-verified."
    },
    {
      "id": "quote.create",
      "description": "Create and read server-priced, time-bounded quotes — the binding commercial documents."
    },
    {
      "id": "booking.create",
      "description": "Convert an approved quote and inventory hold into a confirmed booking. Not issued yet — ships with M3."
    },
    {
      "id": "booking.read",
      "description": "Read bookings the integration created, public-safe fields only. Not issued yet — ships with M3."
    },
    {
      "id": "booking.modify",
      "description": "Reschedule or cancel an existing booking under operator rules. Not issued yet — ships with M5."
    },
    {
      "id": "payment.initiate",
      "description": "Start a traveler-completed payment via an approval-scoped hosted link. Not issued yet — ships with M4."
    }
  ],
  "tools": [
    {
      "name": "search_tours",
      "purpose": "Search the published tour catalog with hard filters (traveller ages, pickup zone, dates) and get availability-checked candidates.",
      "method": "POST",
      "path": "/agent/tours/search",
      "scope": "catalog.read",
      "risk": "read",
      "requires_user_approval": false,
      "milestone": null,
      "status": "live"
    },
    {
      "name": "get_product",
      "purpose": "Fetch one product's normalized detail: options, schedule summary, cancellation policy, suitability rules.",
      "method": "GET",
      "path": "/agent/products/{id_or_slug}",
      "scope": "catalog.read",
      "risk": "read",
      "requires_user_approval": false,
      "milestone": null,
      "status": "live"
    },
    {
      "name": "check_availability",
      "purpose": "Authoritative availability per product/date: status, remaining quantity, booking cutoff, reason codes.",
      "method": "POST",
      "path": "/agent/availability/check",
      "scope": "availability.read",
      "risk": "read",
      "requires_user_approval": false,
      "milestone": null,
      "status": "live"
    },
    {
      "name": "price_preview",
      "purpose": "Server-computed price estimate for a candidate item. Explicitly non-binding.",
      "method": "POST",
      "path": "/agent/pricing/preview",
      "scope": "pricing.read",
      "risk": "read",
      "requires_user_approval": false,
      "milestone": null,
      "status": "live"
    },
    {
      "name": "validate_itinerary",
      "purpose": "Deterministic validation of a draft day plan: time conflicts, transfer presence, flight buffers, age rules.",
      "method": "POST",
      "path": "/agent/itineraries/validate",
      "scope": "itinerary.create",
      "risk": "read",
      "requires_user_approval": false,
      "milestone": null,
      "status": "live"
    },
    {
      "name": "create_quote",
      "purpose": "Create a server-priced, time-bounded quote — the binding commercial document. Idempotency-Key required.",
      "method": "POST",
      "path": "/agent/quotes",
      "scope": "quote.create",
      "risk": "commercial_write",
      "requires_user_approval": false,
      "milestone": null,
      "status": "live"
    },
    {
      "name": "get_quote",
      "purpose": "Read one quote this integration created: items, price, expiry, status.",
      "method": "GET",
      "path": "/agent/quotes/{id}",
      "scope": "quote.create",
      "risk": "read",
      "requires_user_approval": false,
      "milestone": null,
      "status": "live"
    },
    {
      "name": "hold_inventory",
      "purpose": "Temporarily reserve quoted inventory (short expiry) before booking.",
      "method": "POST",
      "path": "/agent/holds",
      "scope": "booking.create",
      "risk": "commercial_write",
      "requires_user_approval": false,
      "status": "live",
      "milestone": null
    },
    {
      "name": "create_booking",
      "purpose": "Convert a quote + hold into a confirmed booking. Requires a traveler approval reference.",
      "method": "POST",
      "path": "/agent/bookings",
      "scope": "booking.create",
      "risk": "high",
      "requires_user_approval": true,
      "status": "live",
      "milestone": null
    },
    {
      "name": "get_booking",
      "purpose": "Read bookings this integration created — public-safe subset only, no supplier or internal data.",
      "method": "GET",
      "path": "/agent/bookings/{id}",
      "scope": "booking.read",
      "risk": "customer_data",
      "requires_user_approval": false,
      "status": "live",
      "milestone": null
    },
    {
      "name": "initiate_payment",
      "purpose": "Issue an approval-scoped hosted payment link for the traveler. Opaque authorization only — raw card data never passes through the agent channel.",
      "method": "POST",
      "path": "/agent/payments",
      "scope": "payment.initiate",
      "risk": "high",
      "requires_user_approval": true,
      "status": "live",
      "milestone": null
    },
    {
      "name": "manage_itinerary",
      "purpose": "Create, read, update and delete server-persisted trip itineraries — the same rows the website planner edits (parity). Optimistic-lock versioning; plans lock once quoted or booked.",
      "method": "GET/POST/PUT/DELETE",
      "path": "/itineraries",
      "scope": "itinerary.read + itinerary.write",
      "risk": "commercial_write",
      "requires_user_approval": false,
      "status": "live",
      "milestone": null
    },
    {
      "name": "concierge_plan",
      "purpose": "Plan-with-AI: an LLM orchestrator calls the agent tools (search → detail → availability → validate → quote) and returns a server-validated itinerary plus a server-computed quote. Product ids must come from tool results; invalid plans are never persisted.",
      "method": "POST",
      "path": "/concierge/plan",
      "scope": "concierge.plan",
      "risk": "read",
      "requires_user_approval": false,
      "status": "live",
      "milestone": null
    },
    {
      "name": "reschedule_booking",
      "purpose": "Reschedule an existing booking within operator rules, with traveler approval.",
      "method": null,
      "path": null,
      "scope": "booking.modify",
      "risk": "high",
      "requires_user_approval": true,
      "status": "planned",
      "milestone": "v2"
    },
    {
      "name": "cancel_booking",
      "purpose": "Cancel an existing booking under the applicable policy tier, with traveler approval.",
      "method": null,
      "path": null,
      "scope": "booking.modify",
      "risk": "high",
      "requires_user_approval": true,
      "status": "planned",
      "milestone": "v2"
    },
    {
      "name": "mcp_server",
      "purpose": "MCP (Model Context Protocol) Streamable HTTP endpoint exposing the same tools to MCP clients.",
      "method": "POST",
      "path": "/agent/mcp",
      "scope": "multiple",
      "risk": "read",
      "requires_user_approval": false,
      "status": "live",
      "milestone": null
    }
  ],
  "docs": {
    "openapi": "https://goldatrip.com/api/v1/docs",
    "agents_page": "/{locale}/agents",
    "llms_txt": "https://goldatrip.com/llms.txt"
  },
  "contact": "/contact"
}