# Profiles API overview

Look up people's public profiles, and the artworks someone liked and saw.

The Profiles API lets your app show someone's public profile, and list the artworks the person using your app liked and saw.

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

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

## Endpoints

| Endpoint                         | Scope           | What it does                                                         |
| -------------------------------- | --------------- | -------------------------------------------------------------------- |
| `GET /api/profiles/user/:userId` | `profiles:read` | [Someone's public profile](/profiles-api/reference/get-a-profile/)   |
| `GET /api/profiles/me/likes`     | `likes:read`    | [What the person liked](/profiles-api/reference/list-your-likes/)    |
| `GET /api/profiles/me/seen`      | `seen:read`     | [What the person saw](/profiles-api/reference/list-what-youve-seen/) |

The `me` endpoints are always about the person who gave your app access. There's no way to see someone else's likes or what they've seen.

<Admonition kind="info" title="Only ask for what you need">
  What someone has seen says a lot about where they've been. Only ask for
  `seen:read` when your app really needs it.
</Admonition>

## A profile

```json
{
  "@type": "Profile",
  "id": "a1b2c3",
  "href": "https://streetartcities.com/users/a1b2c3",
  "displayName": "Someone",
  "avatar": "https://streetartcities.com/media/avatars/…/small.jpg",
  "bio": "Hunting for murals since 2015.",
  "socialLinks": [{ "type": "instagram", "url": "https://instagram.com/…" }],
  "followerCount": 120,
  "followingCount": 45,
  "decorations": [
    {
      "id": "country-manager",
      "title": "Country Manager",
      "image": "https://streetartcities.com/images/decorations/country-manager.png"
    }
  ],
  "badges": [
    {
      "id": "first-seen",
      "title": "First sighting",
      "description": "…",
      "image": "https://streetartcities.com/images/badges/first-seen.png"
    }
  ],
  "createdAt": "2026-01-01T12:00:00.000Z"
}
```

It only has what anyone can see on the person's profile on Street Art Cities. To get the email address of the person using your app, use [Log in with Street Art Cities](/authentication/openid-connect/).

## Likes and seen artworks

Both lists are newest first, and come in pages:

```bash
curl "https://streetartcities.com/api/profiles/me/likes?page=1&perPage=20" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

```json
{
  "items": [
    {
      "type": "marker",
      "id": "108322",
      "title": "Big cat",
      "artistsString": "Someone, Someone Else",
      "thumbnail": "https://streetartcities.com/media/markers/…/thumbnail.jpg",
      "href": "https://streetartcities.com/cities/amsterdam/markers/108322",
      "createdAt": "2026-09-01T10:00:00.000Z"
    },
    {
      "type": "comment",
      "id": "f4e5d6",
      "title": "Big cat",
      "comment": "Saw this one being painted!",
      "href": "https://streetartcities.com/cities/amsterdam/markers/108322",
      "createdAt": "2026-08-20T18:30:00.000Z"
    }
  ],
  "page": 1,
  "perPage": 20,
  "total": 2
}
```

| Parameter      | What it does                                                     |
| -------------- | ---------------------------------------------------------------- |
| `page`         | Which page, starting at 1                                        |
| `perPage`      | How many per page (20 by default, at most 100)                   |
| `updatedSince` | Only what was added since this time, like `2026-09-01T00:00:00Z` |

`type` is `marker` for an artwork or other place on the map. Likes can also be on a `comment`: those come with the title, thumbnail and link of the artwork the comment is on, and the comment itself. Use the `id` of a marker with the [Markers API](/markers-api/overview/) to get everything about it.

The seen list also has the artworks the person hunted (added to the map) themselves, since they've clearly seen those too.

`createdAt` is when the person liked it, saw it or hunted it. Someone can see the same artwork more than once, but it's only listed once, with the last time they saw it. People can also log a visit from the past, so a seen `createdAt` can be long ago.

If something was deleted after the person liked or saw it, you only get its `type`, `id` and `createdAt`.

## Keeping a copy in sync

Get every page once, and write down when you started. Next time, pass that time as `updatedSince` to only get what was added since:

```bash
curl "https://streetartcities.com/api/profiles/me/seen?updatedSince=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

This goes by when something was added to the list, not by `createdAt`, so you also get visits from the past the person logged since. Unlikes don't show up this way: to catch those, get the full list of likes now and then.

## Errors

Errors look like this:

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

You get a `404` when there's no one with that ID, and a `403` when your app doesn't have the scope the endpoint needs.