GraphQL API

The Call AI GraphQL endpoint, the query mechanics it supports, and how it reports errors.

The Call AI GraphQL API returns conversation intelligence data, such as call recordings, transcripts, and insights, from a single endpoint. You choose the fields you need in the query, so one request returns exactly the data you ask for.

Send all requests to https://api-gateway.callai.mindtickle.com/public/graphapi with Content-Type: application/json and Authorization: Bearer ACCESS_TOKEN. See Authentication for the token.

GraphQL overview

GraphQL is a query language for APIs that lets you request exactly the data you need. The selection set defines which fields the server returns, so you can limit a request to the information your integration needs.

For example, the following query fetches a list of recordings with the recordingsV2 operation:

{
  recordingsV2(
    first: 1
    after: "0"
    filters: { categoryId: "1" }
    sort: { sortType: "start_date", sortOrder: desc }
  ) {
    edges {
      node {
        id
        mediaUrls {
          streamingSource
        }
      }
    }
  }
}

Interacting with the API

You can interact directly with the Call AI API with standard HTTP clients or command-line tools such as cURL.

If you encounter errors related to exhausted credits, see Error handling and reduce the batch size before retrying.

The following cURL command authenticates and fetches a list of recordings. Replace ACCESS_TOKEN with your OAuth access token.

curl --location 'https://api-gateway.callai.mindtickle.com/public/graphapi' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer ACCESS_TOKEN' \
 --data '{"query":"query {\n    recordingsV2(\n        first: 1,\n        after: \"0\",\n        filters: {\n            categoryId: \"1\"\n        }\n        sort: {\n            sortType: \"start_date\",\n            sortOrder: asc\n        }\n    )\n    {\n        edges {\n            node {\n                id\n                mediaUrls {\n                    streamingSource\n                }\n            }\n        }\n    }\n}\n","variables":{}}'

Endpoints

Query call data: fetch recordings with the recordingsV2 query, including participants, transcripts, themes, stats, and scores.
Download call recordings: retrieve pre-signed URLs for the audio and video files of a recording.

Error handling

In GraphQL, a request may return an HTTP 200 OK status even if it fails. Check the response body for an errors array as well as checking the HTTP status. GraphQL responses can contain both partial data and errors; do not assume HTTP 200 means every requested field succeeded.

The following structure uses type placeholders. Replace "number" and "string" with the corresponding values when interpreting an error response.

{
  "errors": [
    {
      "message": "string",
      "locations": [
        {
          "line": "number",
          "column": "number"
        }
      ],
      "path": ["string"],
      "extensions": {
        "code": "string",
        "originalError": {
          "code": "string",
          "message": "string",
          "details": {}
        },
        "creditsInfo": {
          "maximumAvailable": "number",
          "currentlyAvailable": "number",
          "willResetAt": "string"
        },
        "requestedQueryCost": "number"
      }
    }
  ],
  "data": null
}

Recommended actions:

For each object in errors, if extensions.code is INSUFFICIENT_CREDITS, you have exceeded the rate limit. Reduce your pagination size or request hit rate. Check the creditsInfo object in the error response to view your current availability.
For each object in errors, if extensions.code is INTERNAL_SERVER_ERROR and its message contains the string /authenticate - Request failed with status code 404, your access token has expired. Refresh the access token. See Refresh an access token.