Integrations API Overview¶

The integrations API is the public API surface for partner-facing Traveln APIs.

• Host: https://integrations.app.traveln.ai
• Usage model: server-to-server only

API groups¶

Traveln currently exposes two integrations API patterns:

Resource APIs¶

These endpoints live under /api/v1/ and use the tenant's SSO HMAC secret.

Authorization: Api-Key <sso_hmac_secret>

The tenant is derived from this secret. Do not send a tenant slug in the URL, query string, or request body.

Payment callback API¶

The payment notification endpoint is a separate server-to-server callback used by partner payment backends to report booking payment outcomes back to Traveln.

X-API-KEY: <partner_api_key>

See Payment Notification API for the full contract.

Response formats¶

Resource APIs¶

The /api/v1/ resource endpoints return the same top-level JSON structure:

{
  "success": true,
  "message": "Countries retrieved.",
  "data": {},
  "error": null
}

Error responses keep the same envelope:

{
  "success": false,
  "message": "Unauthorized.",
  "data": null,
  "error": {
    "code": "UNAUTHORIZED"
  }
}

Payment callback API¶

POST /api/v1/payments/notify/ returns a simpler status payload instead of the standard integrations envelope:

{
  "status": "success"
}

Available endpoints¶

Resource APIs¶

• GET /api/v1/countries/
• GET /api/v1/cities/
• GET /api/v1/trips/<uuid>/
• GET /api/v1/suggested-prompts/
• POST /api/v1/suggested-prompts/
• PATCH /api/v1/suggested-prompts/<uuid>/
• DELETE /api/v1/suggested-prompts/<uuid>/

Payment callback API¶

• POST /api/v1/payments/notify/

Request examples¶

The examples below use the standard /api/v1/ resource API authentication model.

curl "https://integrations.app.traveln.ai/api/v1/countries/?limit=20&offset=0" \
  -H "Authorization: Api-Key <sso_hmac_secret>" \
  -H "Accept: application/json"

const res = await fetch("https://integrations.app.traveln.ai/api/v1/countries/?limit=20&offset=0", {
  headers: {
    Authorization: "Api-Key <sso_hmac_secret>",
    Accept: "application/json",
  },
})

const payload = await res.json()
console.log(payload)

import requests

res = requests.get(
    "https://integrations.app.traveln.ai/api/v1/countries/",
    params={"limit": 20, "offset": 0},
    headers={
        "Authorization": "Api-Key <sso_hmac_secret>",
        "Accept": "application/json",
    },
    timeout=30,
)

payload = res.json()
print(payload)

Notes¶

• These endpoints are intended for partner backend services, not browser-side JavaScript.
• Browser CORS is intentionally not enabled on the integrations host.
• The data field contains the endpoint-specific payload for /api/v1/ resource APIs.
• The payment notification endpoint uses X-API-KEY and a simple status response. Do not reuse the Authorization: Api-Key examples for that endpoint.