# Artists API overview

Search and look up the artists behind the artworks on the Street Art Cities map.

The Artists API lets your app find artists, look them up, and list their artworks.

**Base link:** `https://streetartcities.com/api/artists`

**API reference:** [open in Swagger UI](https://petstore3.swagger.io/?url=https://streetartcities.com/api/artists/openapi), or grab the [OpenAPI spec](https://streetartcities.com/api/artists/openapi) directly.

<Admonition kind="info" title="Want to change an artist?">
  The Artists API is read-only. To fix mistakes, [suggest a
  change](/edits-api/suggesting-changes/) with the Edits API.
</Admonition>

## Endpoints

| Endpoint                       | Scope          | What it does                                                            |
| ------------------------------ | -------------- | ----------------------------------------------------------------------- |
| `GET /api/artists`             | `artists:read` | [Search artists](/artists-api/reference/search-artists/)                |
| `GET /api/artists/:id`         | `artists:read` | [Everything about one artist](/artists-api/reference/get-an-artist/)    |
| `GET /api/artists/:id/markers` | `artists:read` | [The artist's markers](/artists-api/reference/list-an-artists-markers/) |

All of them need an access token with the `artists:read` scope.

## An artist

```json
{
  "@type": "Artist",
  "id": "someone",
  "title": "Someone",
  "href": "https://streetartcities.com/artists/someone",
  "alternativeTitles": ["S0meone", "Someone Else"],
  "logoImage": "https://streetartcities.com/media/artists/…/logo.jpg",
  "country": "Netherlands",
  "artworksCount": 42,
  "createdAt": "2026-01-01T12:00:00.000Z",
  "updatedAt": "2026-02-01T08:30:00.000Z",
  "bio": "Paints big cats.",
  "socialLinks": [{ "type": "instagram", "url": "https://instagram.com/…" }]
}
```

`alternativeTitles` are other names the artist goes by, and other ways to spell their name. Search looks at those too.

`GET /api/artists/:id` gives you all of this, straight from our database. Search results only have the fields up to `updatedAt`.

## Searching

```bash
curl "https://streetartcities.com/api/artists?q=someone" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

| Parameter      | What it does                                                                        |
| -------------- | ----------------------------------------------------------------------------------- |
| `q`            | Words to look for in the artist's name and other names                              |
| `city`         | Only artists with markers in this city, like `amsterdam`                            |
| `country`      | Only artists with markers in this country, like `NL`                                |
| `sort`         | `relevance` (best match for `q` first), `popular` (most artworks first) or `oldest` |
| `updatedSince` | Only artists that changed since this time                                           |

Pages work just like [searching markers](/markers-api/searching-markers/#pages), including [keeping a copy in sync](/markers-api/searching-markers/#keeping-a-copy-in-sync) with `sort=oldest` and `updatedSince`.

## An artist's markers

`GET /api/artists/:id/markers` takes the same options as [searching markers](/markers-api/searching-markers/), and gives the same results. It's the same as searching markers with `artist=:id`.

## Errors

Errors look like this:

```json
{ "error": { "message": "Artist not found." } }
```

You get a `404` when an artist doesn't exist. That includes artists that were merged into another one, when two people added the same artist.