.nh
.TH "glab" "1" "Jul 2026" "Auto generated by spf13/cobra" ""

.SH NAME
glab-api - Make an authenticated request to the GitLab API.


.SH SYNOPSIS
\fBglab api  [flags]\fP


.SH DESCRIPTION
Makes an authenticated HTTP request to the GitLab API, and prints the response.
Specify either a path to a GitLab API v4 endpoint, or \fBgraphql\fR to access the
GitLab GraphQL API.

.PP
For more information, see:
.IP \(bu 2
GitLab REST API documentation
\[la]https://docs.gitlab.com/api/\[ra]
.IP \(bu 2
GitLab GraphQL documentation
\[la]https://docs.gitlab.com/api/graphql/\[ra]

.PP
If the current directory is a Git directory, this command uses the GitLab
authenticated host in the current directory. Otherwise, \fBgitlab.com\fR is used.
To override the GitLab hostname, use \fB--hostname\fR\&.

.PP
When used in the endpoint argument, these placeholder values are replaced
with values from the repository of the current directory:
.IP \(bu 2
\fB:branch\fR
.IP \(bu 2
\fB:fullpath\fR
.IP \(bu 2
\fB:group\fR
.IP \(bu 2
\fB:id\fR
.IP \(bu 2
\fB:namespace\fR
.IP \(bu 2
\fB:repo\fR
.IP \(bu 2
\fB:user\fR
.IP \(bu 2
\fB:username\fR

.PP
The default HTTP request method is \fBGET\fR when no parameters are added,
and \fBPOST\fR otherwise. To override the method, use \fB--method\fR\&.

.PP
Pass one or more \fB--raw-field\fR values in \fBkey=value\fR format to add
JSON-encoded string parameters to the \fBPOST\fR body.

.PP
The \fB--field\fR flag behaves like \fB--raw-field\fR but converts values
based on their format:
.IP \(bu 2
Literal values \fBtrue\fR, \fBfalse\fR, \fBnull\fR, and integer numbers are converted to
the matching JSON types.
.IP \(bu 2
Placeholder values \fB:namespace\fR, \fB:repo\fR, and \fB:branch\fR are populated with values
from the repository of the current directory.
.IP \(bu 2
If the value starts with \fB@\fR, the rest of the value is interpreted as a
filename to read the value from. Pass \fB-\fR to read from standard input.

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

.PP
For GraphQL requests, all fields other than \fBquery\fR and \fBoperationName\fR are
interpreted as GraphQL variables.

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

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

.PP
In \fB--paginate\fR mode, all pages of results are requested sequentially until
no more pages of results remain. For GraphQL requests:
.IP \(bu 2
The original query must accept an \fB$endCursor: String\fR variable.
.IP \(bu 2
The query must fetch the \fBpageInfo{ hasNextPage, endCursor }\fR set of fields from a collection.

.PP
The \fB--output\fR flag controls the output format:
.IP \(bu 2
\fBjson\fR (default): Pretty-printed JSON. Arrays are output as a single JSON array.
.IP \(bu 2
\fBndjson\fR: 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 \fBjq\fR\&.

.PP
For ndjson format specifications, see the
ndjson spec
\[la]https://github.com/ndjson/ndjson\-spec\[ra] and JSON Lines
\[la]https://jsonlines.org/\[ra]\&.


.SH OPTIONS
\fB-F\fP, \fB--field\fP=[]
	Add a parameter of inferred type. Using this flag changes the default HTTP method to POST.

.PP
\fB--form\fP=[]
	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.

.PP
\fB-H\fP, \fB--header\fP=[]
	Add an additional HTTP request header.

.PP
\fB--hostname\fP=""
	The GitLab hostname for the request. Defaults to gitlab.com, or the authenticated host in the current Git directory.

.PP
\fB-i\fP, \fB--include\fP[=false]
	Include HTTP response headers in the output.

.PP
\fB--input\fP=""
	The file to use as the body for the HTTP request.

.PP
\fB-X\fP, \fB--method\fP="GET"
	The HTTP method for the request.

.PP
\fB--output\fP="json"
	Format output as: json, ndjson.

.PP
\fB--paginate\fP[=false]
	Make additional HTTP requests to fetch all pages of results.

.PP
\fB-f\fP, \fB--raw-field\fP=[]
	Add a string parameter.

.PP
\fB--silent\fP[=false]
	Do not print the response body.


.SH OPTIONS INHERITED FROM PARENT COMMANDS
\fB-h\fP, \fB--help\fP[=false]
	Show help for this command.


.SH EXAMPLE
.EX
# 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
        }
      }
    }
  }'

.EE


.SH SEE ALSO
\fBglab(1)\fP