GraphQL API

GraphQL provides queries for fetching data and a set of mutations for modifying objects.

GraphQL endpoint

The GraphQL endpoint can be found at https://toil.kitemaker.co/developers/graphql. Introspection is enabled for this endpoint, so you can point your favorite GraphQL developer tool (like GraphQL Playground or Postman) at the API to retrieve the schema and interact with the API. Please note: even introspecting the API requires the client to be authenticated.

Authentication

Authentication currently based on a simple Bearer token scheme. When making any request to the server, set the Authorization HTTP header:

Authorization: Bearer <your-token-here>

There are currently two token types:

• Personal access tokens - these tokens operate on the API as a particular user (within a single organization)

• Application tokens - these tokens operate on the API as their own actor (i.e. a service user within a single organization)

Personal access tokens have access to the same spaces to which their associated user has access. Application tokens only have access to non-private spaces currently.

Tokens are obtained in Kitemaker by searching for "manage developer settings" in the Kitemaker Command or by clicking the cogwheel/settings icons for your organization.

Examples

Fetching information about your organization and spaces:

query Org {
  organization {
    id
    name
    spaces {
      id
      name
      labels {
        id
        name
        color
      }
      statuses {
        id
        name
        type
        default
      }
    }
    users {
      id
      username
    }
  }
}

Fetching work items in a space:

query WorkItems {
  workItems(spaceId: "0529cc0727477100") {
    workItems {
      id
      title
      description
      labels {
        id
      }
      comments {
        id
        body
        actor {
          ... on User {
            id
            username
          }
          ... on IntegrationUser {
            id
            externalName
          }
          ... on Integration {
            id
            type
          }
          ... on Application {
            id
            name
          }
        }
      }
    }
  }
}

The workItems query will return limited number of work items. It will also return a boolean called hasMore and a string called cursor. When hasMore is true, you can pass cursor to the work items query to fetch the next batch of items:

query WorkItems {
  workItems(spaceId: "0529cc0727477100", cursor: "50") {
    workItems {
      id
      title
      description
      labels {
        id
      }
      comments {
        id
        body
        actor {
          ... on User {
            id
            username
          }
          ... on IntegrationUser {
            id
            externalName
          }
          ... on Integration {
            id
            type
          }
          ... on Application {
            id
            name
          }
        }
      }
    }
  }

Please note: the cursor property should be treated as an opaque string. It currently resembles (i.e. actually is) a work item number, but this should not be relied upon.

GraphQL API Schema

The annotated schema for the Kitemaker GraphQL API is located here: https://github.com/kitemakerhq/docs/blob/main/kitemaker.graphql

If anything in the API is unclear or you find the comments to be lacking, email us at [email protected] and we'll improve it right away.