# The review queue

Why every change made through an app is checked first, and how reviewing works.

When people edit things on Street Art Cities themselves, trusted hunters' changes often go live straight away. **Changes made through an app never do.** They always go to the review queue first, so that apps can't flood the map with changes, even by accident.

## What happens to an edit

```text
  submitted ──▶ accepted ──▶ reverted
      │
      └──────▶ rejected
```

| Status      | Meaning                                                |
| ----------- | ------------------------------------------------------ |
| `submitted` | Waiting in the review queue                            |
| `accepted`  | A reviewer accepted it, and it's live                  |
| `rejected`  | A reviewer rejected it. `reviewComment` often says why |
| `reverted`  | It was accepted, but later undone                      |

The person who suggested the edit gets a notification when it's accepted or rejected.

`POST /api/edits/evaluate-permissions` always answers `"autoAccept": false` for apps. It also tells you whether the person could accept the change themselves, with `canAccept`. Use both to choose the right words in your app, like _"Suggest a change"_, or _"Your change will be ready to review"_ when `canAccept` is `true`.

```json
{
  "autoAccept": false,
  "canAccept": true
}
```

If `canAccept` is `true`, send the person to the [review link](#the-review-link), so they can check the change and accept it themselves. Don't accept it for them through the API (see [below](#reviewing-through-the-api)).

## The review link

Every edit has a `reviewUrl`, like `https://streetartcities.com/community/review-queue/b3d1c1f4-…`. The page shows the change and its status to the person who suggested it, and to everyone who can review it. Link to it from your app, so people can follow their suggestions.

If the person is allowed to review the edit, they can accept or reject it on that page, including their own edits. That keeps them in charge, while making sure every app-made change is looked at by a person.

## Reviewing through the API

Apps with the `edits:review` scope can review too, for people who are reviewers. This is only meant for apps that help people review **other people's** changes, like a review queue app for a city's hunters.

<Admonition kind="warning" title="Never accept your own app's changes">
  Changes your app suggests must always be accepted by a person, who presses
  **Accept** by hand on the [review link](#the-review-link). Don't use
  `edits:review` to accept them, and don't accept changes without someone
  checking them first. We don't allow fully automated or bulk changes at the
  moment.
</Admonition>

When `GET /api/edits/:id` answers `"reviewable": true`, your app can show it to the person, and accept or reject it once they've decided:

```bash
curl -X POST https://streetartcities.com/api/edits/b3d1c1f4-…/accept \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reviewComment": "Checked it, thanks!" }'
```

| Endpoint                     | What it does                                                        |
| ---------------------------- | ------------------------------------------------------------------- |
| `POST /api/edits/:id/accept` | Applies the change                                                  |
| `POST /api/edits/:id/reject` | Rejects it. Use `reviewComment` to explain why                      |
| `POST /api/edits/:id/revert` | Undoes an accepted change, as long as nothing else changed it since |

Who can review depends on the edit: usually the hunters of the city an artwork
is in, the country's managers, and admins. The `edits:review` scope doesn't
change that, it only lets your app do it for them.