Artists

Endpoints for managing represented artists (for gallery accounts).

Create or Update Artist

POST /v1/artists

Create or update a represented artist. The artist is automatically linked to your gallery.

Required scope: artists:write
Required entity type: gallery

Request Body

Field	Type	Required	Description
`name`	string	✅	Artist’s full name
`nationality`	string		Nationality (e.g., “German”)
`birth_year`	number		Year of birth
`biography`	string		Artist biography
`external_url`	string		Link to the artist’s website

Deduplication

Artist names are normalized to slugs. If an artist with the same normalized name exists, they are updated and linked to your gallery.

Example

curl -X POST https://api.artland.com/v1/artists \
  -H "Authorization: Bearer ak_liv...re" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Schmidt",
    "nationality": "German",
    "birth_year": 1985,
    "biography": "Contemporary abstract artist working with color theory and geometric forms.",
    "external_url": "https://mariaschmidt.com"
  }'

Response (201):

{
  "id": 42,
  "name": "Maria Schmidt",
  "slug": "maria-schmidt",
  "created": true
}

List Artists

GET /v1/artists

List all artists for the entity bound to your API key.

Required scope: artists:read

Query Parameters

Parameter	Default	Description
`page`	1	Page number
`limit`	50	Results per page (max: 100)

Example

curl https://api.artland.com/v1/artists \
  -H "Authorization: Bearer ak_liv...n**Response (200):**
```json
{
  "artists": [
    {
      "id": 42,
      "name": "Maria Schmidt",
      "slug": "maria-schmidt",
      "nationality": "German",
      "birth_year": 1985,
      "biography": "Contemporary abstract artist..."
    }
  ],
  "total": 8,
  "page": 1,
  "limit": 50
}

Auto-Linking

When you push an artwork with artist_name, the system:

Normalizes the artist name
Looks up existing artists by slug
Creates the artist if not found
Links the artwork to the artist
Links the artist to your gallery

This means you can push artworks with artist_name without separately creating the artist first — the system handles it automatically.