{"openapi":"3.1.0","info":{"title":"Street Art Cities Artists API","description":"Search and look up the artists behind the artworks 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":{"ArtistSummary":{"type":"object","properties":{"@type":{"type":"string","const":"Artist"},"id":{"type":"string"},"title":{"type":"string"},"href":{"type":"string","description":"Link to the artist on Street Art Cities"},"alternativeTitles":{"type":"array","items":{"type":"string"},"description":"Other names they go by, and other ways to spell their name"},"logoImage":{"description":"Link to their profile picture","type":"string"},"country":{"description":"Where they're based","type":"string"},"artworksCount":{"type":"number","description":"How many of their artworks are on the map"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["@type","id","title","href","alternativeTitles","artworksCount"]},"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/artists":{"get":{"operationId":"getApiArtists","tags":["Artists"],"x-scope-required":["artists:read"],"summary":"Search artists","description":"Find artists by name, or list the artists with markers in a city or country. Results are a lighter version of what [Get an artist](/artists-api/reference/get-an-artist/) gives you.","responses":{"200":{"description":"The artists that match","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ArtistSummary"}},"page":{"type":"number"},"perPage":{"type":"number"},"total":{"type":"number","description":"How many artists match, over all pages"}},"required":["items","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 artists: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 artist's name and other names"},{"in":"query","name":"city","schema":{"type":"string","pattern":"^[\\w-]+$"},"description":"Only artists with markers in this city, like `amsterdam`"},{"in":"query","name":"country","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"description":"Only artists with markers in this country, like `NL`"},{"in":"query","name":"sort","schema":{"type":"string","enum":["relevance","popular","oldest"]},"description":"`relevance` when you pass `q`, otherwise `popular` (most artworks first). `oldest` lists the first added first"},{"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/artists/{artistId}":{"get":{"operationId":"getApiArtistsByArtistId","tags":["Artists"],"x-scope-required":["artists:read"],"summary":"Get an artist","description":"Everything about one artist, straight from the database. Artists that were merged into another one give a 404.","parameters":[{"name":"artistId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The artist","content":{"application/json":{"schema":{"type":"object","properties":{"@type":{"type":"string","const":"Artist"},"id":{"type":"string"},"title":{"type":"string"},"href":{"type":"string","description":"Link to the artist on Street Art Cities"},"alternativeTitles":{"type":"array","items":{"type":"string"},"description":"Other names they go by, and other ways to spell their name"},"logoImage":{"description":"Link to their profile picture","type":"string"},"country":{"description":"Where they're based","type":"string"},"artworksCount":{"type":"number","description":"How many of their artworks are on the map"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"bio":{"type":"string"},"headerImage":{"type":"string"},"socialLinks":{"description":"Links to their website and social media","type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":"string"}},"required":["type","url"]}},"homeTown":{"type":"object","properties":{"label":{"type":"string"},"country":{"type":"string"}},"required":["label"],"additionalProperties":{}},"currentTown":{"type":"object","properties":{"label":{"type":"string"},"country":{"type":"string"}},"required":["label"],"additionalProperties":{}},"claimed":{"description":"Whether the artist looks after this profile themselves","type":"boolean"},"attributes":{"description":"Extra details, like their nationality","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["@type","id","title","href","alternativeTitles","artworksCount"],"additionalProperties":{}}}}},"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 artists: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"]}}}}}}},"/api/artists/{artistId}/markers":{"get":{"operationId":"getApiArtistsByArtistIdMarkers","tags":["Artists"],"x-scope-required":["artists:read"],"summary":"List an artist's markers","description":"The artist's artworks and other markers. Takes the same options and gives the same results as [Search markers](/markers-api/reference/search-markers/).","parameters":[{"name":"artistId","in":"path","required":true,"schema":{"type":"string"}},{"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)"}],"responses":{"200":{"description":"The artist's markers","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 artists: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"]}}}}}}}}}