Calira (formerly Clustermarket) API (0.1.6)

Lists all accounts accessible through the integration. The application scope must include read_accounts.

Pagination: This endpoint supports pagination with a default limit of 100 records. Use page and per_page parameters to navigate through large datasets efficiently. Pagination metadata is provided in response headers (X-Total-Records, X-Current-Page, X-Per-Page).

Get the full details of a specific account. The application scope must include read_accounts.

Return lists of bookings accessible to the user, optionally scopable to the providing lab account. The application scope must include read_bookings.

Pagination: This endpoint supports pagination with a default limit of 100 records. Use page and per_page parameters to navigate through large datasets efficiently. Pagination metadata is provided in response headers (X-Total-Records, X-Current-Page, X-Per-Page).

Return the details about a particular booking as defined by the database identifier. The application scope must include read_bookings.

Upcoming / Beta notice

This write endpoint is upcoming and not yet publicly released. It is currently in testing and may not be available on all environments. Request and response shapes, validation rules, error formats, and behaviour may change without notice. Do not use in production until announced as generally available. Contact support for early access.

---

Accept or reject a booking invitation for the authenticated user.

Overview

When a booking is created for a group, each invited user receives a booking invitation. This endpoint lets the invited user respond on their own behalf. The booking ID in the path (/bookings/{id}/invitation) must be the ID of a booking where the current access-token user has an invitation.

Authorisation

Requirement	Details
OAuth scope	write_bookings
Application	Must be approved and authorised for the lab that owns the booking
Resource owner	Must be the invited user — you cannot respond to another user's invitation

A 403 Forbidden response is returned when the scope is missing, the application is not authorised for the lab, the token user is not the invitee, or the invitation cannot be acted on (for example, accepting when the invitee already has an overlapping booking on the same equipment).

Request body

Field	Required	Description
status	Yes	accept or reject
reject_reason	No	Free-text reason stored when rejecting. Ignored for accept.
request_scope	No	Controls how many occurrences are affected for recurring bookings. Default: current
accept_available	No	Boolean, default false. Only relevant when accepting with a bulk request_scope

request_scope values (recurring bookings)

• current (default) — only the invitation tied to this booking ID
• subsequent — this booking and every later occurrence in the recurrence series where the user has an invitation
• all — every occurrence in the recurrence series where the user has an invitation

For non-recurring bookings, request_scope has no practical effect beyond current.

Conflict handling (bulk accept)

When accepting with subsequent or all, the API checks whether the invitee already has overlapping confirmed bookings on the same equipment. If conflicts exist:

• With accept_available: false (default): no invitations are accepted. The response still returns HTTP 200 and includes conflicting_invitations with the affected dates/times, plus an errors array explaining the conflict.
• With accept_available: true: only non-conflicting invitations are accepted; conflicting ones are listed in conflicting_invitations.

Response

Returns the primary booking_invitation (the one for the booking ID in the path), plus:

• processed_invitations — all invitations that were successfully accepted or rejected in this request
• conflicting_invitations — invitations that could not be accepted due to scheduling conflicts (empty when there are no conflicts)

Invitation status values in responses: pending, accepted, rejected.

Errors

See Errors (Write API) for the full catalogue.

HTTP	Condition	Response
401	Missing or invalid access token	{ "error": "unauthorised", "error_description": "..." }
403	Missing write_bookings scope	{ "error": "resource_authorisation_failure", ... }
403	OAuth application not approved	{ "error": "unapproved_application", ... }
403	Application not authorised for the booking's lab	{ "error": "resource_authorisation_failure", ... }
403	Token user is not the invited user	{ "error": "resource_authorisation_failure", ... }
403	Token user has no invitation for this booking	{ "error": "resource_authorisation_failure", ... }
403	Accepting when invitee has overlapping booking on same equipment (request_scope: current)	{ "error": "resource_authorisation_failure", ... }
403	Accepting an already-accepted invitation	{ "error": "resource_authorisation_failure", ... }
404	Booking ID does not exist	{ "error": "resource_not_found", ... }
422	status omitted or not accept/reject	{ "error": "invalid_invitation_status", "error_description": "The status parameter must be either 'accept' or 'reject'." }
422	request_scope not current, subsequent, or all	{ "errors": [{ "attribute": "base", "message": "unknown request_scope: ..." }] }
200	Bulk accept blocked by conflicts (accept_available: false)	{ "errors": [{ "attribute": "base", "message": "Cannot complete action: the invitee already has overlapping bookings..." }], "conflicting_invitations": [...], "processed_invitations": [] }
429	More than 30 requests per minute per IP	HTML error page
500	Unexpected server error	{ "error": "internal_server_error", ... }

Side effects

Accepting a confirmed booking may enqueue calendar sync jobs (for example, Outlook) for the invitee. Notifications are sent to relevant parties when an invitation is responded to.

Example workflow

# Accept a single invitation
POST /bookings/12345/invitation
Authorization: Bearer <token>
Content-Type: application/json

{ "status": "accept" }

# Reject with a reason
POST /bookings/12345/invitation

{ "status": "reject", "reject_reason": "Not available that day" }

# Accept all non-conflicting occurrences in a recurring series
POST /bookings/12345/invitation

{ "status": "accept", "request_scope": "all", "accept_available": true }

Returns a submitted custom form response linked to a booking. Use this endpoint to retrieve the user-submitted answers for a booking's custom form. The application scope must include read_bookings.

Example request: GET /custom_form_responses/16

Upcoming / Beta notice

This write endpoint is upcoming and not yet publicly released. It is currently in testing and may not be available on all environments. Request and response shapes, validation rules, error formats, and behaviour may change without notice. Do not use in production until announced as generally available. Contact support for early access.

---

Registers a file for direct upload before attaching it to equipment via POST /equipment or PATCH /equipment/{id}.

Overview

Equipment photos and documents are not uploaded inline with create/update requests. Instead, use this three-step direct upload flow:

Step	Endpoint	Action
A	POST /uploads	Register upload metadata and receive signed_id + direct_upload target
B	PUT direct_upload.url	Upload the raw file bytes to cloud storage (not the Calira API)
C	POST /equipment or PATCH /equipment/{id}	Attach the signed_id from step A

The signed_id is scoped to the registering user and OAuth application. It must be used with the same credentials that registered it.

Step A — Register upload (POST /uploads)

Send file metadata (name, type, size, checksum). On success you receive:

{
  "signed_id": "eyJfcmFpbHMiOnsiZGF0YSI6MTE3OSwicHVyIjoiYmxvYl9pZCJ9fQ==--6109b8c4568a1687e0b95fc25955d4c52cae4b4e",
  "filename": "microscope.jpg",
  "content_type": "image/jpeg",
  "byte_size": 1048576,
  "purpose": "photo",
  "direct_upload": {
    "url": "https://storage.example.com/rails/active_storage/disk/...",
    "headers": {
      "Content-Type": "image/jpeg",
      "Content-MD5": "dGVzdCBjaGVja3N1bQ=="
    }
  }
}

Save signed_id for step C. Use direct_upload.url and direct_upload.headers for step B.

Step B — Upload file bytes (PUT direct_upload.url)

This step does not call the Calira API. You upload the file directly to cloud storage using the pre-signed URL returned in step A.

Requirement	Details
HTTP method	PUT (not POST)
URL	direct_upload.url from the step A response
Headers	All key/value pairs from direct_upload.headers — include them exactly as returned (typically Content-Type and Content-MD5)
Request body	Raw file bytes — not JSON, not multipart/form-data
Body size	Must match the byte_size sent in step A

Important:

• direct_upload.url is short-lived (pre-signed; expires after approximately 5 minutes by default). Complete step B promptly after step A — if the URL expires, register a new upload with POST /uploads.
• The Content-MD5 header must match the checksum you sent in step A (base64-encoded MD5 of the file).
• Do not add an Authorization header on this request — authentication is embedded in the pre-signed URL.
• Step B must succeed before you reference the signed_id in step C. If you skip step B, equipment create/update will fail with an incomplete-upload error.
• A successful upload typically returns 200 OK or 204 No Content from the storage provider (not from Calira).

# Step B example — upload file bytes to storage
curl -X PUT "https://storage.example.com/rails/active_storage/disk/..." \
  -H "Content-Type: image/jpeg" \
  -H "Content-MD5: dGVzdCBjaGVja3N1bQ==" \
  --data-binary @microscope.jpg

# Alternative: pipe file contents
curl -X PUT "https://storage.example.com/rails/active_storage/disk/..." \
  -H "Content-Type: image/jpeg" \
  -H "Content-MD5: dGVzdCBjaGVja3N1bQ==" \
  --data-binary "@/path/to/microscope.jpg"

Step C — Attach to equipment

Reference the signed_id from step A in photos or documents when creating or updating equipment. See POST /equipment or PATCH /equipment/{id}.

Authorisation

Requirement	Details
OAuth scope	write_equipment

Request body

Field	Required	Description
filename	Yes	Original file name including extension (e.g. microscope.jpg)
content_type	Yes	MIME type of the file. Must match the purpose restrictions below
byte_size	Yes	File size in bytes. Must be greater than 0
checksum	Yes	Base64-encoded MD5 digest of the file bytes
purpose	Yes	photo or document — determines allowed types and size limits

Purpose restrictions

photo

• Allowed content types: image/png, image/jpeg, image/jpg, image/svg+xml
• Maximum size: 10 MB

document

• Allowed content types: image/jpeg, image/jpg, image/png, application/pdf, application/msword, application/vnd.ms-excel, application/vnd.oasis.opendocument.spreadsheet, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.openxmlformats-officedocument.wordprocessingml.document
• Maximum size: 25 MB

Response

On success (201 Created), returns the signed_id to reference in equipment requests, plus direct_upload.url and direct_upload.headers for the file upload step.

Errors

See Errors (Write API) for the full catalogue. This endpoint does not require lab authorisation — only a valid write_equipment token.

HTTP	Condition	Response
401	Missing or invalid access token	{ "error": "unauthorised", ... }
403	Missing write_equipment scope	{ "error": "resource_authorisation_failure", ... }
403	OAuth application not approved	{ "error": "unapproved_application", ... }
422	Invalid upload metadata — see field table below	{ "success": false, "message": "The upload could not be registered...", "errors": [...] }
500	Unexpected server error	{ "error": "internal_server_error", ... }

422 field errors

attribute	When
filename	Missing or blank
content_type	Missing, blank, or not allowed for the purpose
byte_size	Missing, zero, exceeds 10 MB (photo), or exceeds 25 MB (document)
checksum	Missing or blank
purpose	Not photo or document

If you reference a signed_id on equipment create/update before uploading file bytes (step B), or after the signed ID expires, validation fails on the equipment request with a base error — register a new upload.

Example workflow (all steps)

# Step A: Register upload
POST /uploads
Authorization: Bearer <token>
Content-Type: application/json

{
  "filename": "microscope.jpg",
  "content_type": "image/jpeg",
  "byte_size": 1048576,
  "checksum": "dGVzdCBjaGVja3N1bQ==",
  "purpose": "photo"
}

# Response includes signed_id and direct_upload — save both for steps B and C

# Step B: Upload file bytes to direct_upload.url (NOT the Calira API)
curl -X PUT "<direct_upload.url from step A>" \
  -H "Content-Type: image/jpeg" \
  -H "Content-MD5: dGVzdCBjaGVja3N1bQ==" \
  --data-binary @microscope.jpg

# Step C: Create equipment with the signed_id from step A
POST /equipment
Authorization: Bearer <token>
Content-Type: application/json

{
  "account_id": 123,
  "name": "API Microscope",
  "category": "Equipment",
  "photos": ["<signed_id from step A>"]
}

Lists all equipment under the specified lab. Requires read_equipment scope.

Pagination: This endpoint supports pagination with a default limit of 100 records. Use page and per_page parameters to navigate through large datasets efficiently. Pagination metadata is provided in response headers (X-Total-Records, X-Current-Page, X-Per-Page).

Upcoming / Beta notice

This write endpoint is upcoming and not yet publicly released. It is currently in testing and may not be available on all environments. Request and response shapes, validation rules, error formats, and behaviour may change without notice. Do not use in production until announced as generally available. Contact support for early access.

---

Creates a new piece of equipment in the specified lab account.

Overview

This endpoint creates equipment atomically in a single request. You can supply general fields, pricing, booking rules, maintenance settings, contact people, group access, labels, and file attachments in one payload.

Authorisation

Requirement	Details
OAuth scope	write_equipment
Application	Must be approved and authorised for the target lab (account_id)
User	Must have permission to create equipment in that lab (typically admin or instructor)

Required fields

Field	Description
account_id	ID of the lab account where the equipment will be created
name	Display name of the equipment
category	One of: Equipment, Parent equipment, Room/Space, Desk/Bench, Other

Depending on the category, a subcategory may also be required (for example, Microscopy & Imaging when category is Equipment).

Request body

The request body schema defines every field with types, allowed values, and nested object structure. Expand the schema in the panel below or see these component schemas:

Schema	Contents
EquipmentMutableFields	All top-level fields
EquipmentPricingInput	pricing object — currency, charging, price details, advance pricing, add-ons
EquipmentBookingRulesInput	booking_rules object — min/max duration, time step, start step, advance notice, business hours
EquipmentMaintenanceInput	maintenance object — maintenance contracts
EquipmentAttachmentInput	photos and documents — signed IDs (create) or action objects (update)

Optional top-level fields (summary)

Field	Description
room	Physical location or room name
subcategory	Subcategory name matching the selected category
manufacturer	Manufacturer name
model_number	Model or catalogue number
manufacturing_year	Year of manufacture (integer or string)
serial_number	Serial number
availability_status	Always Available or Unavailable (default: Always Available)
description	Plain-text description
lab_rules	Plain-text lab-specific usage rules
safety_features	Plain-text safety information
date_of_purchase	Purchase date (ISO 8601 date string)
internal_id	Internal inventory identifier
purchase_price	Purchase price
contact_access_role_ids	Array of access role IDs for equipment contact people. Use GET /equipment/contact_people?account_id={id} to list valid IDs
group_ids	Array of group IDs that should have access
equipment_label_ids	Array of equipment label IDs
photos	Array of signed_id strings from POST /uploads with purpose: photo — see EquipmentAttachmentInput
documents	Array of signed_id strings from POST /uploads with purpose: document — see EquipmentAttachmentInput

Nested sections (summary)

See the nested schemas above for full parameter definitions. Brief overview:

pricing → EquipmentPricingInput

Enable charging, set currency (GBP, USD, …), charging_type (perHour/perDay), price_details.internal, optional advance_pricing slots, and custom_addons.

booking_rules → EquipmentBookingRulesInput

Enable constraints, set min_booking_time / max_booking_time ({ unit, duration }), time_step, start_step, advance_booking_must / advance_booking_can, and optional business_hours.

maintenance → EquipmentMaintenanceInput

Set maintenance_contract and maintenance_contract_ids.

File attachments

Photos and documents use the three-step direct upload flow:

Step	Action
A	POST /uploads — register metadata, receive signed_id and direct_upload
B	PUT direct_upload.url — upload raw file bytes to storage (see POST /uploads for full step B documentation)
C	Include signed_id in photos or documents on this request

On create, photos and documents must be arrays of signed IDs (not action objects). Step B must complete before step C.

Response

Returns 201 Created with { success: true, equipment: { ... } } containing the full equipment configuration including pricing, booking_rules, and maintenance sections.

Validation errors

Returns 422 Unprocessable Entity with field-level errors when validation fails. No equipment is created on validation failure.

See Errors (Write API) for the complete field-level catalogue.

HTTP	Condition	Response
401	Missing or invalid access token	{ "error": "unauthorised", ... }
403	Missing write_equipment scope	{ "error": "resource_authorisation_failure", ... }
403	OAuth application not approved	{ "error": "unapproved_application", ... }
403	Application not authorised for the lab	{ "error": "resource_authorisation_failure", ... }
403	User cannot create equipment in the lab	{ "error": "resource_authorisation_failure", ... }
404	account_id missing or does not exist	{ "errors": ["account_not_found"], ... }
422	Schema, attachment, or business-rule validation failed	{ "success": false, "message": "Equipment could not be created...", "errors": [...] }
500	Unexpected server error	{ "error": "internal_server_error", ... }

Common 422 causes: missing account_id/name/category; invalid subcategory, availability_status, or contact_access_role_ids; unsupported pricing/booking_rules values; invalid or incomplete photos/documents signed_id references (see upload flow).

Upcoming / Beta notice

This write endpoint is upcoming and not yet publicly released. It is currently in testing and may not be available on all environments. Request and response shapes, validation rules, error formats, and behaviour may change without notice. Do not use in production until announced as generally available. Contact support for early access.

---

Returns access roles that may be assigned as equipment contact people for a lab. Use the returned id values in contact_access_role_ids when creating or updating equipment.

When to call

Scenario	Parameters
Creating new equipment	account_id only — returns lab admins and instructors
Updating existing equipment	account_id + equipment_id — also includes instructors assigned to that equipment

Authorisation

Requirement	Details
OAuth scope	write_equipment
Application	Must be approved and authorised for the lab (account_id)
User	Must have permission to create equipment (no equipment_id) or update the equipment (with equipment_id)

Response

Returns { "contact_access_roles": [ ... ] } where each item includes id, user_id, account_id, name, email, and role (admin or instructor).

Errors

See Errors (Write API) for the full catalogue.

HTTP	Condition	Response
401	Missing or invalid access token	{ "error": "unauthorised", ... }
403	Missing write_equipment scope	{ "error": "resource_authorisation_failure", ... }
403	OAuth application not approved	{ "error": "unapproved_application", ... }
403	Application not authorised for the lab	{ "error": "resource_authorisation_failure", ... }
403	User cannot create equipment in the lab (no equipment_id; e.g. guest)	{ "error": "resource_authorisation_failure", ... }
403	User cannot update the equipment (with equipment_id)	{ "error": "resource_authorisation_failure", ... }
404	account_id query parameter omitted	{ "errors": ["not_found"], "error_messages": "No lab, account, or equipment was found..." }
404	account_id or equipment_id does not exist	{ "errors": ["not_found"], "error_messages": "No lab, account, or equipment was found..." }
500	Unexpected server error	{ "error": "internal_server_error", ... }

Returns details about a particular piece of equipment. Requires the equipment ID, and the application scope must include read_equipment.

Upcoming / Beta notice

This write endpoint is upcoming and not yet publicly released. It is currently in testing and may not be available on all environments. Request and response shapes, validation rules, error formats, and behaviour may change without notice. Do not use in production until announced as generally available. Contact support for early access.

---

Updates an existing piece of equipment. Send only the fields you want to change — this is a partial update.

Overview

At least one updatable field must be present in the request body. An empty body returns 422 Unprocessable Entity.

Any field documented for create (except account_id) can be updated, including nested pricing, booking_rules, and maintenance sections.

See the Request body schema (EquipmentUpdateRequest → EquipmentMutableFields and nested schemas) for the full parameter reference including EquipmentAttachmentInput action objects for photos and documents.

Authorisation

Requirement	Details
OAuth scope	write_equipment
Application	Must be approved and authorised for the lab that owns the equipment
User	Must have permission to update the equipment

Updating file attachments

Unlike create, photos and documents on update use an action object (not a plain array):

Action	signed_ids required	Effect
extend	Yes	Add new attachments alongside existing ones
replace	Yes	Remove all existing attachments of that type and attach the given signed IDs
remove	Yes	Remove only the attachments matching the given signed IDs
destroy	No	Remove all attachments of that type

Each signed_id must be registered via POST /uploads (step A) and file bytes uploaded via step B before use.

Response

Returns 200 OK with { success: true, message: "Equipment was updated.", equipment: { ... } }.

Validation errors

Returns 422 Unprocessable Entity with field-level errors when validation fails. No partial updates are applied when validation fails.

See Errors (Write API) for the complete field-level catalogue.

HTTP	Condition	Response
401	Missing or invalid access token	{ "error": "unauthorised", ... }
403	Missing write_equipment scope	{ "error": "resource_authorisation_failure", ... }
403	OAuth application not approved	{ "error": "unapproved_application", ... }
403	Application not authorised for the lab	{ "error": "resource_authorisation_failure", ... }
403	User cannot update the equipment	{ "error": "resource_authorisation_failure", ... }
404	Equipment ID in URL does not exist	{ "errors": ["equipment_not_found"], ... }
422	Empty body, schema, attachment, or business-rule validation failed	{ "success": false, "message": "Equipment could not be updated...", "errors": [...] }
500	Unexpected server error	{ "error": "internal_server_error", ... }

Common 422 causes: empty request body; invalid field values; unsupported photos/documents action; missing signed_ids for extend/replace/remove; unknown signed_id; attachment not on equipment; incomplete upload (step B not done).

Returns bookings about a particular piece of equipment. Requires the equipment ID, and the application scope must include read_equipment.

Pagination: This endpoint supports pagination with a default limit of 100 records. Use page and per_page parameters to navigate through large datasets efficiently. Pagination metadata is provided in response headers (X-Total-Records, X-Current-Page, X-Per-Page).