admin_api.md 3.45 KB
Newer Older
Haelwenn's avatar
Haelwenn committed
1
# Admin API
rinpatch's avatar
rinpatch committed
2
# Admin API
Maxim Filippov's avatar
Maxim Filippov committed
3

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

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

### List users

- Method `GET`
Maxim Filippov's avatar
Maxim Filippov committed
11
- Query Params:
12
13
14
15
16
17
18
19
20
  - *optional* `query`: **string** search term
  - *optional* `filters`: **string** comma-separated string of filters:
    - `local`: only local users
    - `external`: only external users
    - `active`: only active users
    - `deactivated`: only deactivated users
  - *optional* `page`: **integer** page number
  - *optional* `page_size`: **integer** number of users per page (default is `50`)
- Example: `https://mypleroma.org/api/pleroma/admin/users?query=john&filters=local,active&page=1&page_size=10`
Maxim Filippov's avatar
Maxim Filippov committed
21
22
23
- Response:

```JSON
Maxim Filippov's avatar
Maxim Filippov committed
24
25
26
27
{
  "page_size": integer,
  "count": integer,
  "users": [
Maxim Filippov's avatar
Maxim Filippov committed
28
    {
Maxim Filippov's avatar
Maxim Filippov committed
29
30
      "deactivated": bool,
      "id": integer,
31
32
33
34
35
36
37
      "nickname": string,
      "roles": {
        "admin": bool,
        "moderator": bool
      },
      "local": bool,
      "tags": array
Maxim Filippov's avatar
Maxim Filippov committed
38
39
    },
    ...
Maxim Filippov's avatar
Maxim Filippov committed
40
41
  ]
}
Maxim Filippov's avatar
Maxim Filippov committed
42
43
```

Haelwenn's avatar
Haelwenn committed
44
## `/api/pleroma/admin/user`
Maxim Filippov's avatar
Maxim Filippov committed
45

Haelwenn's avatar
Haelwenn committed
46
### Remove a user
Maxim Filippov's avatar
Maxim Filippov committed
47
48
49
50
51
52

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

Haelwenn's avatar
Haelwenn committed
53
### Create a user
Maxim Filippov's avatar
Maxim Filippov committed
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

- 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
73
74
75
  "deactivated": bool,
  "id": integer,
  "nickname": string
Maxim Filippov's avatar
Maxim Filippov committed
76
77
}
```
Haelwenn's avatar
Haelwenn committed
78
79

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

Haelwenn's avatar
Haelwenn committed
81
### Tag a list of users
Maxim Filippov's avatar
Maxim Filippov committed
82
83
84
85
86
87

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

Haelwenn's avatar
Haelwenn committed
88
### Untag a list of users
Maxim Filippov's avatar
Maxim Filippov committed
89
90
91
92
93

- Method: `DELETE`
- Params:
  - `nickname`
  - `tags`
Haelwenn's avatar
Haelwenn committed
94
95

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

Haelwenn's avatar
Haelwenn committed
97
### Get user user permission groups membership
Maxim Filippov's avatar
Maxim Filippov committed
98
99
100
101
102

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

Haelwenn's avatar
Haelwenn committed
103
104
```JSON
{
Maxim Filippov's avatar
Maxim Filippov committed
105
106
  "is_moderator": bool,
  "is_admin": bool
Haelwenn's avatar
Haelwenn committed
107
108
109
110
}
```

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

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

114
### Get user user permission groups membership per permission group
Maxim Filippov's avatar
Maxim Filippov committed
115
116
117
118
119

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

Haelwenn's avatar
Haelwenn committed
120
121
```JSON
{
Maxim Filippov's avatar
Maxim Filippov committed
122
123
  "is_moderator": bool,
  "is_admin": bool
Haelwenn's avatar
Haelwenn committed
124
125
}
```
Maxim Filippov's avatar
Maxim Filippov committed
126

Haelwenn's avatar
Haelwenn committed
127
### Add user in permission group
Maxim Filippov's avatar
Maxim Filippov committed
128
129
130
131
132
133
134

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

Haelwenn's avatar
Haelwenn committed
135
### Remove user from permission group
Maxim Filippov's avatar
Maxim Filippov committed
136
137
138
139
140
141
142

- 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
143

144
145
146
## `/api/pleroma/admin/activation_status/:nickname`

### Active or deactivate a user
Maxim Filippov's avatar
Maxim Filippov committed
147
148
149
150
151

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

Haelwenn's avatar
Haelwenn committed
153
## `/api/pleroma/admin/relay`
Maxim Filippov's avatar
Maxim Filippov committed
154

Haelwenn's avatar
Haelwenn committed
155
### Follow a Relay
Maxim Filippov's avatar
Maxim Filippov committed
156
157
158
159
160
161
162

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

Haelwenn's avatar
Haelwenn committed
163
### Unfollow a Relay
Maxim Filippov's avatar
Maxim Filippov committed
164
165
166
167
168
169

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

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

Haelwenn's avatar
Haelwenn committed
173
### Get a account registeration invite token
Maxim Filippov's avatar
Maxim Filippov committed
174
175
176
177

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

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

Haelwenn's avatar
Haelwenn committed
181
### Sends registration invite via email
Maxim Filippov's avatar
Maxim Filippov committed
182
183
184
185
186

- Methods: `POST`
- Params:
  - `email`
  - `name`, optionnal
Haelwenn's avatar
Haelwenn committed
187
188

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

Haelwenn's avatar
Haelwenn committed
190
### Get a password reset token for a given nickname
Maxim Filippov's avatar
Maxim Filippov committed
191
192
193
194

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