# Tools Reference: List Management

All five list tools require lists:manage permission, which is granted to all accounts by default.

Lists are org-owned collections of hotels:

Static lists — manually curated sets of hotels
Dynamic lists — backed by a saved search query; new matches can be discovered using get_list_diff

# list_user_lists

List all hotel lists owned by the calling organisation. Paginated at 10 per page.

# Parameters

Parameter	Type	Required	Description
`page`	integer (≥1)	No	Page number (default 1)
`createdBy`	string	No	Filter by creator user ID

# Example

curl -X POST https://api.hotel-universe.travel/mcp \
  -H "Authorization: Bearer pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_user_lists",
      "arguments": {
        "page": 1
      }
    }
  }'

# Response

{
  "total": 3,
  "page": 1,
  "lists": [
    {
      "id": "lst_abc123",
      "name": "London City Hotels",
      "createdBy": "usr_xyz",
      "createdAt": "2025-03-01T10:00:00Z"
    }
  ]
}

# get_list

Get metadata for a single list by ID. For dynamic lists, includes the saved search query that the list is backed by.

# Parameters

Parameter	Type	Required	Description
`listId`	string	Yes	List ID (e.g. `"lst_abc123"`)

# Example

curl -X POST https://api.hotel-universe.travel/mcp \
  -H "Authorization: Bearer pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_list",
      "arguments": {
        "listId": "lst_abc123"
      }
    }
  }'

# get_list_hotels

Get hotel entries in a list with hotel preview data. Paginated at 10 per page. For large lists, iterate through pages using the page parameter.

# Parameters

Parameter	Type	Required	Description
`listId`	string	Yes	List ID
`page`	integer (≥1)	No	Page number (default 1)

# Example

curl -X POST https://api.hotel-universe.travel/mcp \
  -H "Authorization: Bearer pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_list_hotels",
      "arguments": {
        "listId": "lst_abc123",
        "page": 1
      }
    }
  }'

# Response

{
  "total": 47,
  "page": 1,
  "entries": [
    {
      "huId": "HU4A2BC9",
      "name": "Hotel Arts Barcelona",
      "matchStatus": "matched"
    },
    {
      "huId": null,
      "name": "Unknown Beach Resort",
      "matchStatus": "unmatched"
    }
  ]
}

matchStatus values:

matched — the entry has a confirmed Hotel Universe ID
needsReview — a candidate match exists but requires human confirmation
unmatched — no match found yet

# get_list_stats

Get a summary of a list: total entries, matched hotels, entries needing review, and unmatched entries. Useful as a quick health check before processing a list.

# Parameters

Parameter	Type	Required	Description
`listId`	string	Yes	List ID

# Example

curl -X POST https://api.hotel-universe.travel/mcp \
  -H "Authorization: Bearer pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_list_stats",
      "arguments": {
        "listId": "lst_abc123"
      }
    }
  }'

# Response

{
  "total": 47,
  "matched": 43,
  "needsReview": 2,
  "unmatched": 2
}

# get_list_diff

For a dynamic list, return the hotels that match the saved search query but are not yet included in the list. Returns an empty array for static lists.

Run this periodically to discover newly added hotels that qualify for inclusion in a dynamic list.

# Parameters

Parameter	Type	Required	Description
`listId`	string	Yes	List ID

# Example

curl -X POST https://api.hotel-universe.travel/mcp \
  -H "Authorization: Bearer pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_list_diff",
      "arguments": {
        "listId": "lst_abc123"
      }
    }
  }'

# Response

[
  {
    "huId": "HU9F1AA2",
    "name": "New Boutique Hotel Barceloneta",
    "address": "Passeig Marítim de la Barceloneta, 36, Barcelona"
  }
]

← Tools Reference: Search & Hotels Tools Reference: Metasearch Pricing →