Your itinerary.
In your tools, too.

1. Enable API access in Triivl

   Open Settings → API and MCP. Enable API access, select your own trips and choose the permissions you want. Save your settings.

2. Create an API key

   Name the connection and copy the key when it appears. The key is shown only once and expires within 90 days. The new settings screen must be installed in your app.

3. Let the app synchronize, then read your trips

   Keep the app open while your selected trips synchronize. Send the key as a Bearer token with your request.

# Set the key locally. Do not put it in code or Git.
export TRIIVL_API_KEY='YOUR_API_KEY'

curl 'https://api.triivl.app/v1/trips' \
  --header "Authorization: Bearer $TRIIVL_API_KEY"

{
  "trips": [
    {
      "id": "e27a8846-c0c9-42e5-a308-d35c060e336e",
      "title": "Weekend in Ålesund",
      "kind": "personal",
      "startDay": "2026-11-06",
      "endDay": "2026-11-08",
      "deletedAt": null,
      "revision": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "syncedAt": "2026-10-14T19:10:00.000Z"
    }
  ]
}

All IDs, dates and revisions on this page are examples. Use the ID and revision from your own response.

API and MCP have separate settings. Both are off by default. An API key grants REST access, while an approved MCP connection grants MCP access. The app's sign-in token cannot be used as an integration key.

Changing settings does not automatically expand an existing key or connection. Create a new key or approve the MCP connection again to grant additional permissions. Access is checked on every request and can be revoked in the app.

Documents, photos, receipts, private notes, seats, precise addresses, coordinates and packing lists are excluded from this API.

All REST requests below require Authorization: Bearer YOUR_API_KEY. {tripId} is the ID from the trip response.

export TRIP_ID='ID_FROM_TRIP_LIST'

curl "https://api.triivl.app/v1/trips/$TRIP_ID" \
  --header "Authorization: Bearer $TRIIVL_API_KEY"

REQUEST_ID="$(uuidgen)"

curl --request POST 'https://api.triivl.app/v1/trips' \
  --header "Authorization: Bearer $TRIIVL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data "{
    \"requestId\": \"$REQUEST_ID\",
    \"trip\": {
      \"title\": \"Weekend in Ålesund\",
      \"kind\": \"personal\",
      \"startDay\": \"2026-11-06\",
      \"endDay\": \"2026-11-08\"
    }
  }"

export REVISION='REVISION_FROM_GET_TRIP'

REQUEST_ID="$(uuidgen)"

curl --request PATCH "https://api.triivl.app/v1/trips/$TRIP_ID" \
  --header "Authorization: Bearer $TRIIVL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data "{
    \"requestId\": \"$REQUEST_ID\",
    \"expectedRevision\": \"$REVISION\",
    \"trip\": { \"title\": \"Long weekend in Ålesund\" }
  }"

REQUEST_ID="$(uuidgen)"

curl --request DELETE "https://api.triivl.app/v1/trips/$TRIP_ID" \
  --header "Authorization: Bearer $TRIIVL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data "{
    \"requestId\": \"$REQUEST_ID\",
    \"expectedRevision\": \"$REVISION\"
  }"

Trip items are flights, hotels, rental cars and other activities in a trip. New items default to ideas. Set planningState: "confirmed" to add an item to the itinerary. The API does not make bookings or purchases.

REQUEST_ID="$(uuidgen)"

curl --request POST "https://api.triivl.app/v1/trips/$TRIP_ID/items" \
  --header "Authorization: Bearer $TRIIVL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data "{
    \"requestId\": \"$REQUEST_ID\",
    \"expectedRevision\": \"$REVISION\",
    \"item\": {
      \"type\": \"lodging\",
      \"title\": \"Hotel in Ålesund\",
      \"city\": \"Ålesund\",
      \"planningState\": \"idea\",
      \"startDate\": \"2026-11-06T15:00:00+01:00\",
      \"endDate\": \"2026-11-08T11:00:00+01:00\",
      \"startTimeZoneID\": \"Europe/Oslo\",
      \"endTimeZoneID\": \"Europe/Oslo\"
    }
  }"

{
  "requestId": "c90d02d6-dcd4-479a-8cd3-d02c8df1dcf1",
  "expectedRevision": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "item": { "title": "Hotel Brosundet", "planningState": "confirmed" }
}

A write response with 202 Accepted means the request is queued. It is saved in the app only when its status is applied. The app checks current permissions and revision before saving.

export REQUEST_ID='ID_FROM_WRITE_RESPONSE'

curl "https://api.triivl.app/v1/trip-commands/$REQUEST_ID" \
  --header "Authorization: Bearer $TRIIVL_API_KEY"

Safe retries

Generate a new UUID for each new change, for example with uuidgen. After a network failure, repeat the same request with the same requestId, body and key. Do not generate a new ID for that retry: keep REQUEST_ID and repeat only the curl call, not the uuidgen line. Reusing an ID with a different body or connection is rejected.

Only one queued/in-progress change is allowed per trip. Wait for the result and read the trip's new revision before the next change. Pending requests expire after 24 hours. Status records are retained for up to 90 days.

Trip · trip

Trip item · item

Unknown fields are rejected. IDs are UUIDs. revision is 64 hexadecimal characters. syncedAt shows when the backend last received the copy; it does not guarantee that a closed app has sent its latest changes.

Use a client that supports MCP with Streamable HTTP and OAuth. Add Triivl's server URL, then approve access in the app.

https://api.triivl.app/mcp

1. Enable MCP in the app

   Enable MCP and choose permissions under Settings → API and MCP. “All my trips” is the default and includes future trips. Choose “Select individual trips” to restrict access. API access does not need to be enabled. Booking references require a separate choice.

2. Add the server in your AI client

   Choose an external MCP server, enter the URL above and start the client's OAuth sign-in.

3. Approve the connection in Triivl

   The approval page opens the app. Check the client's name and permissions before approving. If the link does not open the app, enter the request code from the page manually in settings. The request lasts five minutes.

Ongoing trips and individual items

Use get_agenda for “what is next?” and “tomorrow”. One call returns the ongoing trip, next activity and confirmed items for the date, including unassigned items. Timestamps include local time zones. An 11:00 flight arrival can yield an 11:30 taxi suggestion; this is a minimum 30-minute planning buffer, rounded up to the next quarter-hour, not a booking.

create_item accepts an omitted tripId. The item is created as an idea without an artificial parent trip. assign_item attaches it later, or unassigns it with destinationTripId: null. Both sides require update permission and current revisions. “All my trips” includes unassigned items; individual selection offers a separate “Items without a trip” choice.

Smarter reading and writing

The tools compute their answers deterministically from the synchronized copies. No AI model is used, no new data is uploaded, and every tool follows the permissions and trip selection you chose. Booking references appear only with their own opt-in; seats, addresses and notes are never included.

• get_agenda now also returns derived per activity: minutes until start (startsInMinutes), trip day (“Day 2 of 3”), departsInMinutes and arrivesInMinutes for flights, and check-in/check-out context for lodging. conflicts warns about overlaps and tight connections. Existing fields are unchanged. Live flight status is not included.
• search_items searches title, subtitle, city, origin, destination and flight number, with an optional date range, type and trip. Results are ranked and bounded by limit.
• check_plan reviews one trip: nights without lodging, overlapping items, tight connections, transport that ends somewhere other than where the next item starts (only when both places are known and comparable), items without a time and the number of unconfirmed ideas. summarize_trip gives a short overview with days, cities in order and counts per type.
• create_item and assign_item return hints next to the queued change: possibleDuplicates and, without a trip, suggestedTrips whose dates contain the item or are one day away. These are suggestions. Nothing is assigned or changed automatically. Without read access, hints is only checked: false.
• parse_booking_text reads pasted confirmation text with Triivl’s existing rule-based import reader and proposes items shaped like create_item. It saves and queues nothing; the chat shows the proposals and calls create_item after you agree. Flights use the airports’ time zones; pass timeZone for other places.

The client is offered only the tools it is allowed to use. Write tools use the same queue and revision checks as REST. The chat client must use get_change_status to confirm the change was saved.

Connecting an external AI client means that client receives the data you permit. You can disconnect it in the app at any time.

Triivl supports public clients without a client secret, exact redirect URIs and Authorization Code with PKCE S256. Clients should read discovery metadata instead of hardcoding their configuration.

MCP uses stateless HTTP POST with JSON responses. GET and DELETE on /mcp return 405; the server does not use SSE or persistent MCP sessions. Unauthorized POST returns 401 with a WWW-Authenticate header pointing to resource metadata.

{
  "error": {
    "code": "revision_conflict",
    "message": "Trip has changed. Read its current revision."
  }
}

Individual selection allows up to 1,000 selected trips per channel. MCP with “All my trips” has no selection-count limit. Up to 1,000 items per trip. Key/client names may contain up to 100 characters. Private integration responses use Cache-Control: no-store. Read responses are synchronized copies; check syncedAt.

Lists are paged: GET /v1/items and list_items answer at most 100 items (limit, max 500) from offset, ordered by start, with total, truncated and nextOffset; a trip's items are paged the same way with itemLimit and itemOffset. Everything MCP can read is a REST route too: GET /v1/items/search, GET /v1/trips/{id}/plan, GET /v1/trips/{id}/summary and POST /v1/booking-text, with the same permissions as the tools.

Download the OpenAPI 3.1 specification for complete schemas, security configuration and endpoints. It also includes the app's own backend endpoints, which require app sign-in and are not accessible with an integration key.