Calira (formerly Clustermarket) API (0.1.7)

Account

An account in Calira (formerly Clustermarket) represents an organisation, department, or lab. We have a hierarchical structure following these rules:

• An organisation can have many departments and many labs.
• A department can only have labs.
• A lab can exist by itself, without a department or organisation. We refer to these as independent labs.

graph TD
    org[Organisation]
    org-->lab0[Lab]
    dep1[Department]
    dep2[Department]
    org-->dep1
    dep1-->lab1[Lab]
    dep1-->lab2[Lab]
    org-->dep2
    dep2-->lab3[Lab]
    il[Independent Lab]

Pagination

All endpoints in the Calira (formerly Clustermarket) API support pagination to efficiently handle large datasets. The API uses a custom pagination system with header-based metadata.

Default Behavior

• A maximum of 100 records are returned per request if no pagination parameters are specified
• Page 1 is returned by default

Pagination Parameters

• page: The page number to retrieve (1-based indexing, default: 1)
• per_page: Number of records per page (1-100, default: 100, maximum: 100)

Pagination Headers

The API provides pagination metadata in response headers:

• X-Total-Records: Total number of records available
• X-Current-Page: Current page number
• X-Per-Page: Number of records per page

Pagination Usage Examples

Basic Pagination

# Get first page (default behavior)
GET /equipment?account=123
# Headers: X-Total-Records: 250, X-Current-Page: 1, X-Per-Page: 100

# Get first page with 50 records
GET /equipment?account=123&per_page=50
# Headers: X-Total-Records: 250, X-Current-Page: 1, X-Per-Page: 50

# Get second page with 50 records
GET /equipment?account=123&per_page=50&page=2
# Headers: X-Total-Records: 250, X-Current-Page: 2, X-Per-Page: 50

# Get third page with 25 records
GET /equipment?account=123&per_page=25&page=3
# Headers: X-Total-Records: 250, X-Current-Page: 3, X-Per-Page: 25

Retrieving All Records

# Example: Get all equipment by iterating through pages
# Page 1: GET /equipment?account=123&per_page=100&page=1
# Page 2: GET /equipment?account=123&per_page=100&page=2
# Page 3: GET /equipment?account=123&per_page=100&page=3
# Continue until X-Current-Page * X-Per-Page >= X-Total-Records

Performance Considerations

• Default behavior: When no pagination parameters are provided, the API returns page 1 with up to 100 records
• Large datasets: For datasets with more than 100 records, you must use pagination parameters to retrieve additional pages
• Recommended approach: Use reasonable page sizes (25-100 records) for optimal performance
• For large datasets: Implement proper pagination logic in your application to retrieve all records
• Rate limiting: Be mindful of API rate limits when making multiple paginated requests

Pagination Response Format

• JSON Response: Simple array of records (no pagination metadata in JSON)
• Headers: Pagination metadata is provided in response headers
• Ordering: Records are ordered by creation date (most recent first)
• Authorization: Pagination respects authorization policies

Write API errors

Complete error reference for all write endpoints. Each endpoint section below also repeats its relevant errors.

Shared error formats

OAuth / authorisation — { "error": "<code>", "error_description": "<message>" }

Rate limiting (write endpoints)

All write endpoints are throttled per client IP address:

Limits are enforced independently per endpoint path (each row above has its own 30/minute bucket per IP). Exceeding a limit returns HTTP 429 Too Many Requests with an HTML error page. Retry with exponential backoff.

Equipment resource not found — { "errors": ["<code>"], "error_messages": "<message>" }

Validation — { "success": false, "message": "...", "errors": [{ "attribute": "...", "message": "..." }], "error_messages": ["..."] } on 422

Booking helper endpoints — { "errors": ["<code>"], "error_messages": ["<message>"] }

Used by GET /equipment_available_slots/{equipment_id}, GET /equipment/{id}/booking_add_ons, GET /equipment/{id}/users, GET /users/{id}, and POST /bookings/search. errors holds a stable machine-readable code; error_messages holds the matching human-readable explanation. Each endpoint section lists its codes.

Manage booking — { "error": "<code>", "error_description": "<message>" }, used by POST /bookings/{id}/manage.

Booking notes — { "success": null | false, "message": "...", "booking_id": null, "booking_note": null, "errors": [...], "error_messages": [...] }, used by /booking/notes/{id}.

POST /bookings/{id}/invitation

POST /uploads

Does not require lab authorisation — only a valid write_equipment or write_bookings token.

GET /equipment/contact_people

POST /equipment and PATCH /equipment/{id}

HTTP-level errors

422 attachment errors (create and update)

422 model / business-rule errors (create and update)

POST /equipment_training/{user_id} and DELETE /equipment_training/{user_id}

A missing or invalid token, a missing write_equipment scope, or an unapproved application uses the OAuth error body { "error": "<code>", "error_description": "<message>" }.

Training failures use { "success": false, "message": "...", "user_id": null, "trained_equipment": null, "errors": [{ "attribute": "...", "code": "...", "message": "...", "equipment_ids": [1001] }], "error_messages": ["..."] }. Nothing is written when the request fails. equipment_ids is omitted when the failure is not about particular equipment. A body that cannot be read (trained_equipment missing or empty, or an unsupported field) is 422 and those errors entries have no code.

POST /bookings and PATCH /bookings/{id}

HTTP-level errors

422 schema errors (update)

403 business-rule errors (create and update)

Returned when schema validation passes but equipment booking rules reject the request. The errors and error_messages arrays contain human-readable strings (not attribute objects). Common causes include:

• Equipment already booked during the requested time
• Booking would exceed personal or group usage limits
• Booking violates minimum/maximum duration or advance-notice rules on the equipment
• Booking falls outside permitted business hours or usage schedule
• User lacks permission to book the equipment at the requested time

422 time errors (create and update)

Projects, participants, recurrence, add-ons, and booking on behalf of (create and update)

These failures use the booking write body (success, message, booking: null, errors, error_messages). errors and error_messages both contain the message below.

POST /bookings/{id}/manage

/booking/notes/{id}

Booking Write API

The following booking write endpoints are available:

• POST /bookings — create a booking
• PATCH /bookings/{id} — update a booking