Data API Reference
Every endpoint, parameter and field of the Maya Data API, with the values a field can have. How to create a key and keep a copy of your conversations is in Exporting your conversation data.
Endpoints
Every address starts with the API base URL, https://api.mayatravel.ai/v1, and needs your key in the Authorization: Bearer header.
| Endpoint | What it returns |
|---|---|
GET /conversations | Conversations, up to 50 per page, oldest first: by created_at_utc without filters, and by updated_at_utc when you pass updated_after. |
GET /conversations/{chat_uuid} | One conversation with its messages. Answers 404 if it doesn't exist or belongs to another organisation. |
GET /me | The organisation and permissions of your key, and the limits that apply. Use it to test a new key. |
Parameters
These apply to GET /conversations. Times are ISO 8601, for example 2026-09-30T14:22:05Z; a time without a zone counts as UTC.
| Parameter | Type | Meaning |
|---|---|---|
cursor | string | The next_cursor from the previous page. Leave it out on the first call. It remembers your filters, so you can send it alone or together with the same filters; different filters are refused. |
updated_after | timestamp | Only conversations whose updated_at_utc is on or after this moment. Conversations that changed in the last 30 minutes come in a later run. |
created_after | timestamp | Only conversations with created_at_utc on or after this moment. |
created_before | timestamp | Only conversations with created_at_utc before this moment. |
Responses
A page of conversations. Follow next_cursor until has_more is false. A page can hold fewer than 50 conversations, or none, and still have more after it.
{
"data": [ /* up to 50 conversations */ ],
"next_cursor": "eyJ2IjoxLCJjIjoiMjAyNi0wOS0zMFQxNDoyMjowNVoifQ",
"has_more": true
}
The answer from /me:
{
"organization": "example-travel",
"scopes": ["maya:export"],
"limits": { "conversations_per_minute": 500, "concurrent_requests": 1, "page_size": 50 }
}
An error, with a code to check and a message to read:
{ "error": { "code": "rate_limited", "message": "Limit of 500 conversations per minute reached. Try again in 12 seconds." } }
| Status | When |
|---|---|
| 400 | A parameter or the cursor is invalid. |
| 401 | The key is missing, wrong or revoked. |
| 403 | The key is not a conversation-export key, belongs to another environment, or its owner no longer has access to the organisation. Use a key from the API keys card, not AI Connections (MCP). |
| 404 | The conversation doesn't exist for your organisation, or the address isn't an endpoint. |
| 429 | The limit of 500 conversations a minute is reached, or another request for your organisation is still running. Retry-After says how many seconds to wait. |
| 500, 503 | Something went wrong on the Maya side. Retry with the same cursor. |
Conversation
One record per conversation. Only real conversations are included: at least one message from the visitor. Test conversations and chat windows opened without a message are left out. A field marked "or null" can be empty.
Identity and Time
| Field | Type | Meaning |
|---|---|---|
chat_uuid | string | Unique id of the conversation, stable forever. The Maya chat widget sends the same value as chat_id with the events it reports to your analytics, so you can join conversations with your web analytics. |
ga_client_id | string or null | The GA4 client id of the visitor's browser, when Maya captured it. Use it to join conversations with your Google Analytics data. |
created_at_utc | timestamp | When the chat window was opened. This can be days before the first message. |
updated_at_utc | timestamp | When the conversation last changed: a new message, or Maya finished processing it. Use it with updated_after. |
first_user_message_at_utc | timestamp | When the visitor sent the first message. Use this to date a conversation. |
last_message_at_utc | timestamp or null | When the last message was sent. Empty when the exact message times aren't available. |
duration_seconds | integer or null | Seconds from the visitor's first message to the last message. Empty when the exact message times aren't available. |
timestamps_estimated | boolean | true when the exact message times of this conversation aren't available. The messages are still in the right order (seq). |
Where It Started
| Field | Type | Meaning |
|---|---|---|
site | string or null | The website the conversation started on, for example www.example-travel.com. |
entry_mode | string or null | How the chat was shown when the visitor sent the first message: popover, full-page or search. |
entry_page_url | string or null | The page the visitor was on when they sent the first message. Missing for some conversations. |
What Maya Made of It
| Field | Type | Meaning |
|---|---|---|
chat_title | string or null | A short title Maya writes once the conversation has gone quiet. |
outcome | string or null | How the conversation ended. See Values. |
sentiment | string or null | positive, neutral or negative. |
topics | list of strings | Topics Maya assigned to the conversation. |
countries | list of strings | Countries the visitor mentioned or asked about. |
places | list of strings | Regions and cities the visitor mentioned or asked about. |
knowledge_gap | boolean | The visitor asked at least one question Maya couldn't answer from your content. |
flagged_inappropriate | boolean | At least one visitor message was flagged as inappropriate. |
left_contact_details | boolean | The visitor left an email address in the chat. The details themselves are only in the message text. |
Activity
| Field | Type | Meaning |
|---|---|---|
user_messages | integer | Messages the visitor typed. |
quick_reply_messages | integer | Suggested replies the visitor clicked. |
assistant_answers | integer | Answers Maya gave. |
recommendation_blocks | integer | Answers that came with recommendation cards. The cards themselves are not part of the API yet. |
Trip Details
Filled in when the visitor mentioned them.
| Field | Type | Meaning |
|---|---|---|
adults | integer or null | Number of adults travelling. |
children | integer or null | Number of children travelling. |
babies | integer or null | Number of babies travelling. |
travel_group | list of strings | Who is travelling, as Maya understood it from the conversation. |
departure_month | integer or null | Month of departure, from 1 to 12. |
duration_nights | integer or null | Length of the trip in nights. |
themes | list of strings | Holiday themes the visitor was interested in, when your Maya setup recognises them. |
Messages
| Field | Type | Meaning |
|---|---|---|
messages | list of messages | Every message in the conversation, in order. See Message. |
Message
One entry per message, from the visitor, Maya or one of your colleagues. The fixed greeting every chat opens with is left out.
| Field | Type | Meaning |
|---|---|---|
seq | integer | Position in the conversation, starting at 1. Always the right order. |
created_at_utc | timestamp | When the message was sent. |
timestamp_estimated | boolean | true when the exact time of this message isn't available. seq still gives the right order. |
sender | string | user, assistant or human_agent. See Values. |
message_type | string | What kind of message this is. See Values. |
content | string | The full text, exactly as typed or answered. It can contain personal data the visitor typed. |
page_url | string or null | The page the visitor was on. Visitor messages only. |
widget_mode | string or null | popover, full-page or search. Visitor messages only. |
knowledge_gap | boolean | Maya couldn't answer this from your content. |
flagged_inappropriate | boolean | This message was flagged as inappropriate. |
Values
Fields with a fixed set of values. New values can be added within v1, so treat a value you don't know as "other" instead of failing.
outcome
| Value | Meaning |
|---|---|
resolved_by_ai | Maya answered the visitor's question. |
not_in_offering | Maya correctly told the visitor this isn't something you offer. |
handed_to_colleague | The conversation was handed over to one of your colleagues. |
ai_could_not_help | Maya couldn't answer the question. |
just_browsing | The visitor was looking around without a real question. |
message_type
| Value | Meaning |
|---|---|
typed | The visitor typed a message. |
quick_reply | The visitor clicked a suggested reply. |
cta | The visitor clicked a call-to-action button, such as leaving their details. |
answer | An answer from Maya. |
human_answer | A reply from one of your colleagues after a handover. |
idle_message | A short follow-up Maya sent when the visitor went quiet. |
thumbs_down_followup | The question Maya asks after a thumbs down. |
inappropriate_notice | The notice shown after a message was flagged as inappropriate. |
daily_limit_reached | The notice shown when a visitor reached the daily message limit. |
sender
| Value | Meaning |
|---|---|
user | The visitor. |
assistant | Maya. |
human_agent | One of your colleagues, after a handover. |
entry_mode and widget_mode
| Value | Meaning |
|---|---|
popover | The chat window that opens from the chat button on a page. |
full-page | The chat shown as a full page. |
search | The conversation started from Maya's search bar. |
Example Conversation
Shortened, with made-up values.
{
"chat_uuid": "6f1c2d9e-8a41-4b7f-9c3e-2d5a7b0e4f18",
"ga_client_id": "1234567890.1759241708",
"created_at_utc": "2026-09-30T14:21:48Z",
"updated_at_utc": "2026-09-30T14:41:12Z",
"first_user_message_at_utc": "2026-09-30T14:22:05Z",
"last_message_at_utc": "2026-09-30T14:29:51Z",
"duration_seconds": 466,
"timestamps_estimated": false,
"site": "www.example-travel.com",
"entry_mode": "popover",
"entry_page_url": "https://www.example-travel.com/greece/crete",
"chat_title": "Family hotel on Crete in May",
"outcome": "resolved_by_ai",
"sentiment": "positive",
"topics": ["Family holidays", "Beach hotels"],
"countries": ["Greece"],
"places": ["Crete"],
"user_messages": 3,
"quick_reply_messages": 1,
"assistant_answers": 4,
"recommendation_blocks": 2,
"knowledge_gap": false,
"flagged_inappropriate": false,
"left_contact_details": false,
"adults": 2,
"children": 2,
"babies": null,
"travel_group": ["family"],
"departure_month": 5,
"duration_nights": 7,
"themes": ["beach"],
"messages": [
{ "seq": 1, "created_at_utc": "2026-09-30T14:22:05Z", "timestamp_estimated": false,
"sender": "user", "message_type": "typed",
"content": "Do you have family hotels on Crete with a kids' pool, in May?",
"page_url": "https://www.example-travel.com/greece/crete", "widget_mode": "popover",
"knowledge_gap": false, "flagged_inappropriate": false },
{ "seq": 2, "created_at_utc": "2026-09-30T14:22:11Z", "timestamp_estimated": false,
"sender": "assistant", "message_type": "answer",
"content": "Yes! Here are three family hotels on Crete with a separate kids' pool …",
"page_url": null, "widget_mode": null,
"knowledge_gap": false, "flagged_inappropriate": false }
]
}