# Suggesting changes
Describe what should change using actions, and send it to the review queue.
A suggested change is called an **edit**. Each edit changes one thing, like an artwork or an artist, and describes what should change in a map of **actions**.
## Send an edit
```bash
curl -X POST https://streetartcities.com/api/edits \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"entityType": "marker",
"entityId": "9ff36a03-5b1c-4b8f-9a0e-2f0c1f6c2d11",
"actions": {
"attributes.access_note": "Only visible whilst the shop is open.",
"tags": { "$add": ["stencil"] }
},
"editComment": "Went there today, it's a stencil"
}'
```
| Field | Required | Value |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `entityType` | Yes | What kind of thing you're changing, see the [overview](/edits-api/overview/#what-you-can-change) |
| `entityId` | No | The ID of what you're changing. Leave it out to add something new |
| `actions` | Yes | What should change |
| `editComment` | No | A note for the reviewers, explaining the change |
| `editAttachments` | No | Up to 10 links to images that back up the change, see [images](#images) |
You get back `201` with the edit:
```json
{
"edit": {
"id": "b3d1c1f4-…",
"entityType": "marker",
"entityId": "9ff36a03-…",
"status": "submitted",
"actions": { "…": "…" },
"createdAt": "2026-09-24T10:12:00.000Z",
"reviewUrl": "https://streetartcities.com/community/review-queue/b3d1c1f4-…"
}
}
```
Show the `reviewUrl` to the person, so they can follow what happens to their suggestion. Learn more in [the review queue](/edits-api/review-queue/).
## Actions
`actions` is a flat map. Each **key** is a path to a field, using dots for nested fields. Each **value** is either the new value, or an operation.
```json
{
"title": "Flower girl",
"attributes.access_note": "Only visible whilst the shop is open.",
"tags": { "$add": ["stencil"], "$remove": ["mural"] },
"attributes.old_note": { "$unset": true }
}
```
| Value | What it does |
| ------------------------------------- | --------------------------------- |
| Anything else | Sets the field to this value |
| `{ "$add": [...], "$remove": [...] }` | Adds or removes items from a list |
| `{ "$unset": true }` | Removes the field |
List items with an `id`, like artists, are matched on their `id` alone. So `{ "$remove": [{ "id": "banksy" }] }` removes Banksy, whatever title the marker has saved for them.
There are also a few special keys for existing things:
| Key | Value | What it does |
| ------------ | --------------------------- | ----------------------------------------------- |
| `$mergeInto` | Another ID of the same type | Merges this one into the other (for duplicates) |
| `$delete` | `true` | Deletes it. Must be the only action |
| `$renameTo` | A new name | Renames a tag. Only works for tags |
Send `"attributes.style": "…"` rather than `"attributes": { "style": "…" }`. The second one replaces all of `attributes`, and wipes out anything you didn't include.
A city's Official Partner settings (like `attributes.verified` or
`attributes.verifiedLogo`) can't be changed through the API. Changing them, or
replacing a city's whole `attributes`, returns a `403`.
## Adding a new artwork
Leave out `entityId`, and use the same field names you get from the [Markers API](/markers-api/overview/#a-marker):
```json
{
"entityType": "marker",
"actions": {
"lat": 52.3731,
"lng": 4.8922,
"city": "amsterdam",
"type": "artwork",
"title": "Big cat",
"images": [
{
"id": "0b6e1c2d-…",
"url": "https://streetartcities.com/media/…/orig.jpg"
}
],
"artists": [{ "id": "someone" }, { "title": "Someone new" }]
},
"editComment": "Spotted this today"
}
```
- Always send `lat`, `lng` and `city`. The city decides who reviews the suggestion, so without it, it can take a lot longer. Use the nearest city from [the list of cities](https://streetartcities.com/data/global/cities.json). Send its ID, or the whole `city` you got from the Markers API. We fill in the `country` from the city, unless you send one.
- Send each artist as `{ "id" }` or `{ "title" }`. Find their IDs with the [Artists API](/artists-api/overview/#searching), which also looks at other names they go by. With an ID, we fill in the artist's current name, and an ID we don't know returns a `400`. With just a name, we use the artist with exactly that name (capitals count). If there isn't one, a new artist is added when the edit is accepted, so you don't need to add them separately first. This works for a new artwork's `artists`, and for `$add`.
- Photos go in `images`. See [uploading images](/edits-api/uploading-images/#3-use-the-image) for how to add them.
- When there's no title, the artwork is called "Untitled".
Edits you get back use our own names: `site` instead of `city`, and `markerType` instead of `type`. The same goes for `entityType`: send `city` or `site`, you get back `site`.
## Images
Images in markers' `actions.images` and `editAttachments` have to be on Street Art Cities already: `https` links starting with `https://streetartcities.com/media/`.
Other links are turned down with a `400`. To get your own images there, see [uploading images](/edits-api/uploading-images/).
## See the person's edits
`GET /api/edits/mine` lists the edits the person has suggested, newest first. `GET /api/edits/:id` returns one edit with a preview of what it changes:
```json
{
"edit": { "id": "b3d1c1f4-…", "status": "submitted", "…": "…" },
"reviewable": false,
"revertible": false,
"changes": [
{ "path": "tags", "before": ["mural"], "after": ["mural", "stencil"] }
]
}
```
For the full list of fields, see the [API reference](https://petstore3.swagger.io/?url=https://streetartcities.com/api/edits/openapi).