API Guide: Read Itineraries

List a traveller's itineraries, open one with its ETag, and read its days, flights, hotels, packing and expenses.

Read a traveller's library with GET /v1/itineraries, then open one itinerary with GET /v1/itineraries/{id}. Every call needs Authorization: Bearer YOUR_TOKEN and the itineraries:read scope. Send Travelyfe-Itinerary-Shape: clean on all of them.

Steps

List the library. filter is all (the default), owned, shared, saved, liked or disliked. updatedSince (an ISO 8601 time) returns only itineraries changed after it.

curl "https://api.travelyfe.com/v1/itineraries?filter=owned&limit=2" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Travelyfe-Itinerary-Shape: clean"

{
  "data": [
    {
      "id": "5b0e5c1a-8f4d-4a52-9d3a-1c2e7f6b9a10",
      "title": "Five Days In Lisbon",
      "destination": { "name": "Lisbon, Portugal" },
      "startDate": "2027-03-10",
      "visibility": "private",
      "role": "owner",
      "daysCount": 5,
      "stopsCount": 14,
      "updatedAt": "2026-10-12T09:30:00.000Z",
      "etag": "\"aXRpbmVyYXJ5OjQy\""
    }
  ],
  "nextCursor": null
}

Example response, shortened: each row also has summary, coverImageUrl, tags and author.

Open one itinerary. Replace the id with one from the list. The ETag response header is the version you read; keep it if you plan to change the itinerary.

curl -i https://api.travelyfe.com/v1/itineraries/5b0e5c1a-8f4d-4a52-9d3a-1c2e7f6b9a10 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Travelyfe-Itinerary-Shape: clean"

The body is the whole itinerary plus visibility, role, author, createdAt, updatedAt, likesCount and viewsCount.

Read a part. Each of these answers { "data": [...] } and the ETag header:

curl https://api.travelyfe.com/v1/itineraries/5b0e5c1a-8f4d-4a52-9d3a-1c2e7f6b9a10/flights \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Travelyfe-Itinerary-Shape: clean"

Use /days, /flights, /hotels, /packing or /expenses. One day, with its stops and the flight and hotel pins for that day, is /days/{dayId}.

Read another traveller's itineraries. Use their account id and filter=owned. You see only what you are allowed to see.

curl "https://api.travelyfe.com/v1/accounts/ACCOUNT_ID/itineraries?filter=owned" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Travelyfe-Itinerary-Shape: clean"

Check likes and saves. GET /v1/itineraries/{id}/marks answers { "liked": false, "disliked": false, "saved": true }.

What You Get

Itinerary fields are named once, everywhere: title, summary, destination, origin, startDate, travellers, currency, tags, days (each with stops), flights, hotels, packing, expenses. See the reference for every field.

Packing and expenses are included only when the traveller has Travelyfe Pro. Documents are not part of the itinerary: use the document routes.

If It Doesn't Work

401 unauthenticated: the token is missing, expired or revoked. See Authentication.
403 forbidden: the token lacks itineraries:read, or you asked for another traveller's saved, liked or disliked list.
403 subscriptionRequired: you asked for /packing or /expenses and the traveller does not have Pro.
404 notFound: the itinerary does not exist or this traveller cannot see it.

Limits

Reads count against 120 requests a minute. limit is 1 to 100, 25 by default; see Page Through Results.

API Guide: Read Itineraries

Steps

What You Get

If It Doesn't Work

Limits

Related

On this page