---
name: "gt-api"
section: "1"
platform: "linux"
package: "gitea-cli"
version: "1.0.0-1"
release: "Arch Linux 2026-11-07"
platforms: ["linux"]
url: "https://carta.tech/man/gt-api"
---

# gt-api(1)

Make an authenticated Gitea API request

## NAME

gt-api - Make an authenticated Gitea API request

## SYNOPSIS

**gt api \<endpoint\> \[flags\]**

## DESCRIPTION

Make an authenticated request to the Gitea API of the selected instance and print the response.

The endpoint is a path under /api/v1, such as repos/{owner}/{repo}/issues, or a URL of the instance's API. The placeholders {owner} and {repo} take the repository of the current directory or --repo, and {branch} the checked-out Git branch.

The method is GET, or POST when fields or --input supply a request body; -X selects another. Fields become query parameters of GET and HEAD requests and a JSON body otherwise:

\-f, --raw-field name=value   a string value\
   \-F, --field name=value       a typed value: true, false, null, numbers, arrays and\
                                objects are JSON, @FILE reads a file and @- stdin

\--paginate follows the next-page links of a GET request, or asks for the next page of a list that Gitea counts in X-Total-Count without links, and prints every page on its own line. --jq filters each JSON response with a jq expression and prints strings without quotes; jq does not need to be installed.

On a terminal, JSON responses are indented and colored. A response outside 2xx prints its body, then fails with the HTTP status.

## OPTIONS

**-F**, **--field**=\[\]\
 	Add a typed parameter in **key=value** format; @FILE or @- reads a file or stdin

**-H**, **--header**=\[\]\
 	Add an HTTP request header in **name:value** format

**-h**, **--help**\[=false\]\
 	help for api

**-i**, **--include**\[=false\]\
 	Print the response status and headers to stderr

**--input**=""\
 	Read the request body from a **file**, or stdin with -

**--max-pages**=1000\
 	Stop --paginate after this many pages; reaching the default fails

**-X**, **--method**="GET"\
 	HTTP **method**

**--output-file**=""\
 	Write the complete response to a new **file**

**--paginate**\[=false\]\
 	Follow next-page links and print every page

**-f**, **--raw-field**=\[\]\
 	Add a string parameter in **key=value** format

**--silent**\[=false\]\
 	Do not print the response body

**--verbose**\[=false\]\
 	Print the request and the response status and headers to stderr

## OPTIONS INHERITED FROM PARENT COMMANDS

**--cwd**=""\
 	Working **directory** for repository discovery

**--debug**\[=false\]\
 	Log the method, URL, status, and duration of each HTTP request to stderr

**--host**=""\
 	Gitea instance **URL**, including any base path

**--interactive**\[=false\]\
 	Allow prompts with machine output

**-q**, **--jq**=""\
 	Filter JSON output using a jq **expression**; implies --json

**--no-input**\[=false\]\
 	Disable prompts and implicit editor/browser interactions

**--remote**=""\
 	Git **remote** used for repository discovery

**-R**, **--repo**=""\
 	Select a repository as **OWNER/REPO** or URL

**--sudo**=""\
 	Perform API requests as this **user** (requires an administrator account)

**--user**=""\
 	Account **name** on the selected instance

## EXAMPLE

```
$ gt api user --jq .login
# Create an issue: -f sends strings, -F typed values
$ gt api repos/{owner}/{repo}/issues -f title="Crash on start" -F labels='[3]'
$ gt api user/repos --paginate --jq '.[].full_name'
```

## SEE ALSO

**[gt(1)](/man/gt/1.md)**