{"openapi":"3.1.0","info":{"title":"Street Art Cities Markers API","description":"Search and look up artworks, legal walls and the other places on the Street Art Cities map.","version":"1.0.0"},"servers":[{"url":"https://streetartcities.com","description":"Production"},{"url":"https://streetartdev.com","description":"Development"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Marker":{"type":"object","properties":{"@type":{"type":"string","const":"Marker"},"id":{"type":"string"},"href":{"type":"string","description":"Link to the marker on Street Art Cities"},"city":{"description":"The city it's in. Missing when it isn't in a city","type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id"]},"country":{"description":"Two-letter country code, like `NL`","type":"string"},"countryName":{"type":"string"},"lat":{"type":"number"},"lng":{"type":"number"},"address":{"type":"string"},"type":{"type":"string","description":"Marker type, like `artwork` or `legal_wall`"},"title":{"type":"string"},"status":{"description":"`active`, `inProgress` or `removed`","type":"string"},"description":{"description":"Can contain simple HTML, like links and line breaks","type":"string"},"artists":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"}},"required":["id","title","href"]},"description":"The artists who made it"},"artistsString":{"type":"string","description":"Names of the artists, comma separated"},"tags":{"type":"array","items":{"type":"string"}},"thumbnail":{"description":"Link to a small image","type":"string"},"likes":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"images":{"description":"Pictures, the first one is the main one. Not in search results","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}},"required":["url"],"additionalProperties":{}}},"attributes":{"description":"Extra details, like the year it was made. Not in search results","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"distance":{"description":"Meters from `lat` and `lng`, when searching by distance. Only in search results","type":"number"}},"required":["@type","id","href","lat","lng","type","artists","artistsString","tags","likes"]}}},"security":[{"bearerAuth":[]}],"paths":{"/api/markers/search":{"get":{"operationId":"getApiMarkersSearch","tags":["Markers"],"x-scope-required":["markers:read"],"summary":"Search markers","description":"Find artworks and other places by keyword, country, city, type or tag, or near a spot on the map. Results are a lighter version of what [Get a marker](/markers-api/reference/get-a-marker/) gives you, without images, attributes and artist details.","responses":{"200":{"description":"The markers that match","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Marker"}},"page":{"type":"number"},"perPage":{"type":"number"},"total":{"type":"number","description":"How many markers match, over all pages"}},"required":["items","page","perPage","total"]}},"application/geo+json":{"schema":{"type":"object","properties":{"type":{"type":"string","const":"FeatureCollection"},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"Feature"},"id":{"type":"string"},"geometry":{"type":"object","properties":{"type":{"type":"string","const":"Point"},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"required":["type","coordinates"]},"properties":{"$ref":"#/components/schemas/Marker"}},"required":["type","id","geometry","properties"]}},"page":{"type":"number"},"perPage":{"type":"number"},"total":{"type":"number"}},"required":["type","features","page","perPage","total"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{"type":"array","items":{}}},"required":["message"]}},"required":["error"]}}}},"401":{"description":"Not logged in","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{"type":"array","items":{}}},"required":["message"]}},"required":["error"]}}}},"403":{"description":"The app doesn't have the markers:read scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{"type":"array","items":{}}},"required":["message"]}},"required":["error"]}}}}},"parameters":[{"in":"query","name":"q","schema":{"type":"string","maxLength":200},"description":"Words to look for in the title, artists, address and tags"},{"in":"query","name":"country","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"description":"Two-letter country code, like `NL`"},{"in":"query","name":"city","schema":{"type":"string","pattern":"^[\\w-]+$"},"description":"City ID, like `amsterdam`"},{"in":"query","name":"type","schema":{"type":"string","pattern":"^[\\w-]+$"},"description":"Marker type, like `artwork` or `legal_wall`"},{"in":"query","name":"status","schema":{"default":"active","type":"string","enum":["active","inProgress","removed","all"]},"description":"`active` by default. Use `removed` for artworks that are gone, or `all` for everything"},{"in":"query","name":"tag","schema":{"type":"string","maxLength":100},"description":"Only markers with this tag"},{"in":"query","name":"artist","schema":{"type":"string","pattern":"^[\\w-]+$"},"description":"Only markers by this artist, like `banksy`"},{"in":"query","name":"lat","schema":{"type":"number","minimum":-90,"maximum":90},"description":"Latitude, to find markers near a spot (use with `lng`)"},{"in":"query","name":"lng","schema":{"type":"number","minimum":-180,"maximum":180},"description":"Longitude, to find markers near a spot (use with `lat`)"},{"in":"query","name":"radius","schema":{"default":5,"type":"number","exclusiveMinimum":0,"maximum":100},"description":"How far from `lat` and `lng` to look, in km (5 by default)"},{"in":"query","name":"sort","schema":{"type":"string","enum":["relevance","distance","newest","oldest"]},"description":"`distance` when you pass `lat` and `lng`, otherwise `relevance` when you pass `q`, and `newest` when you don't"},{"in":"query","name":"format","schema":{"default":"json","type":"string","enum":["json","geojson"]},"description":"`geojson` gives a GeoJSON FeatureCollection instead"},{"in":"query","name":"updatedSince","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"description":"Only what changed since this time, like `2026-09-01T00:00:00Z`"},{"in":"query","name":"page","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991},"description":"Which page of results, starting at 1"},{"in":"query","name":"perPage","schema":{"default":20,"type":"integer","minimum":1,"maximum":100},"description":"How many results per page (20 by default, at most 100)"}]}},"/api/markers/{markerId}/history":{"get":{"operationId":"getApiMarkersByMarkerIdHistory","tags":["Markers"],"security":[],"summary":"Get a marker's history","description":"Who added the marker, what was changed since, and the notes people left, like comments and 'Seen' reports. You don't need an access token for this one.","parameters":[{"name":"markerId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The marker's history","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Create","Update","Note"],"description":"`Create` when the marker was added, `Update` for a change, `Note` for things like comments and 'Seen' reports"},"id":{"type":"string"},"actor":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"href":{"type":"string","description":"Link to their profile"},"avatar":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","displayName","href"],"additionalProperties":{},"description":"Who did it"},"summary":{"description":"What happened, with links written as `<name|link>`, like `<Jane|https://…> changed the title to 'Big cat'`","type":"string"},"content":{"description":"Comment left with it","anyOf":[{"type":"string"},{"type":"null"}]},"published":{"type":"string","description":"When it happened"},"noteType":{"description":"For notes: the kind of note, like `seen` or `comment`","type":"string"},"attachments":{"type":"array","items":{}},"likesCount":{"type":"number"},"resolved":{"type":"boolean"}},"required":["type","id","actor","published"],"additionalProperties":{}},"description":"Newest first. Only the last few 'Seen' notes are included"},"likesCount":{"type":"number"},"seenCount":{"type":"number","description":"How often it was recently seen"},"lastSeenAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"site":{"description":"The ID of the city it's in","anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"reportingTypes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":{}},"description":"The kinds of notes people can leave on this marker"}},"required":["items","likesCount","seenCount","reportingTypes"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{"type":"array","items":{}}},"required":["message"]}},"required":["error"]}}}}}}},"/api/markers/{markerId}":{"get":{"operationId":"getApiMarkersByMarkerId","tags":["Markers"],"x-scope-required":["markers:read"],"summary":"Get a marker","description":"Everything about one marker, straight from the database. Markers that were merged into another one give a 404.","parameters":[{"name":"markerId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The marker","content":{"application/json":{"schema":{"type":"object","properties":{"@type":{"type":"string","const":"Marker"},"id":{"type":"string"},"href":{"type":"string","description":"Link to the marker on Street Art Cities"},"city":{"description":"The city it's in. Missing when it isn't in a city","type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id"]},"country":{"description":"Two-letter country code, like `NL`","type":"string"},"countryName":{"type":"string"},"lat":{"type":"number"},"lng":{"type":"number"},"address":{"type":"string"},"type":{"type":"string","description":"Marker type, like `artwork` or `legal_wall`"},"title":{"type":"string"},"status":{"description":"`active`, `inProgress` or `removed`","type":"string"},"description":{"description":"Can contain simple HTML, like links and line breaks","type":"string"},"artists":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"}},"required":["id","title","href"]},"description":"The artists who made it"},"artistsString":{"type":"string","description":"Names of the artists, comma separated"},"tags":{"type":"array","items":{"type":"string"}},"thumbnail":{"description":"Link to a small image","type":"string"},"likes":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"images":{"description":"Pictures, the first one is the main one. Not in search results","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}},"required":["url"],"additionalProperties":{}}},"attributes":{"description":"Extra details, like the year it was made. Not in search results","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"distance":{"description":"Meters from `lat` and `lng`, when searching by distance. Only in search results","type":"number"}},"required":["@type","id","href","lat","lng","type","artists","artistsString","tags","likes"]}}}},"401":{"description":"Not logged in","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{"type":"array","items":{}}},"required":["message"]}},"required":["error"]}}}},"403":{"description":"The app doesn't have the markers:read scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{"type":"array","items":{}}},"required":["message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{"type":"array","items":{}}},"required":["message"]}},"required":["error"]}}}}}}}}}