API Overview

The Artland Partner Sync API is a REST API for syncing artworks, artists, and events into Artland.

Base URL

https://api.artland.com/v1/

All endpoints are relative to this base URL.

Authentication

Every request requires an API key:

Authorization: Bearer ak_liv...nSee [Authentication](/getting-started/authentication) for details on key types and scopes.

## Common Patterns

### Pagination

List endpoints support pagination via query parameters:

| Parameter | Default | Max |
|-----------|---------|-----|
| `page` | 1 | — |
| `limit` | 50 | 100 |

```bash
curl "https://api.artland.com/v1/artworks?page=2&limit=25" \
  -H "Authorization: Bearer ak_liv...n```json
{
  "artworks": [...],
  "total": 42,
  "page": 2,
  "limit": 25
}

Response Format

All responses are JSON. Successful creates return 201, successful reads return 200.

Idempotency

Pass an X-Idempotency-Key header to safely retry requests. Keys are cached for 24 hours:

curl -X POST https://api.artland.com/v1/artworks \
  -H "Authorization: Bearer ak_liv...-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"title": "..."}'

Deduplication

Three layers prevent duplicates:

Layer	Scope	Mechanism
Natural key slugs	Galleries, artists, events	`normalized_slug` with `ON CONFLICT DO UPDATE`
Source fingerprint	Artworks	`SHA-256(artist_slug + title + year)`
Idempotency key	All endpoints	Optional `X-Idempotency-Key` header, KV-cached 24h

Auto-Linking

When you push data, the system automatically creates relationship records:

Push Scenario	What Happens
Gallery → artwork (with `artist_name`)	Resolve artist → create if needed → link gallery↔artist + artwork→artist + artwork→gallery
Gallery → artist	Resolve → create if needed → link gallery↔artist
Artist → artwork (with `gallery_name`)	Link artwork→artist (auto) → resolve gallery → link if found

This means you don’t need to manage entity relationships manually — just include artist_name or gallery_name in your payloads.

Rate Limits

Rate limits are enforced per API key. See Rate Limits for details.

Response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1718800000

Error Handling

The API returns standard HTTP status codes and JSON error bodies. See Errors for the full list.