GraphQL

GraphQL is Biztraak’s primary application API. It exposes queries for reading platform data, mutations for changing state, and subscriptions for selected real-time workflow updates.

Endpoints

Use the API host for the environment you are connected to:

• GraphQL HTTP endpoint: /graphql
• GraphQL WebSocket endpoint: /graphql for subscriptions
• GraphQL Voyager: /graphql-voyager

The Voyager page is a visual schema explorer backed by the /graphql endpoint. Protected operations still require the same authenticated context as other API calls.

Authentication

Send a bearer token with GraphQL HTTP requests:

Authorization: Bearer <your-token>
Content-Type: application/json

The token identifies the caller and tenant context. GraphQL authorization is then applied to the operation and the objects it accesses. See Authentication and Authorization before connecting an integration.

Request format

GraphQL requests are JSON documents containing a query and, when needed, variables and operationName:

{
  "query": "query ProjectList($teamId: UUID!) { projects(where: { teamId: { eq: $teamId } }) { nodes { id name } } }",
  "variables": {
    "teamId": "00000000-0000-0000-0000-000000000000"
  }
}

The exact field names, arguments, input types, and return selections are defined by the live schema. Use Voyager or introspection in a client to inspect the schema available to your environment rather than copying an operation intended for a different version.

Queries, mutations, and subscriptions

• Queries read projects, components, deployments, service providers, workflows, and other exposed resources.
• Mutations perform supported changes such as creating or updating resources and starting workflow operations.
• Subscriptions deliver selected live updates, including deployment and workflow events, over WebSocket.

GraphQL responses can contain both data and errors. Check both in client code, especially for mutations and long-running operations. A successful request at the HTTP or transport layer does not necessarily mean that the requested business operation succeeded.

Connections, filtering, and sorting

Many collection fields use the Relay-style connection shape:

query ListProjects($first: Int!, $after: String) {
  projects(first: $first, after: $after, order: { name: ASC }) {
    nodes { id name }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}

Use the live schema to confirm the connection’s argument names and the fields available for a particular resource. Collection fields that expose filtering and sorting arguments can be identified from that schema. Prefer cursor pagination and request only the fields the integration needs.

Operation domains

The schema is organized around platform domains. Common areas include:

• teams, users, roles, invitations, and billing
• projects, components, providers, environments, and deployments
• Git repositories, pipelines, and Terraform operations
• Marketplace store items, reviews, and payment-plan workflows
• virtual machines and VM-hosted workloads
• agent workflows and workflow events
• forums, notifications, observability, and database tooling

Availability and authorization vary by team, plan, feature flag, and target resource. Voyager is the best source for the exact current field names and arguments.

GraphiQL and other clients

Biztraak does not currently serve an embedded GraphiQL page. You can use an external GraphiQL installation, Apollo Sandbox, Insomnia, or another GraphQL client by configuring it with the environment’s /graphql endpoint and the required bearer token.

When using a browser-based client, do not paste production tokens into a shared or third-party environment. Prefer a local client or the built-in Voyager page when you only need to inspect the schema.

Practical workflow

1. Create or obtain an API token using Authentication.
2. Open /graphql-voyager to understand the available types and relationships.
3. Start with a read-only query and request only the fields your integration needs.
4. Add variables instead of interpolating user input into query strings.
5. Add mutations and subscriptions only after the corresponding authorization and lifecycle behavior is understood.
6. Monitor the returned errors and the platform workflow state for asynchronous operations.

For REST endpoints and route examples, see REST API reference. For retries, asynchronous work, and compatibility guidance, see API operations. For a broader API path, see API Overview.