Triplist Search API

Overview

The Triplist Search API lets you search for curated travel triplists — AI-generated or human-created travel plans with flights, hotels, apartments, car rentals, transfers, and trains.

Base URL: https://triplist.com/api/v1

Authentication: Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Search Endpoint

GET /api/v1/triplists/search

Returns paginated search results with optional facets.

Query Parameters

At least one of q, travelers, dateStart, priceMax, styles, or itemTypes is required.

Example

curl "https://triplist.com/api/v1/triplists/search?q=paris+romantic&travelers=2&dateStart=2026-06-01&dateEnd=2026-06-14&sort=price&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Format

{
  "data": [
    {
      "kind": "triplist_card",
      "triplistId": "uuid",
      "parentTripId": "uuid",
      "travelerCount": 2,
      "travelerOrigin": { "city": "New York", "country": "US" },
      "travelerDates": { "start": "2026-06-01", "end": "2026-06-14" },
      "totalCost": "2450.00",
      "totalCostCurrency": "USD",
      "generationStatus": "complete",
      "score": 92.5,
      "createdAt": "2026-02-20T10:00:00Z",
      "updatedAt": "2026-02-20T12:30:00Z",
      "tripTitle": "Romantic Paris Getaway",
      "coverImageUrl": "https://...",
      "mainPlaces": [{ "name": "Paris", "country": "France" }],
      "tripDatesRange": { "start": "2026-06-01", "end": "2026-06-14" },
      "estimatedCost": "2000-3000",
      "styles": ["romantic", "cultural"]
    }
  ],
  "meta": {
    "cursor": "2026-02-20T10:00:00Z",
    "hasMore": true
  },
  "facets": {
    "styles": [{ "value": "romantic", "count": 45 }],
    "destination_names": [{ "value": "Paris", "count": 18 }],
    "destination_countries": [{ "value": "France", "count": 42 }]
  }
}

Field Reference

Pagination

Use cursor-based pagination. Pass meta.cursor from the previous response as the cursor query parameter. When meta.hasMore is false, you've reached the end.

Streaming Endpoint

GET /api/v1/triplists/search/stream

Server-Sent Events (SSE) endpoint for real-time search results and AI generation progress. Accepts the same query parameters as the standard search endpoint.

• Content-Type: text/event-stream
• Heartbeat comment every 15 seconds to keep the connection alive
• Supports reconnection via Last-Event-ID header

Event Types

initial-results

First batch of existing results (up to 20 items).

{ "cards": [ /* FeedTriplistCard[] */ ], "count": 20 }

new-trip

A single newly AI-generated triplist card.

{ "card": { /* FeedTriplistCard */ } }

generation-status

Status update for a triplist being generated. Polled every ~2 seconds.

{
  "triplistId": "uuid",
  "generationStatus": "in_progress",
  "totalCost": "1234.50",
  "totalCostCurrency": "USD",
  "score": 85.5
}

image-update

Cover image became available for a triplist.

{ "triplistId": "uuid", "coverImageUrl": "https://..." }

done

Stream is complete. Close the connection.

{ "totalCount": 25 }

error

An error occurred. The stream will close.

{ "message": "An unexpected error occurred." }

Item Types & Filters

Valid item types: flight, hotel, apartment, car_rental, transfer, train

Flight Filters

Hotel Filters

Apartment Filters

Car Rental Filters

Transfer Filters

Train Filters

Passing Filters

Serialize the filter object as JSON and URL-encode it in the itemFilters parameter:

itemFilters={"flight":{"maxStops":1,"cabinClass":"business"},"hotel":{"minStars":4}}

URL-encoded:
itemFilters=%7B%22flight%22%3A%7B%22maxStops%22%3A1%2C%22cabinClass%22%3A%22business%22%7D%2C%22hotel%22%3A%7B%22minStars%22%3A4%7D%7D

Natural Language Query Parsing

The q parameter supports natural language. The API extracts structured criteria from free text:

Structured parameters (travelers, dateStart, etc.) take precedence over values parsed from q.

Error Handling

All errors follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description.",
    "details": {}
  }
}

Common Error Codes

Rate Limiting

The search endpoint uses the FEED rate-limit tier: 120 requests per 60-second sliding window.

When rate-limited, you'll receive a 429 response. Wait until X-RateLimit-Reset before retrying.

Example: Full AI Agent Flow

Here's a step-by-step example of how an AI agent can use this API to answer "Find me a romantic trip to Paris for 2 people in June under $3000":

Step 1: Parse the user request

Extract: destination = Paris, travelers = 2, dates = June 2026, budget = $3000, style = romantic.

Step 2: Call the search API

curl "https://triplist.com/api/v1/triplists/search?q=paris+romantic&travelers=2&dateStart=2026-06-01&dateEnd=2026-06-30&priceMax=3000&styles=romantic&sort=price&limit=5&generate=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 3: Interpret results

• Check the data array for results. Each card has totalCost, tripTitle, mainPlaces, and styles.
• If generationStatus is "pending" or "in_progress", the AI is still building the triplist — connect to the streaming endpoint to watch progress.
• Use meta.hasMore and meta.cursor to paginate if needed.

Step 4: Stream for real-time updates (optional)

const eventSource = new EventSource(
  "https://triplist.com/api/v1/triplists/search/stream" +
  "?q=paris+romantic&travelers=2&dateStart=2026-06-01" +
  "&dateEnd=2026-06-30&priceMax=3000&styles=romantic&generate=true"
);

eventSource.addEventListener("initial-results", (e) => {
  const { cards, count } = JSON.parse(e.data);
  // Display initial results immediately
});

eventSource.addEventListener("new-trip", (e) => {
  const { card } = JSON.parse(e.data);
  // Append newly generated triplist
});

eventSource.addEventListener("generation-status", (e) => {
  const { triplistId, generationStatus, totalCost } = JSON.parse(e.data);
  // Update progress indicator
});

eventSource.addEventListener("done", () => {
  eventSource.close();
});

Step 5: Present to user

Summarize the top results: trip title, destination, dates, total cost, and a link to the full triplist on Triplist.

Panel Component System

Triplist uses a shared panel system for filter dropdowns and configuration sheets. On desktop, panels render as positioned dropdowns; on mobile, they render as bottom sheets. Both share a single background color and footer component.

--panel-bg CSS variable

A CSS custom property defines the panel surface color for both light and dark mode:

• Light: #ffffff
• Dark: #2a2a2a

Use the Tailwind class bg-panel-bg to apply it.

ResponsivePanel

Wraps Dropdown (desktop) and BottomSheet (mobile) behind a single interface.

FilterPanelFooter

Shared footer used inside every filter panel. Layout: left-aligned text link (“Clear”) and right-aligned primary button (“Done” or “Apply”), separated by a top border.

Footer UX pattern

• Immediate-apply panels (item type picker, capacity): changes take effect as the user interacts; the footer button is labeled “Done” and simply closes the panel.
• Deferred-apply panels (date range): the footer button is labeled “Apply” and commits the selection on click.