Partner API

The itinerary engine, behind your interface.

Generate grounded, feasibility-checked itineraries from your website, booking flow, or CRM. Available on the Agency and Enterprise plans — keys are created in your workspace console and are rate-limited per key.

Create an API key Talk to sales

Authentication

Every request carries a bearer key. Keys are shown once at creation, stored hashed, and revocable at any time from Workspace → API. Scopes: itineraries:read, itineraries:write.

Authorization: Bearer tk_live_...

Create an itinerary

POST /api/v1/itineraries accepts a brief and returns 202 immediately — the engine plans asynchronously (typically under a minute). Generations draw from your workspace's monthly quota.

curl -X POST https://tripos.dev/api/v1/itineraries \
  -H "Authorization: Bearer tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "Lisbon",
    "startDate": "2026-09-12",
    "endDate": "2026-09-16",
    "timezone": "Europe/Lisbon",
    "clientRef": "crm-4821",
    "preferences": {
      "budget": "high",
      "pace": "balanced",
      "vibes": { "foodie": 90, "culture": 70 }
    }
  }'

# 202 Accepted
{
  "id": "cm0x…",
  "status": "generating",
  "statusUrl": "https://tripos.dev/api/v1/itineraries/cm0x…"
}

Fetch the result

Poll the status URL until status is ready. Every block carries its venue data, confidence level, and source.

curl https://tripos.dev/api/v1/itineraries/cm0x… \
  -H "Authorization: Bearer tk_live_..."

# 200 OK (when ready)
{
  "id": "cm0x…",
  "status": "ready",
  "destination": "Lisbon",
  "days": [
    {
      "dayNumber": 1,
      "date": "2026-09-12",
      "blocks": [
        {
          "startTime": "09:00",
          "endTime": "10:00",
          "type": "FOOD",
          "title": "Pastéis de Belém",
          "neighborhood": "Belém",
          "confidence": "CONFIRMED",
          "place": { "name": "Pastéis de Belém", "rating": 4.7, "address": "…" }
        }
      ]
    }
  ]
}

List itineraries

GET /api/v1/itineraries?limit=20&cursor=… returns your workspace's itineraries with cursor pagination.

Embeds

Any client deliverable can be embedded on your own site. Embed pages are iframe-safe and render your workspace branding.

<!-- Embed a branded itinerary on your site -->
<iframe
  src="https://tripos.dev/embed/p/DELIVERABLE_TOKEN"
  style="width:100%;max-width:760px;height:900px;border:0"
  title="Trip itinerary"
  loading="lazy"
></iframe>

Errors & limits

Status	Meaning	What to do
401	Missing, malformed, or revoked key	Check the Authorization header
402	Plan lapsed or monthly quota reached	Upgrade or wait for the next cycle
403	Key lacks the required scope	Create a key with the right scopes
429	Rate limit exceeded (100 req/min per key)	Back off and retry