Help us learn about your current experience with the documentation. Take the survey.

glab api

Make an authenticated request to the GitLab API.

Synopsis

Makes an authenticated HTTP request to the GitLab API, and prints the response. Specify either a path to a GitLab API v4 endpoint, or graphql to access the GitLab GraphQL API.

For more information, see:

If the current directory is a Git directory, this command uses the GitLab authenticated host in the current directory. Otherwise, gitlab.com is used. To override the GitLab hostname, use --hostname.

When used in the endpoint argument, these placeholder values are replaced with values from the repository of the current directory:

  • :branch
  • :fullpath
  • :group
  • :id
  • :namespace
  • :repo
  • :user
  • :username

The default HTTP request method is GET when no parameters are added, and POST otherwise. To override the method, use --method.

Pass one or more --raw-field values in key=value format to add JSON-encoded string parameters to the POST body.

The --field flag behaves like --raw-field but converts values based on their format:

  • Literal values true, false, null, and integer numbers are converted to the matching JSON types.
  • Placeholder values :namespace, :repo, and :branch are populated with values from the repository of the current directory.
  • If the value starts with @, the rest of the value is interpreted as a filename to read the value from. Pass - to read from standard input.

Neither --field nor --raw-field parses JSON arrays or objects; those values are sent as strings. To pass a JSON body literally, use --input.

For GraphQL requests, all fields other than query and operationName are interpreted as GraphQL variables.

To send data as multipart/form-data instead of JSON, use --form. This is required for API endpoints that accept file uploads, such as wiki attachments. Pass one or more --form values in key=value format. To upload a file, prefix the value with @ followed by the file path. Pass - to read from standard input. Do not combine --form with --field, --raw-field, or --input.

To pass a raw request body, use --input with a file path. Pass - to read from standard input. In this mode, parameters specified with --field flags are serialized into URL query parameters.

In --paginate mode, all pages of results are requested sequentially until no more pages of results remain. For GraphQL requests:

  • The original query must accept an $endCursor: String variable.
  • The query must fetch the pageInfo{ hasNextPage, endCursor } set of fields from a collection.

The --output flag controls the output format:

  • json (default): Pretty-printed JSON. Arrays are output as a single JSON array.
  • ndjson: Newline-delimited JSON, also known as JSON Lines. Each array element or object is output on a separate line. This format is more memory-efficient for large datasets and works well with tools like jq.

For ndjson format specifications, see the ndjson spec and JSON Lines.

glab api <endpoint> [flags]

Examples

# List releases for the current project, expanding the :fullpath placeholder
glab api projects/:fullpath/releases

# List issues for a project by URL-encoded path
glab api projects/gitlab-com%2Fwww-gitlab-com/issues

# Upload a file to a project wiki
glab api --method POST projects/:fullpath/wikis/attachments --form "file=@./image.png" --form "branch=main"

# Debug the HTTP request and response, including headers and body.
# Use --input (here, piped from stdin) for JSON arrays or objects;
# --field only converts scalars (bool, int, null, placeholders, @file).
echo '{"allowed_to_push":[{"user_id":1}]}' | GLAB_DEBUG_HTTP=1 glab api -X PATCH "projects/:fullpath/protected_branches/main" --input -

# Fetch all pages of issues
glab api issues --paginate

# Fetch all pages of issues as newline-delimited JSON
glab api issues --paginate --output ndjson

# Pipe paginated output to jq to filter open issues
glab api issues --paginate --output ndjson | jq 'select(.state == "opened")'

# Run a simple GraphQL query
glab api graphql -f query="query { currentUser { username } }"

# Run a multi-line GraphQL query for project metadata
glab api graphql -f query='
  query {
    project(fullPath: "gitlab-org/gitlab-docs") {
      name
      forksCount
      statistics {
        wikiSize
      }
      issuesEnabled
      boards {
        nodes {
          id
          name
        }
      }
    }
  }
'

# Run a paginated GraphQL query using an endCursor variable
glab api graphql --paginate -f query='
  query($endCursor: String) {
    project(fullPath: "gitlab-org/graphql-sandbox") {
      name
      issues(first: 2, after: $endCursor) {
        edges {
          node {
            title
          }
        }
        pageInfo {
          endCursor
          hasNextPage
        }
      }
    }
  }'

Options

  -F, --field stringArray       Add a parameter of inferred type. Using this flag changes the default HTTP method to POST.
      --form stringArray        Add a multipart form field. To upload a file, prefix the value with @ followed by the file path. To read from standard input, use @- (at most once). Using this flag changes the default HTTP method to POST.
  -H, --header stringArray      Add an additional HTTP request header.
      --hostname string         The GitLab hostname for the request. Defaults to gitlab.com, or the authenticated host in the current Git directory.
  -i, --include                 Include HTTP response headers in the output.
      --input string            The file to use as the body for the HTTP request.
  -X, --method string           The HTTP method for the request. (default "GET")
      --output string           Format output as: json, ndjson. (default "json")
      --paginate                Make additional HTTP requests to fetch all pages of results.
  -f, --raw-field stringArray   Add a string parameter.
      --silent                  Do not print the response body.

Options inherited from parent commands

  -h, --help   Show help for this command.