> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tattoo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List Artists

> Authenticated internal-beta endpoint for runtime-backed artist profile reads.

<Note>
  **Posture:** Authenticated internal beta. The caller must resolve to a mapped TattooAPI actor before access is granted.
</Note>

<Warning>
  **Write boundary:** Public writes are blocked. Do not build production flows assuming mutation is live on this route family.
</Warning>

Canonical request URL: `https://api.tattooapi.com/api/v1/artists`.

# List Artists

`GET /artists` is an authenticated internal-beta read endpoint.

It returns runtime-backed `ArtistProfile` records for team, SDK, and operator development. This is not promoted as a no-auth public endpoint yet.

## Auth

Use an approved bearer token or partner API key mapped to a TattooAPI actor.

```bash theme={"dark"}
curl "$TATTOO_API_BASE_URL/artists?limit=20" \
  -H "X-API-Key: YOUR_PARTNER_API_KEY"
```

## Query Parameters

| Parameter         | Type    | Notes                                                      |
| ----------------- | ------- | ---------------------------------------------------------- |
| `page`            | integer | Default `1`                                                |
| `limit`           | integer | Default `20`, max `100`                                    |
| `studio_id`       | string  | Filter by studio id                                        |
| `specialty`       | string  | Filter by specialty                                        |
| `min_experience`  | number  | Minimum years of experience                                |
| `max_hourly_rate` | number  | Maximum hourly rate when present                           |
| `is_active`       | boolean | Filter by active state                                     |
| `search`          | string  | Name, bio, and specialty search                            |
| `sort_by`         | string  | `name`, `years_experience`, `hourly_rate`, or `created_at` |
| `sort_order`      | string  | `asc` or `desc`                                            |

## Response Shape

```json theme={"dark"}
{
  "success": true,
  "data": [
    {
      "id": "artist:example",
      "name": "Example Artist",
      "studio_id": "studio:example",
      "specialties": ["black_and_grey"],
      "is_active": true,
      "created_at": "2026-04-30T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}
```

## Write Boundary

`POST` is explicitly blocked on this route. Public artist writes are not active.

Artist profile mutation belongs to governed internal profile-review contracts first, then later owner-scoped contracts after the access model is proven.