Users API - Gitea

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.

integer

required

The unique identifier of the user

The username of the user (also available as username)

Identifier provided by external authenticator (if configured)

integer

The ID of the user’s authentication source

string

The user’s full name

string

The user’s email address

string

URL to the user’s avatar

string

URL to the user’s Gitea profile page

string

User’s preferred language

boolean

Whether the user is an administrator

Timestamp of the user’s last login

string

Timestamp when the user account was created

boolean

Whether the user is restricted

boolean

Whether the user account is active

Whether the user is prohibited from logging in

string

The user’s location

string

The user’s website URL

string

The user’s description/bio

string

User visibility level: public, limited, or private

integer

Number of users following this user

integer

Number of users this user is following

integer

Number of repositories starred by this user

Search Users

GET /users/search

Search for users by keyword

Query Parameters

string

Search keyword

integer

ID of the user to search for

integer

Page number of results to return (1-based)

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": "john@example.com",
      "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

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": "john@example.com",
  "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

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

string

required

The username of the user

Query Parameters

integer

Page number of results to return (1-based)

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

string

required

The username of the user

Query Parameters

integer

Page number of results to return (1-based)

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

string

required

The username of the following user

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

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

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

string

required

The username of the user

Query Parameters

string

Filter by SSH key fingerprint

integer

Page number of results to return (1-based)

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

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

string

required

The title/name for this SSH 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

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

string

required

The username of the user

Query Parameters

boolean

default:"false"

If true, only show actions performed by the user

string

The date of the activities to be found (format: YYYY-MM-DD)

integer

Page number of results to return (1-based)

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:

Organizations API - List user’s organizations
Teams API - List user’s teams
Repositories API - List user’s repositories

​User Object

​Search Users

GET /users/search

​Query Parameters

​Example Request

​Response

​Get a User

GET /users/{username}

​Path Parameters

​Example Request

​Response

​Get Authenticated User

GET /user

​Example Request

​Response

​User Heatmap

GET /users/{username}/heatmap

​Path Parameters

​Example Request

​Response

​Followers & Following

List Followers

List Following

Follow User

Unfollow User

​List Followers

GET /users/{username}/followers

​Path Parameters

​Query Parameters

​Example Request

​List Following

GET /users/{username}/following

​Path Parameters

​Query Parameters

​Example Request

​Check Following Status

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

​Path Parameters

​Example Request

​Follow User

PUT /user/following/{username}

​Path Parameters

​Example Request

​Unfollow User

DELETE /user/following/{username}

​Path Parameters

​Example Request

​Authenticated User Endpoints

​List My Followers

GET /user/followers

​List My Following

GET /user/following

​Check My Following

GET /user/following/{username}

​SSH Keys

List Keys

Get Key

Add Key

Delete Key

​List SSH Keys

GET /users/{username}/keys

​Path Parameters

​Query Parameters

​Example Request

​List My SSH Keys

GET /user/keys

​Get SSH Key

GET /user/keys/{id}

​Path Parameters

​Example Request

​Add SSH Key

POST /user/keys

​Request Body

​Example Request

​Delete SSH Key

DELETE /user/keys/{id}

​Path Parameters

​Example Request

​Activity Feeds

GET /users/{username}/activities/feeds

User Object

Search Users

Query Parameters

Example Request

Response

Get a User

Path Parameters

Example Request

Response

Get Authenticated User

Example Request

Response

User Heatmap

Path Parameters

Example Request

Response

Followers & Following

List Followers

Path Parameters

Query Parameters

Example Request

List Following

Path Parameters

Query Parameters

Example Request

Check Following Status

Path Parameters

Example Request

Follow User

Path Parameters

Example Request

Unfollow User

Path Parameters

Example Request

Authenticated User Endpoints

List My Followers

List My Following

Check My Following

SSH Keys

List SSH Keys

Path Parameters

Query Parameters

Example Request

List My SSH Keys

Get SSH Key

Path Parameters

Example Request

Add SSH Key

Request Body

Example Request

Delete SSH Key

Path Parameters

Example Request

Activity Feeds

Path Parameters

Query Parameters

Example Request

Related Endpoints