Suggesting changes

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

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"
  }'

You get back 201 with the edit:

{
  "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.

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.

{
  "title": "Flower girl",
  "attributes.access_note": "Only visible whilst the shop is open.",
  "tags": { "$add": ["stencil"], "$remove": ["mural"] },
  "attributes.old_note": { "$unset": true }
}

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:

Adding a new artwork

Leave out entityId, and use the same field names you get from the Markers API:

{
  "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. 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, 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 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.

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:

{
  "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.