Artworks

Endpoints for managing artworks in your Artland catalog.

Create or Update Artwork

POST /v1/artworks

Creates a new artwork or updates an existing one (matched by source fingerprint).

Required scope: artworks:write

Request Body

Field	Type	Required	Description
`title`	string	✅	Artwork title
`creation_year`	number		Year of creation
`medium`	string		Medium (e.g., “Oil on canvas”)
`dimensions`	string		Dimensions (e.g., “120 × 90 cm”)
`price`	number		Price as integer
`currency`	string		ISO currency code (e.g., “EUR”, “USD”)
`availability`	string		”available”, “sold”, “reserved”
`description`	string		Artwork description
`image_url`	string		Permanent URL to the artwork image
`external_url`	string		Link to the artwork on your website
`artist_name`	string		Artist name — resolved and auto-linked

Deduplication

A source fingerprint is computed server-side:

SHA-256(normalizeSlug(artist_name) + '|' + normalizeSlug(title) + '|' + year)

If the fingerprint already exists, the artwork is updated (non-null fields merged, last_synced_at refreshed).

Example

curl -X POST https://api.artland.com/v1/artworks \
  -H "Authorization: Bearer ak_liv...re" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Composition in Blue",
    "creation_year": 2024,
    "medium": "Oil on canvas",
    "dimensions": "120 × 90 cm",
    "price": 45000,
    "currency": "EUR",
    "availability": "available",
    "description": "Part of the Chromatic Series...",
    "image_url": "https://gallery.example.com/artworks/composition-blue.jpg",
    "external_url": "https://gallery.example.com/artworks/composition-blue",
    "artist_name": "Maria Schmidt"
  }'

Response (201):

{
  "id": 123,
  "title": "Composition in Blue",
  "source_fingerprint": "a1b2c3d4e5f6...",
  "created": true
}

When updating an existing artwork, created returns false.

List Artworks

GET /v1/artworks

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

Required scope: artworks:read

Query Parameters

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

Example

curl https://api.artland.com/v1/artworks?page=1&limit=10 \
  -H "Authorization: Bearer ak_liv...n**Response (200):**
```json
{
  "artworks": [
    {
      "id": 123,
      "title": "Composition in Blue",
      "creation_year": 2024,
      "medium": "Oil on canvas",
      "dimensions": "120 × 90 cm",
      "price": 45000,
      "currency": "EUR",
      "availability": "available"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 10
}

Get Artwork

GET /v1/artworks/:id

Retrieve a single artwork by ID.

Required scope: artworks:read

Example

curl https://api.artland.com/v1/artworks/123 \
  -H "Authorization: Bearer ak_liv...n**Response (200):**
```json
{
  "id": 123,
  "title": "Composition in Blue",
  "creation_year": 2024,
  "medium": "Oil on canvas",
  "dimensions": "120 × 90 cm",
  "price": 45000,
  "currency": "EUR",
  "availability": "available",
  "description": "Part of the Chromatic Series...",
  "image_url": "https://gallery.example.com/artworks/composition-blue.jpg",
  "external_url": "https://gallery.example.com/artworks/composition-blue",
  "artist_name": "Maria Schmidt"
}

Update Artwork

PUT /v1/artworks/:id

Update an existing artwork. You must own the artwork via entity binding.

Required scope: artworks:write

Example

curl -X PUT https://api.artland.com/v1/artworks/123 \
  -H "Authorization: Bearer ak_liv...re" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 52000,
    "availability": "reserved"
  }'

Response (200):

{
  "id": 123,
  "title": "Composition in Blue",
  "price": 52000,
  "availability": "reserved"
}