Events

Endpoints for managing public events — exhibitions, openings, talks, and workshops.

Create or Update Event

POST /v1/events

Create a new event or update an existing one (matched by normalized slug from title + gallery).

Required scope: events:write

Request Body

Field	Type	Required	Description
`title`	string	✅	Event title
`event_type`	string		`exhibition`, `opening`, `talk`, `workshop`, `other`
`description`	string		Event description
`location_city`	string		City name
`location_country`	string		ISO country code (e.g., “CH”, “DE”)
`start_date`	string		ISO date (e.g., “2026-04-15”)
`end_date`	string		ISO date (e.g., “2026-05-30”)
`external_url`	string		Link to the event on your website
`image_url`	string		Permanent URL to the event hero image
`ical_url`	string		URL to an iCalendar (.ics) file

Deduplication

Events use normalized_slug derived from the title and gallery ID. Re-posting the same event updates the existing record.

Example

curl -X POST https://api.artland.com/v1/events \
  -H "Authorization: Bearer ak_liv...re" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Spring Exhibition",
    "event_type": "exhibition",
    "description": "Annual spring group show featuring emerging artists.",
    "location_city": "Zurich",
    "location_country": "CH",
    "start_date": "2026-04-15",
    "end_date": "2026-05-30",
    "external_url": "https://gallery.example.com/spring-2026",
    "image_url": "https://gallery.example.com/spring-hero.jpg",
    "ical_url": "https://gallery.example.com/calendar.ics"
  }'

Response (201):

{
  "id": 7,
  "title": "Spring Exhibition",
  "slug": "spring-exhibition",
  "created": true
}

List Events

GET /v1/events

List events for the entity bound to your API key.

Required scope: events:read

Query Parameters

Parameter	Default	Description
`page`	1	Page number
`limit`	50	Results per page
`upcoming`	false	Only return future events
`past`	false	Only return past events

Example

curl "https://api.artland.com/v1/events?upcoming=true" \
  -H "Authorization: Bearer ak_liv...n**Response (200):**
```json
{
  "events": [
    {
      "id": 7,
      "title": "Spring Exhibition",
      "event_type": "exhibition",
      "location_city": "Zurich",
      "location_country": "CH",
      "start_date": "2026-04-15",
      "end_date": "2026-05-30"
    }
  ],
  "total": 3,
  "page": 1,
  "limit": 50
}

Get Event

GET /v1/events/:id

Retrieve a single event by ID.

Required scope: events:read

Example

curl https://api.artland.com/v1/events/7 \
  -H "Authorization: Bearer ak_liv...n**Response (200):**
```json
{
  "id": 7,
  "title": "Spring Exhibition",
  "event_type": "exhibition",
  "description": "Annual spring group show featuring emerging artists.",
  "location_city": "Zurich",
  "location_country": "CH",
  "start_date": "2026-04-15",
  "end_date": "2026-05-30",
  "external_url": "https://gallery.example.com/spring-2026",
  "image_url": "https://gallery.example.com/spring-hero.jpg",
  "ical_url": "https://gallery.example.com/calendar.ics"
}

Delete Event

DELETE /v1/events/:id

Remove an event. You must own the event via entity binding.

Required scope: events:write

Example

curl -X DELETE https://api.artland.com/v1/events/7 \
  -H "Authorization: Bearer ak_liv...n**Response (200):**
```json
{
  "deleted": true,
  "id": 7
}