Authentication

The Agentic Tourism API uses API keys to authenticate requests. You can view and manage your API keys in your dashboard.

API Key Authentication

Include your API key in the Authorization header of each request:

Authorization: Bearer YOUR_API_KEY

OAuth 2.0 (Coming Soon)

For applications that need to access multiple businesses, OAuth 2.0 authentication will be available soon.

Rate Limits

Default Rate Limits:

Basic Plan: 1,000 requests per hour
Standard Plan: 5,000 requests per hour
Premium Plan: 20,000 requests per hour
Enterprise: Custom limits available

Rate limit information is included in response headers:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1640995200
                

POST /v1/chat

Send a chat message and receive an AI-powered response with relevant booking options.

Request Parameters

Parameter	Type	Required	Description
business_id	string	Required	Your unique business identifier
message	string	Required	The user's chat message
session_id	string	Required	Unique session identifier for conversation continuity
language	string	Optional	ISO 639-1 language code (e.g., 'en', 'es', 'fr')
metadata	object	Optional	Additional context data

Example Request

curl -X POST https://api.agentictourism.com/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "biz_123456",
    "message": "What tours do you have available tomorrow?",
    "session_id": "sess_abc123",
    "language": "en"
  }'
                

Example Response

{
  "id": "msg_789xyz",
  "message": "We have several tours available tomorrow! Here are your options:",
  "booking_options": [
    {
      "id": "tour_456",
      "name": "City Walking Tour",
      "time": "10:00 AM",
      "duration": "2 hours",
      "price": 45,
      "availability": 8
    },
    {
      "id": "tour_789",
      "name": "Sunset Boat Cruise",
      "time": "5:30 PM",
      "duration": "1.5 hours",
      "price": 65,
      "availability": 12
    }
  ],
  "media": [
    {
      "type": "image",
      "url": "https://cdn.agentictourism.com/tours/city-walk.jpg",
      "alt": "City Walking Tour"
    }
  ],
  "suggested_actions": ["book_tour", "more_info", "check_other_dates"]
}

GET /v1/bookings

Retrieve booking availability and details for your business.

Query Parameters

Parameter	Type	Description
date	string	ISO 8601 date format (YYYY-MM-DD)
service_id	string	Filter by specific service/tour
guests	integer	Number of guests

POST /v1/bookings

Create a new booking through the API.

Request Body

{ "service_id": "tour_456", "date": "2025-02-15", "time": "10:00", "guests": 2, "customer": { "name": "John Doe", "email": "[email protected]", "phone": "+1234567890" }, "payment_method_id": "pm_123456" }

Error Handling

The API uses standard HTTP response codes to indicate success or failure.

Status Code	Description
200 OK	Request succeeded
400 Bad Request	Invalid request parameters
401 Unauthorized	Invalid or missing API key
404 Not Found	Resource not found
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error - please contact support

Error Response Format

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'date' parameter must be in YYYY-MM-DD format",
    "field": "date"
  }
}

Webhook Events

Subscribe to real-time events for bookings, leads, and conversations.

booking.created

Triggered when a new booking is created

{ "event": "booking.created", "data": { "booking_id": "book_123", "service": "City Walking Tour", "date": "2025-02-15", "customer": {...} }, "timestamp": "2025-02-14T10:30:00Z" }

lead.captured

Triggered when a new lead is captured through chat

{ "event": "lead.captured", "data": { "lead_id": "lead_456", "name": "Jane Smith", "email": "[email protected]", "source": "chat_widget" }, "timestamp": "2025-02-14T11:45:00Z" }

API Documentation