• Running examples
  • Command line
  • GraphiQL
• Queries and mutations
  • Graph traversal
  • Authorization
  • Mutations
    • Creation mutations
    • Update mutations
    • Deletion mutations
  • Introspective queries
  • Query complexity
• Sorting
• Pagination

Get started with GitLab GraphQL API

This guide demonstrates basic usage of the GitLab GraphQL API.

Read the GraphQL API style guide for implementation details aimed at developers who wish to work on developing the API itself.

Running examples

The examples documented here can be run using:

• The command line.
• GraphiQL.

Command line

You can run GraphQL queries in a curl request on the command line on your local computer. A GraphQL request can be made as a POST request to /api/graphql with the query as the payload. You can authorize your request by generating a personal access token to use as a bearer token.

Example:

GRAPHQL_TOKEN=<your-token>
curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer $GRAPHQL_TOKEN" \
     --header "Content-Type: application/json" --request POST \
     --data "{\"query\": \"query {currentUser {name}}\"}"

GraphiQL

GraphiQL (pronounced “graphical”) allows you to run queries directly against the server endpoint with syntax highlighting and autocomplete. It also allows you to explore the schema and types.

The examples below:

• Can be run directly against GitLab.
• Works against GitLab.com without any further setup. Make sure you are signed in and navigate to the .

Refer to running GraphiQL for more information.

Queries and mutations

The GitLab GraphQL API can be used to perform:

• Queries for data retrieval.
• Mutations for creating, updating, and deleting data.

GitLab GraphQL Schema outlines which objects and fields are available for clients to query and their corresponding data types.

Example: Get only the names of all the projects the currently logged in user can access (up to a limit) in the group gitlab-org.

query {
  group(fullPath: "gitlab-org") {
    id
    name
    projects {
      nodes {
        name
      }
    }
  }
}

Example: Get a specific project and the title of Issue #2.

query {
  project(fullPath: "gitlab-org/graphql-sandbox") {
    name
    issue(iid: "2") {
      title
    }
  }
}

Graph traversal

When retrieving child nodes use:

• The edges { node { } } syntax.
• The short form nodes { } syntax.

Underneath it all is a graph we are traversing, hence the name GraphQL.

Example: Get the name of a project, and the titles of all its issues.

query {
  project(fullPath: "gitlab-org/graphql-sandbox") {
    name
    issues {
      nodes {
        title
        description
      }
    }
  }
}

More about queries:

Authorization

Authorization uses the same engine as the GitLab application (and GitLab.com). If you’ve signed in to GitLab and use GraphiQL, all queries are performed as you, the signed in user. For more information, read the GitLab API documentation.

Mutations

Mutations make changes to data. We can update, delete, or create new records. Mutations generally use InputTypes and variables, neither of which appear here.

Mutations have:

• Inputs. For example, arguments, such as which emoji you’d like to award, and to which object.
• Return statements. That is, what you’d like to get back when it’s successful.
• Errors. Always ask for what went wrong, just in case.

Creation mutations

Example: Let’s have some tea - add a :tea: reaction emoji to an issue.

mutation {
  awardEmojiAdd(input: { awardableId: "gid://gitlab/Issue/27039960",
      name: "tea"
    }) {
    awardEmoji {
      name
      description
      unicode
      emoji
      unicodeVersion
      user {
        name
      }
    }
    errors
  }
}

Example: Add a comment to the issue. In this example, we use the ID of the GitLab.com issue. If you’re using a local instance, you must get the ID of an issue you can write to.

mutation {
  createNote(input: { noteableId: "gid://gitlab/Issue/27039960",
      body: "*sips tea*"
    }) {
    note {
      id
      body
      discussion {
        id
      }
    }
    errors
  }
}

Update mutations

When you see the result id of the note you created, take a note of it. Let’s edit it to sip faster.

mutation {
  updateNote(input: { id: "gid://gitlab/Note/<note ID>",
      body: "*SIPS TEA*"
    }) {
    note {
      id
      body
    }
    errors
  }
}

Deletion mutations

Let’s delete the comment, because our tea is all gone.

mutation {
  destroyNote(input: { id: "gid://gitlab/Note/<note ID>" }) {
    note {
      id
      body
    }
    errors
  }
}

You should get something like the following output:

{
  "data": {
    "destroyNote": {
      "errors": [],
      "note": null
    }
  }
}

We’ve asked for the note details, but it doesn’t exist anymore, so we get null.

More about mutations: .

Introspective queries

Clients can query the GraphQL endpoint for information about its own schema. by making an . The

{
  __schema {
    types {
      name
    }
  }
}

query IssueTypes {
  __type(name: "Issue") {
    kind
    name
    fields {
      name
      description
      type {
        name
      }
    }
  }
}

query {
  queryComplexity {
    score
    limit
  }

  project(fullPath: "gitlab-org/graphql-sandbox") {
    name
  }
}

query {
  project(fullPath: "gitlab-org/graphql-sandbox") {
   name
    issues(sort: created_asc) {
      nodes {
        title
        createdAt
      }
    }
  }
}

query {
  project(fullPath: "gitlab-org/graphql-sandbox") {
    name
    issues(first: 2) {
      edges {
        node {
          title
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

query {
  project(fullPath: "gitlab-org/graphql-sandbox") {
    name
    issues(first: 3, after: "eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0") {
      edges {
        node {
          title
        }
        cursor
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}