What type of Endpoints are exposed via Data API

Data API exposes the 5 REST endpoints which supports GET method to extract data on AI assistant analytics. These REST endpoints follow the OData protocol.

📘

What is OData ?

OData (Open Data Protocol) is a standardized protocol developed by Microsoft for building and consuming RESTful APIs. It enables the querying and manipulation of data using a uniform, HTTP-based interface. OData supports operations like filtering, sorting, paging, and data expansion, making it easier to interact with data sources such as databases, file systems, or web services in a consistent manner. Read more about OData here.

Authentication and Authorization

Data API support API key & Oauth2 based authentication. The API credentials will be generated by Moveworks team and shared through a secured email. The API credentials don't have any expiry period or credential rotation policy applied to them.

API Token

1. With the API token, you can use the following cURL command to access Data API

curl -X GET "https://api.moveworks.ai/export/v1beta2/records/conversations" \
     -H "Authorization: Bearer <YOUR_API_TOKEN>" \
     -H "Accept application/json"

OAuth2.0

OAuth 2.0 is the industry-standard protocol for authorization. It is widely used in the SaaS applications. If you are new OAuth2.0, you can read more about it here: OAuth2.0 documentation.

1. With the client_id and client_secret you can use the following cURL command to get the authorization.

   Bash

   curl --request POST --location 'https://api.moveworks.ai/oauth/v1/token' \
   --header 'Content-Type: application/json' \
   --data '{
       "client_id": "<YOUR_CLIENT_ID>",
       "client_secret": "<YOUR_CLIENT_SECRET>",
       "grant_type": "client_credentials"
   }'
   

2. Upon successful API call, you will get the ACCESS_TOKEN. You can use the access token to access the API using the following cURL to connect with the API. Please note that the ACCESS_TOKEN expires after an hour. You have repeat step 2 to generate a new ACCESS_TOKEN.

   Bash

   curl -X GET "https://api.moveworks.ai/export/v1beta2/records/conversations" \
        -H "Authorization: Bearer <ACCESS_TOKEN>" \
        -H "Accept application/json"
   

3. If you the hit the endpoint oauth/v1/token a new token will be generated however the previous token will still work. There is no limitation

OData Functionalities

Pagination

Data API supports client-side pagination. To specify the desired number of results per page with API, you can use $top & $skip parameters. These are standard parameters in OData.

For instance if you want to get the first 10 conversations on 3rd of Feb

curl --location 'https://api.moveworks.ai/export/v1beta2/records/conversataions?$fitler=last_updated_time le 2023-01-01T00:00:00Z&$top=10' \
--header 'Authorization: Bearer <YOUR_API_TOKEN>'

In server side paging, Moveworks have set the default number of results per API to be 100 results. If the results are more the 100 then the API provides a mechanism to fetch the next set of results.

Use the $skip query parameter to skip a certain number of records from the API response. For example let's consider going through the next step of 100 records from an API response. The "Odata.nextlink" attribute contains the link for next set of 100 rows.

{
    "@odata.context": "https://api.moveworks.ai/export/v1beta2/records/$metadata#interactions",
    "@odata.nextLink": "https://api.moveworks.ai/export/v1beta2/records/interactions?$skip=100",
    "value": [
        {
            "actor": "user",
            "context_interaction_id": null,
            "conversation_id": "ZvR4wDMhIP4H",
            "created_time": "2025-02-07T18:38:22.295Z",
            "detail": {
                "content": "1738959482_03:001_31da767dfe4b55da212b210707cc7d0abdd1266b1e44d6ae736a56080accd574",
                "domain": "OTHER",
                "entity": null
            },
            "id": "Bmhgygio176B",
            "last_updated_time": "2025-02-27T06:29:53.317Z",
            "platform": "slack",
            "type": "INTERACTION_TYPE_FREE_TEXT",
            "user_id": "15777330132204530423"
        },
        {
            "actor": "user",
            "context_interaction_id": null,
            "conversation_id": "wkOkW9Ba6xIZ",
            "created_time": "2025-02-07T22:58:41.935Z",
            "detail": {
                "content": "1738973603_03:001_07a03a55e0b89cfe79a611f38803886042ae83e28c8f1ec180736ded55116e91",
                "domain": "OTHER",
                "entity": null
            },
            "id": "FR3O1DYCciNQ",
            "last_updated_time": "2025-02-27T06:29:53.317Z",
            "platform": "slack",
            "type": "INTERACTION_TYPE_FREE_TEXT",
            "user_id": "6057146113635593169"
        },
        {
            "actor": "bot",
            "context_interaction_id": "bN2g6Zirrld2",
            "conversation_id": "ttCdVs0wCiF_",
            "created_time": "2025-02-07T16:33:42.239Z",
            "detail": {
                "content": "I'm here and ready to assist you with any questions or tasks you have. How can I help you today?"
            },
            "id": "VIatQNTBmaMu",
            "last_updated_time": "2025-02-27T06:29:53.317Z",
            "platform": "movewebchat",
            "type": "INTERACTION_TYPE_BOT_MESSAGE",
            "user_id": "3145103286822458043"
        }
    ]
}

Follow the below request to fetch the next set of 100 rows.

curl --location 'https://api.moveworks.ai/export/v1beta2/records/interactions?$skip=100' \
--header 'Authorization: Bearer <YOUR_API_TOKEN>'

When you have paginated through all data and there is no more data to be fetched from the API. In this scenario "Odata.nextlink" attribute will be absent from the API response.

Query parameters

$select parameter

$select query parameter lets you return a set of properties that are different than the default set for an individual resource or a collection of resources. With $select, you can specify a subset. By default all properties will be returned.

For instance, if you want to retrieve only actor and the platform from the interactions table.

curl --location 'https://api.moveworks.ai/export/v1beta2/records/interactions?$select=actor,platform' \
--header 'Authorization: <YOUR API TOKEN>'

$filter parameter

Use the $filter query parameter to return a subset of records. For example if you want to only return plugin call records for Knowledge Base plugin.

The expression specified with $filter is evaluated for each results in the API response, and only the records where the expression evaluates to true are included in the API response. Please note if no results satisfy the condition the returned results will be empty.

$orderby parameter

The "$orderby" query parameter lets to specify the sort order of the items returned from the API. The default order is ascending.

For instance, in order to order the results by the descending order of date, you can use the following query.

curl --location 'https://api.moveworks.ai/export/v1beta2/records/interactions?%24orderby=last_updated_time desc' \
--header 'Authorization: <YOUR API TOKEN>'

Rate limiting

Data API imposes the rate limit at an organization basis. The current rate limit is 60 Request/Minute. This limit applies collectively to all API credentials generated for your organization. We recommend you to introduce wait time in between your API calls.

You will start receiving a Rate limit exhausted error if the number of request are exceeding 60 Request/Minute quota.

Timeouts

Moveworks has imposed timeout to kill queries that takes too long to process.

The default time out for all queries is: 3 mins.

If your request response is too long; Try to reduce the date range on which you are requesting the data.