Artwork API
Read Artwork data from other programs with an API key – access, permissions, endpoints for room occupancy and inventory
The Artwork API lets other programs read data from Artwork, for example an
annual planning tool that needs to know which rooms are occupied. The API is
versioned (/api/v1) and always responds with JSON. Each program needs its own
API key with the matching permissions.
Setting up access
- Open the tool settings, tab Interfaces, section Artwork interface.
- Create a key with a descriptive name (e.g. the name of the connected program) and select only the permissions the program needs.
- Set an expiry date if needed. A key is valid for one year at most.
- Copy the key immediately into the protected secret store of the connected program. It is shown only once.
The program sends the key with every request in the header
Authorization: Bearer <key>.
| Permission | Allows |
|---|---|
calendar:read | Read rooms, areas, events and event statuses (room occupancy) |
inventory:read | Read inventory categories and articles (inventory) |
ticketing:read, ticketing:write | Reserved for the Artwork ticket shop |
All permissions are read-only except ticketing:write. A key cannot retrieve
any other data or change anything in Artwork.
Rotating keys
To rotate a key, create a second one, switch the program over, then revoke the old key. Both keys work in parallel in the meantime. A revoked or expired key is rejected immediately.
Basic rules
- HTTPS only; all responses as JSON (UTF-8), errors included.
- At most 120 requests per minute per key.
- Timestamps in ISO 8601 with time zone, e.g.
2027-03-01T15:00:00+01:00. - IDs never change, even when a room or project is renamed.
- Existing fields are never renamed or removed. New fields may be added; connected programs should ignore unknown fields.
| Code | Meaning |
|---|---|
200 | Success, also for an empty list |
400 | Parameter missing or invalid; errors names the parameter |
401 | Key missing, wrong, expired or revoked |
403 | Key lacks the required permission |
429 | Too many requests; retry after the seconds given in the Retry-After header |
5xx | Artwork error |
Errors contain a readable message in message.
Room occupancy (calendar:read)
Which room is occupied by which project, and when? Room occupancy provides the rooms, the events in them and the event statuses.
Rooms: GET /api/v1/rooms
All rooms not in the recycle bin with id, name, area (area_id,
area_name), room categories, capacity, colour and the details of temporary
rooms. Use areas=3,4 to get the rooms of specific areas.
Events: GET /api/v1/events
| Parameter | Required | Meaning |
|---|---|---|
from | yes | First day (YYYY-MM-DD) |
to | yes | Last day, inclusive; at most three years after from |
rooms | no | Room IDs, e.g. rooms=31,32 |
areas | no | Area IDs; combined with rooms, both apply (the rooms and all rooms of the areas) |
updated_since | no | Only events changed or deleted since this point in time |
page, per_page | no | Page and events per page (default 500, at most 1000) |
Every event with a room that touches the period is returned with its real start and end times. Each event contains, among others:
id,title(project name; without a project the event name or event type),project_id,project_name,event_typeroom_id,room_name,area_id,area_namestartandendas timestamps (end= the room is free from then on),all_day,start_dateandend_date(first and last calendar day, inclusive)status(event status) androom_request_pending(open room request)series_idfor event series,updated_at,deleted_at
Not included: planning events, events without a room, events in rooms in the
recycle bin, and personal data, descriptions and comments. Deleted events only
appear in requests with updated_since, with deleted_at set.
Longer lists are split into pages: links.next holds the address of the next
page and is empty on the last page. A request without updated_since always
returns the complete current state.
Event statuses: GET /api/v1/event-statuses
All event statuses with id, name, color, order and default, plus
status_enabled. The id matches status.id on the events. This lets a
connected program decide which statuses count as occupied. If event statuses
are switched off in the event settings,
status_enabled is false and events have no status.
Inventory (inventory:read)
| Endpoint | Content |
|---|---|
GET /api/v1/inventory | Inventory categories, paginated (per_page at most 100) |
GET /api/v1/inventory/articles | Articles, filterable with search, category_id, subcategory_id |
GET /api/v1/inventory/articles/{id} | One article with properties, images and quantities |
Last updated on