Build with the
Amigo Treks API.

Connect an agent

1. Request credentials below. Save data.id as your OAuth client ID and data.key as your client secret and API key. The secret is returned once.
2. Wait for an Amigo administrator to approve the request. Pending credentials cannot access the API or MCP.
3. For REST, use the approved key as a Bearer token or exchange it for a scoped OAuth token. For MCP, use the Streamable HTTP endpoint below without authentication.

These credentials identify your application. They do not give it access to customer accounts.

Request an API key

Tell us what you are building and how you plan to use the API. Save your key in a secure place when it appears below. We show it once, and you can use it after an administrator approves your request.

POST https://www.amigotrekking.com/api/agent/key-requests
Content-Type: application/json

{"name":"Example travel assistant","email":"developer@example.com","purpose":"Help travelers compare published trekking itineraries."}

{"data":{"id":123,"status":"pending","key":"YOUR_ONE_TIME_AGENT_KEY"}}

Use data.id as your OAuth client ID and data.key as your client secret. Enter a name of up to 120 characters, a contact email and a purpose of 20–2,000 characters. Submit one request and keep the returned credentials while you wait for approval.

Approved keys expire after one year. Request a replacement if a key is lost or expires. Contact Amigo immediately if a key is exposed so an administrator can revoke it.

Make your first request

Search for Everest trips from your terminal. Send your approved key in the Authorization header. Each key allows up to 60 requests per minute.

curl --get 'https://www.amigotrekking.com/api/agent/v1/search' \
  --data-urlencode 'q=everest' \
  --data-urlencode 'limit=3' \
  --header 'Authorization: Bearer YOUR_AGENT_API_KEY' \
  --header 'Accept: application/json'

Read search results in data.suggestions. For a trip result, use the slug from its href: /everest-base-camp-trek.html becomes everest-base-camp-trek. You can also get slugs from the trip catalog. Check the HTTP status before reading the response data.

Keep the key on your server, outside browser bundles, URLs and logs. A pending, invalid, expired or revoked key returns HTTP 401. Customer or administrator tokens cannot be used as agent keys.

OAuth access tokens

The REST API supports OAuth 2.0 client credentials using the same approved key. Set client_id to the numeric registration ID and client_secret to the saved key. Authenticate with HTTP Basic; the issued credentials contain only characters that do not require form escaping.

curl 'https://www.amigotrekking.com/api/agent/oauth/token' --user 'YOUR_CLIENT_ID:YOUR_AGENT_API_KEY' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=client_credentials' --data-urlencode 'scope=trips.read guides.read departures.read'

The JSON response contains access_token, token_type (Bearer), expires_in and scope. Use the access token in the Authorization header of the REST examples above. Tokens last at most 900 seconds; obtain another with client credentials when needed. No refresh token is issued.

• trips.read: trips, itineraries and published pricing; the default scope.
• guides.read: published travel guides.
• departures.read: published departure dates.

Search requires all three scopes. Unsupported scopes return invalid_scope; pending, expired or revoked credentials return invalid_client. Revoking the key invalidates its access tokens. Public MCP requires no API key or OAuth token.

Discovery: authorization server, protected resource, and authentication guide.

Endpoint reference

The OpenAPI specification lists the public content operations and parameters.

Access and privacy

Agents can read published travel content, itineraries, departures and pricing. Customer accounts, login, private bookings, documents and payment records are not part of the integration API.

Do not collect customer passwords or request account tokens. Travelers manage their accounts and checkout on the Amigo website.

Connect an MCP client

Follow the step-by-step MCP connection guide for Codex configuration, connection checks and troubleshooting.

Add the following URL to a client that supports Streamable HTTP. No authentication or API key is required. Use the server card to inspect the connection metadata.

https://www.amigotrekking.com/api/mcp/public

{
  "transport": "streamable-http",
  "url": "https://www.amigotrekking.com/api/mcp/public"
}

Start with search_trips, then get_trip for exact trip details. Use recommend_trips for preference-based suggestions and render_trip_comparison for interactive comparison. Use get_packing_options and generate_packing_list for packing lists from the website’s catalog. The legacy search and fetch tools remain available. Call tools/list after initialization for current schemas.

For contact requests, submit_trip_enquiry comes first. Save its enquiry reference and continuation proof before using submit_booking_request. These tools require explicit consent and their documented idempotency keys. They do not reserve seats, charge payments or confirm bookings.

Before sending an enquiry, get the traveler’s permission to share their contact details and trip request with Amigo.

Connect an A2A agent

Discover the public agent at /.well-known/agent-card.json. It supports A2A 1.0 over JSON-RPC with no API key. Send SendMessage requests to /api/a2a with Content-Type: application/json and A2A-Version: 1.0.

{
  "jsonrpc": "2.0",
  "id": "trip-search",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "unique-client-message-id",
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "Everest Base Camp"
        }
      ]
    }
  }
}

For explicit filters or trip details, send a JSON data part containing skillId and arguments. Supported skills are search_trips, get_trip and get_site_overview. Argument schemas match the public MCP tools; use tools/list for the current definitions.

{
  "jsonrpc": "2.0",
  "id": "trip-details",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "another-unique-message-id",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "skillId": "get_trip",
            "arguments": {
              "trip_id": "trip:everest-base-camp-trek"
            }
          }
        }
      ]
    }
  }
}

Responses contain a direct agent message with structured catalog data. Each request is independent; the service does not retain conversation history or create tasks. Streaming, push notifications and authenticated extended cards are unavailable. A2A access is read-only; use the official website or the consent-based public MCP flow for enquiries and booking requests.

Errors and retries

Handle each endpoint’s response body alongside its HTTP status. Error formats vary by route.

Unknown route · 404

Check the path and slug against the specification. Agent endpoints return a JSON error when a route or published resource is unavailable.

Rate limit · 429

The agent API and MCP share a limit of 60 requests per minute per key. Honor Retry-After before retrying. Additional transport limits apply.

Read request failed

Retry transient GET or HEAD failures with bounded exponential backoff and jitter. Set a timeout and stop after a limited number of attempts.

Write result is uncertain

Check whether the enquiry was created before retrying. Use an idempotency mechanism only where the endpoint documents one; do not assume all writes support it.

Service reachability

GET /api/status confirms the web service responds. Check the operation you depend on before treating the catalog service as available.

Specifications and support