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:

• GitLab REST API documentation
• GitLab GraphQL documentation

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.

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"

# 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.