.nh
.TH "GT-API" "1" "Nov 2026" "gitea-cli" "gitea-cli Manual"

.SH NAME
gt-api - Make an authenticated Gitea API request


.SH SYNOPSIS
\fBgt api <endpoint> [flags]\fP


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

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

.PP
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:

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

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

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


.SH OPTIONS
\fB-F\fP, \fB--field\fP=[]
	Add a typed parameter in \fBkey=value\fR format; @FILE or @- reads a file or stdin

.PP
\fB-H\fP, \fB--header\fP=[]
	Add an HTTP request header in \fBname:value\fR format

.PP
\fB-h\fP, \fB--help\fP[=false]
	help for api

.PP
\fB-i\fP, \fB--include\fP[=false]
	Print the response status and headers to stderr

.PP
\fB--input\fP=""
	Read the request body from a \fBfile\fR, or stdin with -

.PP
\fB--max-pages\fP=1000
	Stop --paginate after this many pages; reaching the default fails

.PP
\fB-X\fP, \fB--method\fP="GET"
	HTTP \fBmethod\fR

.PP
\fB--output-file\fP=""
	Write the complete response to a new \fBfile\fR

.PP
\fB--paginate\fP[=false]
	Follow next-page links and print every page

.PP
\fB-f\fP, \fB--raw-field\fP=[]
	Add a string parameter in \fBkey=value\fR format

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

.PP
\fB--verbose\fP[=false]
	Print the request and the response status and headers to stderr


.SH OPTIONS INHERITED FROM PARENT COMMANDS
\fB--cwd\fP=""
	Working \fBdirectory\fR for repository discovery

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

.PP
\fB--host\fP=""
	Gitea instance \fBURL\fR, including any base path

.PP
\fB--interactive\fP[=false]
	Allow prompts with machine output

.PP
\fB-q\fP, \fB--jq\fP=""
	Filter JSON output using a jq \fBexpression\fR; implies --json

.PP
\fB--no-input\fP[=false]
	Disable prompts and implicit editor/browser interactions

.PP
\fB--remote\fP=""
	Git \fBremote\fR used for repository discovery

.PP
\fB-R\fP, \fB--repo\fP=""
	Select a repository as \fBOWNER/REPO\fR or URL

.PP
\fB--sudo\fP=""
	Perform API requests as this \fBuser\fR (requires an administrator account)

.PP
\fB--user\fP=""
	Account \fBname\fR on the selected instance


.SH EXAMPLE
.EX
$ 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'
.EE


.SH SEE ALSO
\fBgt(1)\fP