# GraphQL API

[GraphQL](https://graphql.org/) provides [queries](https://graphql.org/learn/queries) for fetching data and a set of [mutations](https://graphql.org/learn/queries/#mutations) for modifying objects.

## GraphQL endpoint

The GraphQL endpoint can be found at `https://toil.kitemaker.co/developers/graphql`. [Introspection](https://graphql.org/learn/introspection/) is enabled for this endpoint, so you can point your favorite GraphQL developer tool (like [GraphQL Playground](https://github.com/graphql/graphql-playground) or [Postman](https://www.postman.com/graphql/)) 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:

```graphql
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:

```graphql
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:

```graphql
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 <hi@kitemaker.co> and we'll improve it right away.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://guide.kitemaker.co/developer/02-graphql.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.