Admin-API.md 3.05 KB
Newer Older
Haelwenn's avatar
Haelwenn committed
1
# Admin API
Maxim Filippov's avatar
Maxim Filippov committed
2

Haelwenn's avatar
Haelwenn committed
3
4
Authentication is required and the user must be an admin.

Maxim Filippov's avatar
Maxim Filippov committed
5
## `/api/pleroma/admin/users`
Maxim Filippov's avatar
Maxim Filippov committed
6
7
8
9

### List users

- Method `GET`
Maxim Filippov's avatar
Maxim Filippov committed
10
- Query Params:
Maxim Filippov's avatar
Maxim Filippov committed
11
  - `query`: **string** *optional* search term
Maxim Filippov's avatar
Typo    
Maxim Filippov committed
12
  - `local_only`: **bool** *optional* whether to return only local users
Maxim Filippov's avatar
Maxim Filippov committed
13
14
  - `page`: **integer** *optional* page number
  - `page_size`: **integer** *optional* number of users per page (default is `50`)
Maxim Filippov's avatar
Maxim Filippov committed
15
16
17
- Response:

```JSON
Maxim Filippov's avatar
Maxim Filippov committed
18
19
20
21
{
  "page_size": integer,
  "count": integer,
  "users": [
Maxim Filippov's avatar
Maxim Filippov committed
22
    {
Maxim Filippov's avatar
Maxim Filippov committed
23
24
25
      "deactivated": bool,
      "id": integer,
      "nickname": string
Maxim Filippov's avatar
Maxim Filippov committed
26
27
    },
    ...
Maxim Filippov's avatar
Maxim Filippov committed
28
29
  ]
}
Maxim Filippov's avatar
Maxim Filippov committed
30
31
```

Haelwenn's avatar
Haelwenn committed
32
## `/api/pleroma/admin/user`
Maxim Filippov's avatar
Maxim Filippov committed
33

Haelwenn's avatar
Haelwenn committed
34
### Remove a user
Maxim Filippov's avatar
Maxim Filippov committed
35
36
37
38
39
40

- Method `DELETE`
- Params:
  - `nickname`
- Response: User’s nickname

Haelwenn's avatar
Haelwenn committed
41
### Create a user
Maxim Filippov's avatar
Maxim Filippov committed
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

- Method: `POST`
- Params:
  - `nickname`
  - `email`
  - `password`
- Response: User’s nickname

## `/api/pleroma/admin/users/:nickname/toggle_activation`

### Toggle user activation

- Method: `PATCH`
- Params:
  - `nickname`
- Response: User’s object

```JSON
{
Maxim Filippov's avatar
Maxim Filippov committed
61
62
63
  "deactivated": bool,
  "id": integer,
  "nickname": string
Maxim Filippov's avatar
Maxim Filippov committed
64
65
}
```
Haelwenn's avatar
Haelwenn committed
66
67

## `/api/pleroma/admin/users/tag`
Maxim Filippov's avatar
Maxim Filippov committed
68

Haelwenn's avatar
Haelwenn committed
69
### Tag a list of users
Maxim Filippov's avatar
Maxim Filippov committed
70
71
72
73
74
75

- Method: `PUT`
- Params:
  - `nickname`
  - `tags`

Haelwenn's avatar
Haelwenn committed
76
### Untag a list of users
Maxim Filippov's avatar
Maxim Filippov committed
77
78
79
80
81

- Method: `DELETE`
- Params:
  - `nickname`
  - `tags`
Haelwenn's avatar
Haelwenn committed
82
83

## `/api/pleroma/admin/permission_group/:nickname`
Maxim Filippov's avatar
Maxim Filippov committed
84

Haelwenn's avatar
Haelwenn committed
85
### Get user user permission groups membership
Maxim Filippov's avatar
Maxim Filippov committed
86
87
88
89
90

- Method: `GET`
- Params: none
- Response:

Haelwenn's avatar
Haelwenn committed
91
92
```JSON
{
Maxim Filippov's avatar
Maxim Filippov committed
93
94
  "is_moderator": bool,
  "is_admin": bool
Haelwenn's avatar
Haelwenn committed
95
96
97
98
}
```

## `/api/pleroma/admin/permission_group/:nickname/:permission_group`
Maxim Filippov's avatar
Maxim Filippov committed
99

Haelwenn's avatar
Haelwenn committed
100
101
102
Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist.

### Get user user permission groups membership
Maxim Filippov's avatar
Maxim Filippov committed
103
104
105
106
107

- Method: `GET`
- Params: none
- Response:

Haelwenn's avatar
Haelwenn committed
108
109
```JSON
{
Maxim Filippov's avatar
Maxim Filippov committed
110
111
  "is_moderator": bool,
  "is_admin": bool
Haelwenn's avatar
Haelwenn committed
112
113
}
```
Maxim Filippov's avatar
Maxim Filippov committed
114

Haelwenn's avatar
Haelwenn committed
115
### Add user in permission group
Maxim Filippov's avatar
Maxim Filippov committed
116
117
118
119
120
121
122

- Method: `POST`
- Params: none
- Response:
  - On failure: `{"error": "…"}`
  - On success: JSON of the `user.info`

Haelwenn's avatar
Haelwenn committed
123
### Remove user from permission group
Maxim Filippov's avatar
Maxim Filippov committed
124
125
126
127
128
129
130

- Method: `DELETE`
- Params: none
- Response:
  - On failure: `{"error": "…"}`
  - On success: JSON of the `user.info`
- Note: An admin cannot revoke their own admin status.
Haelwenn's avatar
Haelwenn committed
131

132
133
134
## `/api/pleroma/admin/activation_status/:nickname`

### Active or deactivate a user
Maxim Filippov's avatar
Maxim Filippov committed
135
136
137
138
139

- Method: `PUT`
- Params:
  - `nickname`
  - `status` BOOLEAN field, false value means deactivation.
140

Haelwenn's avatar
Haelwenn committed
141
## `/api/pleroma/admin/relay`
Maxim Filippov's avatar
Maxim Filippov committed
142

Haelwenn's avatar
Haelwenn committed
143
### Follow a Relay
Maxim Filippov's avatar
Maxim Filippov committed
144
145
146
147
148
149
150

- Methods: `POST`
- Params:
  - `relay_url`
- Response:
  - On success: URL of the followed relay

Haelwenn's avatar
Haelwenn committed
151
### Unfollow a Relay
Maxim Filippov's avatar
Maxim Filippov committed
152
153
154
155
156
157

- Methods: `DELETE`
- Params:
  - `relay_url`
- Response:
  - On success: URL of the unfollowed relay
Haelwenn's avatar
Haelwenn committed
158
159

## `/api/pleroma/admin/invite_token`
Maxim Filippov's avatar
Maxim Filippov committed
160

Haelwenn's avatar
Haelwenn committed
161
### Get a account registeration invite token
Maxim Filippov's avatar
Maxim Filippov committed
162
163
164
165

- Methods: `GET`
- Params: none
- Response: invite token (base64 string)
Haelwenn's avatar
Haelwenn committed
166
167

## `/api/pleroma/admin/email_invite`
Maxim Filippov's avatar
Maxim Filippov committed
168

Haelwenn's avatar
Haelwenn committed
169
### Sends registration invite via email
Maxim Filippov's avatar
Maxim Filippov committed
170
171
172
173
174

- Methods: `POST`
- Params:
  - `email`
  - `name`, optionnal
Haelwenn's avatar
Haelwenn committed
175
176

## `/api/pleroma/admin/password_reset`
Maxim Filippov's avatar
Maxim Filippov committed
177

Haelwenn's avatar
Haelwenn committed
178
### Get a password reset token for a given nickname
Maxim Filippov's avatar
Maxim Filippov committed
179
180
181
182

- Methods: `GET`
- Params: none
- Response: password reset token (base64 string)