documentation

admin/reports API methods

Perform moderation actions with reports.

Last modified Sun Dec 18, 2022
Edit this page

View all reports 

GET /api/v1/admin/reports HTTP/1.1

View information about all reports.

Returns: Array of Admin::Report
OAuth: User token + admin:read:reports
Permissions: Manage Reports
Version history:
2.9.1 - added
4.0.0 - support custom roles and permissions

Request

Headers
Authorization
required Provide this header with Bearer <user token> to gain authorized access to this API method.
Query parameters
resolved
Boolean. Filter for resolved reports?
account_id
String. Filter for reports filed by this account.
target_account_id
String. Filter for reports targeting this account.
max_id
Internal parameter. Use HTTP Link header for pagination.
since_id
Internal parameter. Use HTTP Link header for pagination.
min_id
Internal parameter. Use HTTP Link header for pagination.
limit
Integer. Maximum number of results to return. Defaults to 100 reports. Max 200 reports.

Response

200: OK 
[
	{
		"id": "3",
		"action_taken": false,
		"action_taken_at": null,
		"category": "spam",
		"comment": "",
		"forwarded": false,
		"created_at": "2022-09-09T21:19:23.085Z",
		"updated_at": "2022-09-09T21:19:23.085Z",
		"account": {
			"id": "108965218747268792",
			"username": "admin",
			"domain": null,
			"created_at": "2022-09-08T22:48:07.985Z",
			"email": "admin@mastodon.local",
			// ...
			"account": {
				"id": "108965218747268792",
				"username": "admin",
				"acct": "admin",
				// ...
			}
		},
		"target_account": {
			"id": "108965430868193066",
			"username": "goody",
			"domain": null,
			"created_at": "2022-09-08T23:42:04.731Z",
			"email": "goody@mastodon.local",
			// ...
			"account": {
				"id": "108965430868193066",
				"username": "goody",
				"acct": "goody",
				// ...
			}
		},
		"assigned_account": null,
		"action_taken_by_account": null,
		"statuses": [],
		"rules": []
	},
	// ...
]

Because Report IDs are generally not exposed via any API responses, you will have to parse the HTTP Link header to load older or newer results. See Paginating through API responses for more information.

Link: <http://mastodon.example/api/v1/admin/reports?limit=2&max_id=2>; rel="next", <http://mastodon.example/api/v1/admin/reports?limit=2&since_id=1>; rel="prev"
403: Forbidden

Authorized user is not allowed to perform this action, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

View a single report 

GET /api/v1/admin/reports/:id HTTP/1.1

Returns: Admin::Report
OAuth: User token + admin:read:reports
Permissions: Manage Reports
Version history:
2.9.1 - added
4.0.0 - support custom roles and permissions

Request

Path parameters
:id
required String. The ID of the Report in the database.
Headers
Authorization
required Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK 
{
  "id": "2",
  "action_taken": true,
  "action_taken_at": "2022-09-09T21:38:54.679Z",
  "category": "spam",
  "comment": "",
  "forwarded": false,
  "created_at": "2022-09-09T21:19:44.021Z",
  "updated_at": "2022-09-09T21:38:54.681Z",
  "account": {
    "id": "108965218747268792",
    "username": "admin",
    "domain": null,
    "created_at": "2022-09-08T22:48:07.985Z",
    "email": "admin@mastodon.local",
    // ...
    "account": {
      "id": "108965218747268792",
      "username": "admin",
      "acct": "admin",
      // ...
    }
  },
  "target_account": {
    "id": "108965430868193066",
    "username": "goody",
    "domain": null,
    "created_at": "2022-09-08T23:42:04.731Z",
    "email": "goody@mastodon.local",
    // ...
    "account": {
      "id": "108965430868193066",
      "username": "goody",
      "acct": "goody",
      // ...
    }
  },
  "assigned_account": null,
  "action_taken_by_account": {
    "id": "108965218747268792",
    "username": "admin",
    "domain": null,
    "created_at": "2022-09-08T22:48:07.985Z",
    "email": "admin@mastodon.local",
    // ...
    "account": {
      "id": "108965218747268792",
      "username": "admin",
      "acct": "admin",
      // ...
    }
  },
  "statuses": [],
  "rules": []
}
403: Forbidden

Authorized user is not allowed to perform this action, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

Update a report 

PUT /api/v1/admin/reports/:id HTTP/1.1

Change metadata for a report.

Returns: Admin::Report
OAuth: User token + admin:write:reports
Permissions: Manage Reports
Version history:
3.5.0 - added
4.0.0 - support custom roles and permissions

Request

Path parameters
:id
required String. The ID of the Report in the database.
Headers
Authorization
required Provide this header with Bearer <user token> to gain authorized access to this API method.
Form data parameters
category
String. Change the classification of the report to spam, violation, or other.
rule_ids[]
Array of Integer. For violation category reports, specify the ID of the exact rules broken. Rules and their IDs are available via GET /api/v1/instance/rules and GET /api/v1/instance.

Response

200: OK

The report category and/or rule IDs should now be updated.

{
  "id": "3",
  "action_taken": false,
  "action_taken_at": null,
  "category": "other",
  // ...
  "rules": []
}
403: Forbidden

Authorized user is not allowed to perform this action, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

Assign report to self 

POST /api/v1/admin/reports/:id/assign_to_self HTTP/1.1

Claim the handling of this report to yourself.

Returns: Admin::Report
OAuth: User token + admin:write:reports
Permissions: Manage Reports
Version history:
2.9.1 - added
4.0.0 - support custom roles and permissions

Request

Path parameters
:id
required String. The ID of the Report in the database.
Headers
Authorization
required Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

The report should now be assigned to you, or it was already assigned to you.

{
  "id": "3",
  "action_taken": false,
  "action_taken_at": null,
  "category": "other",
  "comment": "",
  "forwarded": false,
  "created_at": "2022-09-09T21:21:01.204Z",
  "updated_at": "2022-09-11T14:39:01.531Z",
  // ...
  "assigned_account": {
    "id": "108965218747268792",
    "username": "admin",
    "domain": null,
    "created_at": "2022-09-08T22:48:07.985Z",
    "email": "admin@mastodon.local",
    // ...
    "account": {
      "id": "108965218747268792",
      "username": "admin",
      "acct": "admin",
      // ...
    }
  },
  "action_taken_by_account": null,
  "statuses": [],
  "rules": []
}
403: Forbidden

Authorized user is not allowed to perform this action, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

Unassign report 

POST /api/v1/admin/reports/:id/unassign HTTP/1.1

Unassign a report so that someone else can claim it.

Returns: Admin::Report
OAuth: User token + admin:write:reports
Permissions: Manage Reports
Version history:
2.9.1 - added 4.0.0 - support custom roles and permissions

Request

Path parameters
:id
required String. The ID of the Report in the database.
Headers
Authorization
required Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

The report should no longer be assigned to you, or it was already not assigned to anyone.

{
  "id": "3",
  "action_taken": false,
  "action_taken_at": null,
  "category": "other",
  "comment": "",
  "forwarded": false,
  "created_at": "2022-09-09T21:21:01.204Z",
  "updated_at": "2022-09-11T14:39:01.531Z",
  // ...
  "assigned_account": null,
  "action_taken_by_account": null,
  "statuses": [],
  "rules": []
}
403: Forbidden

Authorized user is not allowed to perform this action, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

Mark report as resolved 

POST /api/v1/admin/reports/:id/resolve HTTP/1.1

Mark a report as resolved with no further action taken.

Returns: Admin::Report
OAuth: User token + admin:write:reports
Permissions: Manage Reports
Version history:
2.9.1 - added
4.0.0 - support custom roles and permissions

Request

Path parameters
:id
required String. The ID of the Report in the database.
Headers
Authorization
required Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

The report is now resolved, or it was already resolved.

{
  "id": "2",
  "action_taken": true,
  "action_taken_at": "2022-09-11T14:46:22.936Z",
  "category": "spam",
  "comment": "",
  "forwarded": false,
  "created_at": "2022-09-09T21:19:44.021Z",
  "updated_at": "2022-09-11T14:46:22.945Z",
  // ...
}
403: Forbidden

Authorized user is not allowed to perform this action, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

Reopen a closed report 

POST /api/v1/admin/reports/:id/reopen HTTP/1.1

Reopen a currently closed report, if it is closed.

Returns: Admin::Report
OAuth: User token + admin:write:reports
Permissions: Manage Reports
Version history:
2.9.1 - added
4.0.0 - support custom roles and permissions

Request

Path parameters
:id
required String. The ID of the Report in the database.
Headers
Authorization
required Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

The report no longer has an action taken, or it already had no action taken.

{
  "id": "2",
  "action_taken": false,
  "action_taken_at": null,
  "category": "spam",
  "comment": "",
  "forwarded": false,
  "created_at": "2022-09-09T21:19:44.021Z",
  "updated_at": "2022-09-11T14:42:21.855Z",
  // ...
}
403: Forbidden

Authorized user is not allowed to perform this action, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

See also

POST /api/v1/admin/accounts/:id/action
app/controllers/api/v1/admin/reports_controller.rb