> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wisdom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  The GraphQL API is designed for external integrations. All operations require proper authentication and respect your organization's access controls.
</Note>

## Get started

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

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

<Note>
  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.
</Note>

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.

<Steps>
  <Step title="Obtain access key" titleSize="h4">
    Contact WisdomAI support at `support@askwisdom.ai` to obtain your dedicated access key.
  </Step>

  <Step title="Exchange access key for JWT token" titleSize="h4">
    Use WisdomAI's GraphQL API `exchangeAccessToken` query to exchange your access key for a JWT token.

    ```graphql theme={null}
    query ExchangeAccessToken($accessToken: String!) {
      exchangeAccessToken(accessToken: $accessToken)
    }
    ```
  </Step>

  <Step title="Pass token in requests" titleSize="h4">
    Include the session token in all API requests and WebSocket connection payloads.

    ```
    Authorization: Bearer YOUR_SESSION_TOKEN
    ```
  </Step>
</Steps>

### 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](/integrations/embeddings/embedding) for the full end-to-end flow.

## Error handling

<Warning>
  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](/integrations/embeddings/error-handling) for the full reference including response shapes and status codes.
</Warning>

<Info>
  For any queries or support, contact our API team at [**support@askwisdom.ai**](mailto:support@askwisdom.ai).
</Info>

## Related articles

<CardGroup cols={2}>
  <Card title="GraphQL primer" icon="book" href="/integrations/graphql-api/graphql-primer">
    New to GraphQL? Start here for a REST developer's introduction
  </Card>

  <Card title="Exchange Access Token" icon="key" href="/integrations/graphql-api/queries/auth/exchange-access-token">
    Authenticate with the GraphQL API using access keys
  </Card>

  <Card title="Queries" icon="magnifying-glass" href="/integrations/graphql-api/GraphQL-API">
    Learn about available queries for fetching data
  </Card>

  <Card title="Mutations" icon="pen-to-square" href="/integrations/graphql-api/GraphQL-API">
    Discover mutations for creating and updating resources
  </Card>

  <Card title="Subscriptions" icon="wifi" href="/integrations/graphql-api/GraphQL-API">
    Real-time data subscriptions and live updates
  </Card>

  <Card title="Error handling" icon="circle-exclamation" href="/integrations/embeddings/error-handling">
    How to handle HTTP 200 failures and mutation status codes
  </Card>
</CardGroup>