The GraphQL API is a modern alternative to traditional REST endpoints, offering a flexible and efficient way to interact with ChatBotKit platform resources. Unlike REST APIs where you make multiple requests to different endpoints, GraphQL allows you to request exactly the data you need in a single query, reducing network overhead and improving application performance.

Understanding GraphQL

GraphQL uses a strongly-typed schema system that defines all available operations and data structures. This schema serves as a contract between the client and server, enabling powerful tooling like auto-completion, validation, and automatic documentation generation. The GraphQL endpoint supports both queries (for reading data) and mutations (for modifying data), all through a single HTTP POST request.

The platform's GraphQL implementation uses GraphQL Yoga, providing a robust, production-ready GraphQL server with streaming support for long-running operations. The API automatically handles authentication through your session and enforces the same access controls as REST endpoints.

Executing GraphQL Queries

To execute a GraphQL query, send a POST request to the GraphQL endpoint with your query string and any required variables. The query language is intuitive and self-documenting, allowing you to specify exactly which fields you want to retrieve.

POST /api/v1/graphql
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "query": "query GetBots { bots(first: 10) { items { id name description } } }",
  "variables": {}
}
http

The response contains a data field with your requested information and an optional errors array if any issues occurred during execution. This structure allows partial success - you might receive some data along with errors for fields that couldn't be resolved.

Using Variables and Operation Names

For complex queries with dynamic values, use GraphQL variables instead of string interpolation. Variables are type-checked against your query, providing compile-time safety and preventing injection vulnerabilities.

POST /api/v1/graphql
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "query": "query GetBot($id: ID!) { bot(id: $id) { id name backstory model } }",
  "variables": {
    "id": "bot_abc123"
  },
  "operationName": "GetBot"
}
http

The operationName field is optional but recommended when your query document contains multiple operations. It explicitly tells the server which operation to execute, improving clarity and enabling better monitoring and debugging.

Performing Mutations

Mutations modify server-side data and follow the same request format as queries. By convention, mutation operations are named with verbs that describe the action being performed.

POST /api/v1/graphql
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "query": "mutation CreateBot($input: CreateBotInput!) { createBot(input: $input) { id name } }",
  "variables": {
    "input": {
      "name": "Support Assistant",
      "description": "Helps customers with common questions"
    }
  }
}
http

Mutations return the newly created or modified resource, allowing you to immediately access updated data without making an additional query. This pattern reduces network round-trips and ensures consistency between your local state and the server.

Error Handling

GraphQL errors are returned in a structured format within the response, allowing you to handle different error types appropriately. Errors include detailed information about what went wrong, including field paths and error codes when applicable.

The platform uses streaming responses for GraphQL operations, which means long-running queries won't timeout prematurely. If an error occurs after partial data has been sent, the stream will include the error information in the GraphQL errors array while preserving any successfully resolved data.

Best Practice: Use GraphQL introspection queries during development to explore the available schema, types, and operations. Most GraphQL clients provide built-in schema exploration tools that auto-complete field names and validate queries against the schema before execution.

Note: The GraphQL API provides access to the same resources as REST endpoints but with more flexibility in data fetching. For simple CRUD operations, REST endpoints may be more straightforward, while GraphQL excels at complex data requirements and reducing over-fetching.