---
title: '`glab api`'
stage: AI Coding
group: Code Review
info: To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments>
---

<!--
This documentation is auto generated by a script.
Please do not edit this file directly. Run `make gen-docs` instead.
-->

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](https://docs.gitlab.com/api/)
- [GitLab GraphQL documentation](https://docs.gitlab.com/api/graphql/)

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.
- Values starting with `[` or `{` are parsed as JSON arrays or objects
  (e.g. `-F 'topics=["my-topic","GitLab"]'`). Invalid JSON returns an error.
  The value must start with the bracket or brace: a leading space, as in
  `-F 'topics= ["a"]'`, is part of the value, so it is sent as a string.
- Placeholder values `:namespace`, `:repo`, and `:branch` are populated with values
  from the repository of the current directory, including inside JSON
  arrays and objects (e.g. `-F 'input={"projectPath":":fullpath"}'`).
- 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.

`--raw-field` does not parse JSON arrays or objects; those values are
sent as strings. To pass a JSON body literally, use `--input`.

A bracketed `--raw-field` value such as `-f 'scopes=[api,read_api]'` is sent as
the literal string `"[api,read_api]"`. Earlier versions converted that shape
into an array on request bodies, which `--raw-field` never documented. Use
`-F 'scopes=["api","read_api"]'` for an array.

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](https://github.com/ndjson/ndjson-spec) and [JSON Lines](https://jsonlines.org/).

```plaintext
glab api <endpoint> [flags]
```

## Examples

```console
# 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 to send a complete JSON request body from stdin.
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

```plaintext
  -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

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