GraphQL API

Create seamless integrations with WisdomAI using our comprehensive GraphQL API. Access domains, tables, and analytics data programmatically to build custom applications and workflows.

The GraphQL API is designed for external integrations. All operations require proper authentication and respect your organization’s access controls.

Get started

The WisdomAI GraphQL API provides a single endpoint for all operations:

https://{ACCOUNT}.askwisdom.ai/graphql

Replace {ACCOUNT}.askwisdom.ai with the base URL of your WisdomAI tenant, the same domain you use to log in. Both askwisdom.ai and wisdom.ai are valid depending on your deployment.

The API supports queries, mutations, and real-time subscriptions. Subscriptions use a WebSocket-based model that lets users ask questions related to business intelligence and receive structured responses, including tabular data and SQL queries.

WebSocket connection

For real-time subscriptions, use the following WebSocket endpoint:

wss://{ACCOUNT}.askwisdom.ai/graphql

Authentication

WisdomAI supports two authentication flows depending on your use case:

API authentication

For direct API access, authenticate using a JWT session token obtained via the Descope authentication system.

1. Obtain access key

   Contact WisdomAI support at [e-mail] to obtain your dedicated access key.

2. Exchange access key for JWT token

   Use WisdomAI’s GraphQL API exchangeAccessToken query to exchange your access key for a JWT token.

   query ExchangeAccessToken($accessToken: String!) {
     exchangeAccessToken(accessToken: $accessToken)
   }
   
3. Pass token in requests

   Include the session token in all API requests and WebSocket connection payloads.

   Authorization: Bearer YOUR_SESSION_TOKEN
   

Embedded user authentication

For embedding scenarios, the flow is different. Instead of exchangeAccessToken, you call impersonateUser with your Descope access key to obtain a short-lived JWT for the embedded user. That JWT is passed as the token query parameter in the iframe URL, not in an Authorization header.

See the Embedding overview for the full end-to-end flow.

Error handling

The WisdomAI GraphQL API returns HTTP 200 even when an operation fails. Always inspect the response body, not the HTTP status code. See Error handling for the full reference including response shapes and status codes.

For any queries or support, contact our API team at [e-mail].

Related articles

GraphQL primer

New to GraphQL? Start here for a REST developer’s introduction

Exchange Access Token

Authenticate with the GraphQL API using access keys

Queries

Learn about available queries for fetching data

Mutations

Discover mutations for creating and updating resources

Subscriptions

Real-time data subscriptions and live updates

Error handling

How to handle HTTP 200 failures and mutation status codes