Connecting GraphQL API

Overview

Prerequisites

• GraphQL endpoint URL (e.g., https://api.example.com/graphql)
• API credentials (Bearer token or API key)
• GraphQL API documentation (optional, but helpful)

Step-by-Step Instructions

1. Navigate to Data Sources

1. Go to Data Sources from the main navigation
2. Click Connect New Data Source
3. Select GraphQL API from the available options

2. Enter Connection Details

• Connection Name: Give your API a descriptive name (e.g., "Contentful GraphQL API", "Shopify GraphQL API")
• GraphQL Endpoint URL: Enter the full URL to your GraphQL endpoint
• - Example: https://api.example.com/graphql
• - Example: https://shopify.com/admin/api/2024-01/graphql.json

3. Configure Authentication

• Authentication Type: Select "Bearer Token"
• Bearer Token: Enter your API bearer token
• Most GraphQL APIs use Bearer token authentication

• Authentication Type: Select "API Key"
• API Key: Enter your API key
• API Key Header Name: Specify the header name (default: "X-API-Key")
• - Common values: X-API-Key, Authorization

4. Schema Introspection

• Auto-introspect Schema on Connect: Enable this option to automatically fetch and store your GraphQL schema
• This helps with query building and validation
• The schema will be stored for later use in agent configuration

5. Test Connection

1. Click Test Connection to verify your GraphQL endpoint is accessible
2. The test will execute a simple introspection query
3. If successful, you'll see a green success message

6. Select Access Mode

• Online (Live Connection): Real-time GraphQL queries
• Offline (Cached Data): Use cached query responses
• Hybrid: Combination of both

7. Connect GraphQL API

1. Click Connect GraphQL API
2. Wait for the connection to be established
3. If schema introspection is enabled, the schema will be fetched automatically
4. You'll be redirected to see your connected data source

GraphQL Query Examples

Simple Query

Query with Variables

Mutation

Common GraphQL APIs

Shopify GraphQL API

• Endpoint: https://{shop}.myshopify.com/admin/api/{version}/graphql.json
• Authentication: Bearer token (Admin API access token)

Contentful GraphQL API

• Endpoint: https://graphql.contentful.com/content/v1/spaces/{space_id}
• Authentication: Bearer token (Content Delivery API access token)

Troubleshooting

Connection Failed

• Verify your GraphQL endpoint URL is correct
• Check if the endpoint requires HTTPS
• Ensure your IP is whitelisted (if required)

Authentication Errors

• Verify your token/key is valid and not expired
• Check the correct header name for API keys
• Ensure your token/key has the required permissions for the API

Schema Introspection Failed

• Some GraphQL APIs disable introspection for security
• If introspection fails, you can still use the API manually
• Check the API documentation for available queries and mutations

Query Errors

• Verify your GraphQL query syntax is correct
• Check if the fields you're querying exist in the schema
• Ensure variables are provided if the query requires them

401 Unauthorized

• Double-check your credentials
• Verify the authentication method matches the API requirements
• Check if the token needs to be refreshed

Next Steps

• Go to Agent Builder to create an AI agent using this GraphQL API
• Use the introspected schema to build queries
• Configure your agent to execute GraphQL queries and mutations