Skip to main content
The Users API provides endpoints to retrieve user information, manage user relationships, and handle user authentication data.

​
User Object

The User object represents a user account in Gitea.
​
id
integer
required
The unique identifier of the user
​
login
string
required
The username of the user (also available as username)
​
login_name
string
Identifier provided by external authenticator (if configured)
​
source_id
integer
The ID of the user’s authentication source
​
full_name
string
The user’s full name
​
email
string
The user’s email address
​
avatar_url
string
URL to the user’s avatar
​
html_url
string
URL to the user’s Gitea profile page
​
language
string
User’s preferred language
​
is_admin
boolean
Whether the user is an administrator
​
last_login
string
Timestamp of the user’s last login
​
created
string
Timestamp when the user account was created
​
restricted
boolean
Whether the user is restricted
​
active
boolean
Whether the user account is active
​
prohibit_login
boolean
Whether the user is prohibited from logging in
​
location
string
The user’s location
​
website
string
The user’s website URL
​
description
string
The user’s description/bio
​
visibility
string
User visibility level: public, limited, or private
​
followers_count
integer
Number of users following this user
​
following_count
integer
Number of users this user is following
​
starred_repos_count
integer
Number of repositories starred by this user

​
Search Users

GET /users/search

Search for users by keyword

​
Query Parameters

​
q
string
Search keyword
​
uid
integer
ID of the user to search for
​
page
integer
Page number of results to return (1-based)
​
limit
integer
Page size of results

​
Example Request

curl -X GET "https://gitea.example.com/api/v1/users/search?q=john" \
  -H "accept: application/json"

​
Response

{
  "ok": true,
  "data": [
    {
      "id": 1,
      "login": "john",
      "full_name": "John Doe",
      "email": "[email protected]",
      "avatar_url": "https://gitea.example.com/avatars/1",
      "language": "en-US",
      "is_admin": false,
      "location": "New York",
      "website": "https://johndoe.com",
      "description": "Software developer",
      "visibility": "public",
      "followers_count": 10,
      "following_count": 5,
      "starred_repos_count": 20
    }
  ]
}

​
Get a User

GET /users/{username}

Get information about a specific user

​
Path Parameters

​
username
string
required
The username of the user to retrieve

​
Example Request

curl -X GET "https://gitea.example.com/api/v1/users/john" \
  -H "accept: application/json"

​
Response

{
  "id": 1,
  "login": "john",
  "full_name": "John Doe",
  "email": "[email protected]",
  "avatar_url": "https://gitea.example.com/avatars/1",
  "html_url": "https://gitea.example.com/john",
  "language": "en-US",
  "is_admin": false,
  "last_login": "2026-03-10T12:00:00Z",
  "created": "2025-01-01T00:00:00Z",
  "restricted": false,
  "active": true,
  "prohibit_login": false,
  "location": "New York",
  "website": "https://johndoe.com",
  "description": "Software developer",
  "visibility": "public",
  "followers_count": 10,
  "following_count": 5,
  "starred_repos_count": 20
}

​
Get Authenticated User

GET /user

Get information about the currently authenticated user

​
Example Request

curl -X GET "https://gitea.example.com/api/v1/user" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"

​
Response

Returns a User object for the authenticated user.

​
User Heatmap

GET /users/{username}/heatmap

Get a user’s contribution heatmap data

​
Path Parameters

​
username
string
required
The username of the user

​
Example Request

curl -X GET "https://gitea.example.com/api/v1/users/john/heatmap" \
  -H "accept: application/json"

​
Response

Returns an array of contribution data points with timestamps and contribution counts.

​
Followers & Following

List Followers

Get a user’s followers

List Following

Get users a user is following

Follow User

Follow a user

Unfollow User

Unfollow a user

​
List Followers

GET /users/{username}/followers

List all users following the specified user

​
Path Parameters

​
username
string
required
The username of the user

​
Query Parameters

​
page
integer
Page number of results to return (1-based)
​
limit
integer
Page size of results

​
Example Request

curl -X GET "https://gitea.example.com/api/v1/users/john/followers" \
  -H "accept: application/json"

​
List Following

GET /users/{username}/following

List all users that the specified user is following

​
Path Parameters

​
username
string
required
The username of the user

​
Query Parameters

​
page
integer
Page number of results to return (1-based)
​
limit
integer
Page size of results

​
Example Request

curl -X GET "https://gitea.example.com/api/v1/users/john/following" \
  -H "accept: application/json"

​
Check Following Status

GET /users/{username}/following/{target}

Check if one user is following another

​
Path Parameters

​
username
string
required
The username of the following user
​
target
string
required
The username of the followed user

​
Example Request

curl -X GET "https://gitea.example.com/api/v1/users/john/following/jane" \
  -H "accept: application/json"
Returns 204 No Content if following, 404 Not Found otherwise.

​
Follow User

PUT /user/following/{username}

Follow a user (requires authentication)

​
Path Parameters

​
username
string
required
The username of the user to follow

​
Example Request

curl -X PUT "https://gitea.example.com/api/v1/user/following/jane" \
  -H "Authorization: token YOUR_TOKEN"

​
Unfollow User

DELETE /user/following/{username}

Unfollow a user (requires authentication)

​
Path Parameters

​
username
string
required
The username of the user to unfollow

​
Example Request

curl -X DELETE "https://gitea.example.com/api/v1/user/following/jane" \
  -H "Authorization: token YOUR_TOKEN"

​
Authenticated User Endpoints

​
List My Followers

GET /user/followers

List all users following the authenticated user
curl -X GET "https://gitea.example.com/api/v1/user/followers" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"

​
List My Following

GET /user/following

List all users that the authenticated user is following
curl -X GET "https://gitea.example.com/api/v1/user/following" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"

​
Check My Following

GET /user/following/{username}

Check if the authenticated user is following a specific user
curl -X GET "https://gitea.example.com/api/v1/user/following/jane" \
  -H "Authorization: token YOUR_TOKEN"

​
SSH Keys

List Keys

Get a user’s SSH keys

Get Key

Get a specific SSH key

Add Key

Add a new SSH key

Delete Key

Remove an SSH key

​
List SSH Keys

GET /users/{username}/keys

List all public SSH keys for a user

​
Path Parameters

​
username
string
required
The username of the user

​
Query Parameters

​
fingerprint
string
Filter by SSH key fingerprint
​
page
integer
Page number of results to return (1-based)
​
limit
integer
Page size of results

​
Example Request

curl -X GET "https://gitea.example.com/api/v1/users/john/keys" \
  -H "accept: application/json"

​
List My SSH Keys

GET /user/keys

List all SSH keys for the authenticated user
curl -X GET "https://gitea.example.com/api/v1/user/keys" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"

​
Get SSH Key

GET /user/keys/{id}

Get details about a specific SSH key

​
Path Parameters

​
id
integer
required
The ID of the SSH key

​
Example Request

curl -X GET "https://gitea.example.com/api/v1/user/keys/1" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"

​
Add SSH Key

POST /user/keys

Add a new SSH key for the authenticated user

​
Request Body

​
title
string
required
The title/name for this SSH key
​
key
string
required
The SSH public key content

​
Example Request

curl -X POST "https://gitea.example.com/api/v1/user/keys" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Laptop Key",
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC..."
  }'

​
Delete SSH Key

DELETE /user/keys/{id}

Delete an SSH key

​
Path Parameters

​
id
integer
required
The ID of the SSH key to delete

​
Example Request

curl -X DELETE "https://gitea.example.com/api/v1/user/keys/1" \
  -H "Authorization: token YOUR_TOKEN"

​
Activity Feeds

GET /users/{username}/activities/feeds

List a user’s activity feeds

​
Path Parameters

​
username
string
required
The username of the user

​
Query Parameters

​
only-performed-by
boolean
default:"false"
If true, only show actions performed by the user
​
date
string
The date of the activities to be found (format: YYYY-MM-DD)
​
page
integer
Page number of results to return (1-based)
​
limit
integer
Page size of results

​
Example Request

curl -X GET "https://gitea.example.com/api/v1/users/john/activities/feeds?only-performed-by=true" \
  -H "accept: application/json"
For more user-related endpoints, see:

Build docs developers (and LLMs) love

Get started for freeTalk to us