{
  "openapi": "3.1.0",
  "info": {
    "title": "Data Export API",
    "version": "1.4"
  },
  "servers": [
    {
      "url": "https://example.ada.support/"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "Conversation": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "description": "Unique ID for the conversation record",
            "examples": [
              "5d8a7d080afd19b55945c8ab"
            ]
          },
          "agent_id": {
            "description": "The list of unique IDs for agents involved in the conversation",
            "examples": [
              [
                "619d95c0c063a5bf2b1efb7c"
              ]
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "agent_name": {
            "description": "A list of names of the agents involved the conversation, corresponding to the agent IDs",
            "examples": [
              [
                "Ada Lovelace"
              ]
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "agent_handle_time": {
            "type": "number",
            "format": "float",
            "description": "Time taken for a human agent to handle a conversation in seconds",
            "examples": [4]
          },
          "automated_resolution_classification": {
            "description": "Classification of either Resolved or Not Resolved for the conversation",
            "examples": [
              "Resolved"
            ],
            "type": "string"
          },
          "automated_resolution_classification_reason": {
            "description": "Explanation of the reason for the assigned automated_resolution_classification",
            "examples": [
              "The bot provided a detailed step-by-step guide on how to disable auto deposits, both on the mobile app and the web version."
            ],
            "type": "string"
          },
          "bot_handle_time": {
            "type": "number",
            "format": "float",
            "description": "Time taken for the AI agent to handle a conversation in seconds",
            "examples": [4]
          },
          "browser": {
            "description": "The browser used by the chatter",
            "examples": [
              "chrome"
            ],
            "type": "string"
          },
          "browser_version": {
            "description": "The version of the browser used by the chatter",
            "examples": [
              "95.0.4638.69"
            ],
            "type": "string"
          },
          "chatter_id": {
            "type": "string",
            "description": "Ada ID of the chatter having this conversation",
            "examples": [
              "5dbaef7283d791f585563d84"
            ]
          },
          "csat": {
            "type": "object",
            "description": "Object of customer satisfaction survey data for this conversation",
            "examples": [
              {
                "comment": null,
                "feedback": null,
                "is_positive": false,
                "resolved": null,
                "score": 3,
                "style": "EMOJI",
                "survey_type": "end_chat"
              }
            ]
          },
          "date_created": {
            "type": "string",
            "format": "date-time",
            "description": "Date and time the record was created (UTC)",
            "examples": [
              "2019-10-31T14:28:02.865000+00:00"
            ]
          },
          "date_updated": {
            "type": "string",
            "format": "date-time",
            "description": "Last date and time the record was updated (UTC)",
            "examples": [
              "2019-10-31T14:28:02.865000+00:00"
            ]
          },
          "device": {
            "description": "The device the chatter used, such as iphone, android, etc.",
            "examples": [
              "macos"
            ],
            "type": "string"
          },
          "end_user_id": {
            "description": "The End User ID used to identify the chatter profile in the conversation.",
            "examples": [
              "619d95c0c063a5bf2b1efb64e"
            ],
            "type": "string"
          },
          "generated_topic_id": {
            "description": "The unique ID Ada associated with the generated conversation topic",
            "examples": [
              "654952d3e90767ff49713fbf"
            ],
            "type": "string"
          },
          "generated_topic_label": {
            "description": "The title of the generated conversation topic",
            "examples": [
              "Billing Inquiries"
            ],
            "type": "string"
          },
          "generated_topic_v2_id": {
            "description": "The unique ID Ada associated with the generated conversation topic using Topics V2",
            "examples": [
              "654952d3e90767ff49713fb1"
            ],
            "type": "string"
          },
          "generated_topic_v2_title": {
            "description": "The title of the generated conversation topic using Topics V2",
            "examples": [
              "Password Reset Inquiries"
            ],
            "type": "string"
          },
          "generated_topic_v2_desc": {
            "description": "The descrtiption of the generated conversation topic using Topics V2",
            "examples": [
              "All conversations regarding resetting passwords"
            ],
            "type": "string"
          },
          "generated_topic_v2_parent_id": {
            "description": "The unique ID Ada associated with the generated conversation topic's parent category topic. Null if topic has no parent category topic.",
            "examples": [
              "654952d3e90767ff49713fb2"
            ],
            "type": "string"
          },
          "inquiry_summary": {
            "description": "An automatically generated summary of the customer's inquiry",
            "examples": [
              "The customer wanted to know how to temporarily disable auto deposits."
            ],
            "type": "string"
          },
          "is_engaged": {
            "type": "boolean",
            "description": "Whether the chatter engaged with the bot during this conversation",
            "examples": [true]
          },
          "is_escalated": {
            "type": "boolean",
            "description": "Whether the chatter escalated to a live agent during this conversation",
            "examples": [false]
          },
          "is_test_user": {
            "description": "Whether the conversation was started by a test user",
            "examples": [false],
            "type": "boolean"
          },
          "language": {
            "description": "The language the chatter used",
            "examples": [
              "en"
            ],
            "type": "string"
          },
          "metavariables": {
            "type": "object",
            "description": "Object of metavariables and their values active during this conversations",
            "examples": [
              {
                "browser": "chrome",
                "language": "en"
              }
            ]
          },
          "oauth_channel": {
            "description": "The channel used by Oauth",
            "examples": [
              "sms"
            ],
            "type": "string"
          },
          "platform": {
            "description": "Ada platform through which this conversation occurred",
            "examples": [
              "chat"
            ],
            "type": "string"
          },
          "record_last_updated": {
            "type": "string",
            "format": "date-time",
            "description": "Date and time the record was uploaded to the API",
            "examples": [
              "2019-10-31T14:28:02.865000+00:00"
            ]
          },
          "variables": {
            "type": "object",
            "description": "Object of autocapture and global variables and their values last active during this conversations",
            "examples": [
              {
                "account_number": "1234"
              }
            ]
          }
        }
      },
      "ConversationsResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Request status message",
            "examples": [
              "OK"
            ]
          },
          "data": {
            "description": "Records returned from the query",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Conversation"
            }
          },
          "next_page_uri": {
            "type": "string",
            "description": "Relative link to the next page of results matching the query",
            "examples": [
              "/data_api/conversations?updated_since=2019-12-10T20:20:07.308000%2B00:00"
            ]
          }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "description": "Unique ID for the message record",
            "examples": [
              "5d8a7d080afd19b55945c8ab"
            ]
          },
          "answer_id": {
            "type": "string",
            "description": "Internal ID of the answer (response) that triggered this message. Null if the message was not sent by an Ada bot, and None if it was sent by a generative bot",
            "examples": [
              "6392e0f865ba38041ddd5966"
            ]
          },
          "answer_title": {
            "type": "string",
            "description": "Title of the answer (response) that triggered this message. Null if the message was not sent by an Ada bot, or if it was sent by a generative bot",
            "examples": [
              "Greeting"
            ]
          },
          "chatter_id": {
            "type": "string",
            "description": "Internal ID of the chatter who sent this message. Corresponds to the `_id` field of Chatter objects",
            "examples": [
              "6009dd3c81dfae3a4e990acb"
            ]
          },
          "conversation_id": {
            "type": "string",
            "description": "Internal ID of the conversation in which this message was sent. Corresponds to the `_id` field of Conversation objects",
            "examples": [
              "5dba43ebedb828146bc871b6"
            ]
          },
          "date_created": {
            "type": "string",
            "format": "date-time",
            "description": "Time the record was created (UTC)",
            "examples": [
              "2019-10-31T14:28:02.865000+00:00"
            ]
          },
          "link_was_clicked": {
            "type": "boolean",
            "description": "Indicates if the link in the answer (response) was clicked",
            "examples": [false]
          },
          "message_data": {
            "type": "object",
            "description": "Data associated with this message",
            "examples": [
              {
                "_type": "greeting",
                "external_chat_id": "\u003Cuuid_v4_id\u003E",
                "reviewable_message": false
              }
            ]
          },
          "recipient": {
            "type": "string",
            "description": "Recipient of this message",
            "examples": [
              "ada"
            ]
          },
          "record_last_updated": {
            "type": "string",
            "format": "date-time",
            "description": "Date and time the record was uploaded to the API (UTC)",
            "examples": [
              "2019-10-31T14:28:02.865000+00:00"
            ]
          },
          "review": {
            "type": "integer",
            "format": "int32",
            "description": "Rating given to this answer by the chatter",
            "examples": [0]
          },
          "sender": {
            "type": "string",
            "description": "Sender of this message",
            "examples": [
              "b9e51eae-5449-4a46-b6ce-aef2dcb4e067"
            ]
          },
          "in_response_to": {
            "description": "Internal ID of the message that this message is in response to. None if the message is not in response to another message",
            "type": "string",
            "examples": [
              "6392e0f865ba38041ddd5966"
            ]
          }
        }
      },
      "MessagesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "description": "Records returned from the query",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            }
          },
          "message": {
            "type": "string",
            "description": "Request status message",
            "examples": [
              "OK"
            ]
          },
          "next_page_uri": {
            "type": "string",
            "description": "Relative link to the next page of results matching the query",
            "examples": [
              "/data_api/v1.4/messages?created_since=2019-12-10T20:20:07.308000%2B00:00"
            ]
          }
        }
      }
    }
  },
  "paths": {
    "/data_api/v1.4/conversations": {
      "get": {
        "parameters": [
          {
            "in": "query",
            "name": "created_since",
            "required": false,
            "description": "Return records that were created after this date.  Note that `updated_since` and `created_since` are mutually exclusive, so you must only use one in a request. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.",
            "schema": {
              "type": "string",
              "format": "date-time",
              "examples": [
                "2023-07-03T00:00:00Z"
              ]
            }
          },
          {
            "in": "query",
            "name": "updated_since",
            "required": false,
            "description": "Return records that were updated after this date. Note that `updated_since` and `created_since` are mutually exclusive, so you must only use one in a request. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.",
            "schema": {
              "type": "string",
              "format": "date-time",
              "examples": [
                "2023-07-03T00:00:00Z"
              ]
            }
          },
          {
            "in": "query",
            "name": "page_size",
            "required": false,
            "description": "Number of records to return in response. The maximum and default is 10000, the minimum is 100.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 10000,
              "minimum": 100,
              "maximum": 10000,
              "examples": [100]
            }
          },
          {
            "in": "query",
            "name": "created_to",
            "required": false,
            "description": "Return records that were created earlier than this date. If `created_since` is used and this parameter is not specified, this value defaults to 7 days after `created_since`.",
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "examples": [
                "2019-12-10T20:20:07.308000+00:00"
              ]
            }
          },
          {
            "in": "query",
            "name": "updated_to",
            "required": false,
            "description": "Return records that were updated earlier than this date. If `updated_since` is used and this parameter is not specified, this value defaults to 7 days after `updated_since`.",
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "examples": [
                "2019-12-10T20:20:07.308000+00:00"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ada successfully processed the request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Incorrect query."
          },
          "408": {
            "description": "Database query timed out."
          },
          "422": {
            "description": "Invalid arguments or missing data for a required field."
          },
          "429": {
            "description": "Requests are within 1 s of each other."
          },
          "500": {
            "description": "Request timed out or there was a database error."
          },
          "502": {
            "description": "Nginx gateway issue on Ada's servers."
          },
          "503": {
            "description": "Server temporarily unable to handle the request."
          },
          "504": {
            "description": "Temporary infrastructure error on Ada's servers."
          }
        },
        "summary": "Return conversations matching the parameters",
        "description": "Returns a list of `conversation` objects along with a status message and `next_page_uri` if applicable.",
        "tags": [
          "Conversations"
        ]
      }
    },
    "/data_api/v1.4/messages": {
      "get": {
        "parameters": [
          {
            "in": "query",
            "name": "created_since",
            "required": true,
            "description": "Return records that were created after this date. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.",
            "schema": {
              "type": "string",
              "format": "date-time",
              "examples": [
                "2019-12-10T20:20:07.308000+00:00"
              ]
            }
          },
          {
            "in": "query",
            "name": "conversation_id",
            "required": false,
            "description": "Return records with a `conversation_id` that matches this id.",
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "examples": [
                "60bd36dc8f17071b5c5bec12"
              ]
            }
          },
          {
            "in": "query",
            "name": "page_size",
            "required": false,
            "description": "Number of records to return in response. The maximum and default is 10000, the minimum is 100.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 10000,
              "minimum": 100,
              "maximum": 10000,
              "examples": [100]
            }
          },
          {
            "in": "query",
            "name": "created_to",
            "required": false,
            "description": "Return records that were created earlier than this date. If not specified, this value defaults to 7 days after `created_since`. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.",
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "examples": [
                "2019-12-10T20:20:07.308000+00:00"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ada successfully processed the request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessagesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Incorrect query."
          },
          "408": {
            "description": "Database query timed out."
          },
          "422": {
            "description": "Invalid arguments or missing data for a required field."
          },
          "429": {
            "description": "Requests are within 1 s of each other."
          },
          "500": {
            "description": "Request timed out or there was a database error."
          },
          "502": {
            "description": "Nginx gateway issue on Ada's servers."
          },
          "503": {
            "description": "Server temporarily unable to handle the request."
          },
          "504": {
            "description": "Temporary infrastructure error on Ada's servers."
          }
        },
        "summary": "Return messages matching the parameters",
        "description": "Returns a list of `message` objects along with a status message and `next_page_uri` if applicable.",
        "tags": [
          "Messages"
        ]
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": true,
    "samples-enabled": true
  },
  "tags": [
    {
      "name": "data_api_conversations",
      "description": ""
    },
    {
      "name": "data_api_messages",
      "description": ""
    }
  ]
}