> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/go-gitea/gitea/llms.txt
> Use this file to discover all available pages before exploring further.

# Users API

> Manage and interact with users through the Gitea API

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.

<ResponseField name="id" type="integer" required>
  The unique identifier of the user
</ResponseField>

<ResponseField name="login" type="string" required>
  The username of the user (also available as `username`)
</ResponseField>

<ResponseField name="login_name" type="string">
  Identifier provided by external authenticator (if configured)
</ResponseField>

<ResponseField name="source_id" type="integer">
  The ID of the user's authentication source
</ResponseField>

<ResponseField name="full_name" type="string">
  The user's full name
</ResponseField>

<ResponseField name="email" type="string">
  The user's email address
</ResponseField>

<ResponseField name="avatar_url" type="string">
  URL to the user's avatar
</ResponseField>

<ResponseField name="html_url" type="string">
  URL to the user's Gitea profile page
</ResponseField>

<ResponseField name="language" type="string">
  User's preferred language
</ResponseField>

<ResponseField name="is_admin" type="boolean">
  Whether the user is an administrator
</ResponseField>

<ResponseField name="last_login" type="string">
  Timestamp of the user's last login
</ResponseField>

<ResponseField name="created" type="string">
  Timestamp when the user account was created
</ResponseField>

<ResponseField name="restricted" type="boolean">
  Whether the user is restricted
</ResponseField>

<ResponseField name="active" type="boolean">
  Whether the user account is active
</ResponseField>

<ResponseField name="prohibit_login" type="boolean">
  Whether the user is prohibited from logging in
</ResponseField>

<ResponseField name="location" type="string">
  The user's location
</ResponseField>

<ResponseField name="website" type="string">
  The user's website URL
</ResponseField>

<ResponseField name="description" type="string">
  The user's description/bio
</ResponseField>

<ResponseField name="visibility" type="string">
  User visibility level: `public`, `limited`, or `private`
</ResponseField>

<ResponseField name="followers_count" type="integer">
  Number of users following this user
</ResponseField>

<ResponseField name="following_count" type="integer">
  Number of users this user is following
</ResponseField>

<ResponseField name="starred_repos_count" type="integer">
  Number of repositories starred by this user
</ResponseField>

## Search Users

<Card title="GET /users/search" icon="magnifying-glass">
  Search for users by keyword
</Card>

### Query Parameters

<ParamField query="q" type="string">
  Search keyword
</ParamField>

<ParamField query="uid" type="integer">
  ID of the user to search for
</ParamField>

<ParamField query="page" type="integer">
  Page number of results to return (1-based)
</ParamField>

<ParamField query="limit" type="integer">
  Page size of results
</ParamField>

### Example Request

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

### Response

```json theme={null}
{
  "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

<Card title="GET /users/{username}" icon="user">
  Get information about a specific user
</Card>

### Path Parameters

<ParamField path="username" type="string" required>
  The username of the user to retrieve
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/users/john" \
  -H "accept: application/json"
```

### Response

```json theme={null}
{
  "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

<Card title="GET /user" icon="user-check">
  Get information about the currently authenticated user
</Card>

### Example Request

```bash theme={null}
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

<Card title="GET /users/{username}/heatmap" icon="chart-simple">
  Get a user's contribution heatmap data
</Card>

### Path Parameters

<ParamField path="username" type="string" required>
  The username of the user
</ParamField>

### Example Request

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="List Followers" icon="users" href="#list-followers">
    Get a user's followers
  </Card>

  <Card title="List Following" icon="user-group" href="#list-following">
    Get users a user is following
  </Card>

  <Card title="Follow User" icon="user-plus" href="#follow-user">
    Follow a user
  </Card>

  <Card title="Unfollow User" icon="user-minus" href="#unfollow-user">
    Unfollow a user
  </Card>
</CardGroup>

### List Followers

<Card title="GET /users/{username}/followers" icon="users">
  List all users following the specified user
</Card>

#### Path Parameters

<ParamField path="username" type="string" required>
  The username of the user
</ParamField>

#### Query Parameters

<ParamField query="page" type="integer">
  Page number of results to return (1-based)
</ParamField>

<ParamField query="limit" type="integer">
  Page size of results
</ParamField>

#### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/users/john/followers" \
  -H "accept: application/json"
```

### List Following

<Card title="GET /users/{username}/following" icon="user-group">
  List all users that the specified user is following
</Card>

#### Path Parameters

<ParamField path="username" type="string" required>
  The username of the user
</ParamField>

#### Query Parameters

<ParamField query="page" type="integer">
  Page number of results to return (1-based)
</ParamField>

<ParamField query="limit" type="integer">
  Page size of results
</ParamField>

#### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/users/john/following" \
  -H "accept: application/json"
```

### Check Following Status

<Card title="GET /users/{username}/following/{target}" icon="user-check">
  Check if one user is following another
</Card>

#### Path Parameters

<ParamField path="username" type="string" required>
  The username of the following user
</ParamField>

<ParamField path="target" type="string" required>
  The username of the followed user
</ParamField>

#### Example Request

```bash theme={null}
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

<Card title="PUT /user/following/{username}" icon="user-plus">
  Follow a user (requires authentication)
</Card>

#### Path Parameters

<ParamField path="username" type="string" required>
  The username of the user to follow
</ParamField>

#### Example Request

```bash theme={null}
curl -X PUT "https://gitea.example.com/api/v1/user/following/jane" \
  -H "Authorization: token YOUR_TOKEN"
```

### Unfollow User

<Card title="DELETE /user/following/{username}" icon="user-minus">
  Unfollow a user (requires authentication)
</Card>

#### Path Parameters

<ParamField path="username" type="string" required>
  The username of the user to unfollow
</ParamField>

#### Example Request

```bash theme={null}
curl -X DELETE "https://gitea.example.com/api/v1/user/following/jane" \
  -H "Authorization: token YOUR_TOKEN"
```

## Authenticated User Endpoints

### List My Followers

<Card title="GET /user/followers" icon="users">
  List all users following the authenticated user
</Card>

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/user/followers" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"
```

### List My Following

<Card title="GET /user/following" icon="user-group">
  List all users that the authenticated user is following
</Card>

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/user/following" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"
```

### Check My Following

<Card title="GET /user/following/{username}" icon="user-check">
  Check if the authenticated user is following a specific user
</Card>

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/user/following/jane" \
  -H "Authorization: token YOUR_TOKEN"
```

## SSH Keys

<CardGroup cols={2}>
  <Card title="List Keys" icon="key" href="#list-ssh-keys">
    Get a user's SSH keys
  </Card>

  <Card title="Get Key" icon="key" href="#get-ssh-key">
    Get a specific SSH key
  </Card>

  <Card title="Add Key" icon="plus" href="#add-ssh-key">
    Add a new SSH key
  </Card>

  <Card title="Delete Key" icon="trash" href="#delete-ssh-key">
    Remove an SSH key
  </Card>
</CardGroup>

### List SSH Keys

<Card title="GET /users/{username}/keys" icon="key">
  List all public SSH keys for a user
</Card>

#### Path Parameters

<ParamField path="username" type="string" required>
  The username of the user
</ParamField>

#### Query Parameters

<ParamField query="fingerprint" type="string">
  Filter by SSH key fingerprint
</ParamField>

<ParamField query="page" type="integer">
  Page number of results to return (1-based)
</ParamField>

<ParamField query="limit" type="integer">
  Page size of results
</ParamField>

#### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/users/john/keys" \
  -H "accept: application/json"
```

### List My SSH Keys

<Card title="GET /user/keys" icon="key">
  List all SSH keys for the authenticated user
</Card>

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/user/keys" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"
```

### Get SSH Key

<Card title="GET /user/keys/{id}" icon="key">
  Get details about a specific SSH key
</Card>

#### Path Parameters

<ParamField path="id" type="integer" required>
  The ID of the SSH key
</ParamField>

#### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/user/keys/1" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "accept: application/json"
```

### Add SSH Key

<Card title="POST /user/keys" icon="plus">
  Add a new SSH key for the authenticated user
</Card>

#### Request Body

<ParamField body="title" type="string" required>
  The title/name for this SSH key
</ParamField>

<ParamField body="key" type="string" required>
  The SSH public key content
</ParamField>

#### Example Request

```bash theme={null}
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

<Card title="DELETE /user/keys/{id}" icon="trash">
  Delete an SSH key
</Card>

#### Path Parameters

<ParamField path="id" type="integer" required>
  The ID of the SSH key to delete
</ParamField>

#### Example Request

```bash theme={null}
curl -X DELETE "https://gitea.example.com/api/v1/user/keys/1" \
  -H "Authorization: token YOUR_TOKEN"
```

## Activity Feeds

<Card title="GET /users/{username}/activities/feeds" icon="rss">
  List a user's activity feeds
</Card>

### Path Parameters

<ParamField path="username" type="string" required>
  The username of the user
</ParamField>

### Query Parameters

<ParamField query="only-performed-by" type="boolean" default="false">
  If true, only show actions performed by the user
</ParamField>

<ParamField query="date" type="string">
  The date of the activities to be found (format: YYYY-MM-DD)
</ParamField>

<ParamField query="page" type="integer">
  Page number of results to return (1-based)
</ParamField>

<ParamField query="limit" type="integer">
  Page size of results
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/users/john/activities/feeds?only-performed-by=true" \
  -H "accept: application/json"
```

## Related Endpoints

For more user-related endpoints, see:

* [Organizations API](/api/organizations) - List user's organizations
* [Teams API](/api/teams) - List user's teams
* [Repositories API](/api/repositories) - List user's repositories