Calira (formerly Clustermarket) logo
API docs by Redocly

Calira (formerly Clustermarket) API (0.1.5)

Download OpenAPI specification:

Support: support@clustermarket.com URL: https://www.clustermarket.com/support License: Proprietary Terms of Service

Important Concepts

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

accounts

Accounts represent Organisations, Departments or Labs

List Accounts

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).

Authorizations:
oauth
query Parameters
page
integer >= 1
Default: 1

Page number (1-based indexing, default: 1)

per_page
integer [ 1 .. 100 ]
Default: 100

Number of records per page (1-100, default: 100, max: 100)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Account Details

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

Authorizations:
oauth
path Parameters
id
required
integer

Account ID

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "Cambridge Graphene Center",
  • "account_type": "lab",
  • "sector": "academia",
  • "description": "string",
  • "website": "https://www.graphene.cam.ac.uk/",
  • "timezone": "Europe/London",
  • "department": {
    },
  • "organisation": {
    },
  • "labs": [
    ],
  • "departments": [
    ]
}

bookings

A booking made on an equipment.

List Bookings

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).

Authorizations:
oauth
query Parameters
provider_account
number

The parent lab account ID.

page
integer >= 1
Default: 1

Page number (1-based indexing, default: 1)

per_page
integer [ 1 .. 100 ]
Default: 100

Number of records per page (1-100, default: 100, max: 100)

Responses

Response samples

Content type
application/json

Example response showing multiple bookings

[
  • {
    },
  • {
    },
  • {
    }
]

Booking Details

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

Authorizations:
oauth
path Parameters
id
required
integer

Booking ID

Responses

Response samples

Content type
application/json

Example response showing all booking information

{
  • "id": 12345,
  • "cost": "150.00",
  • "currency": "USD",
  • "charging_type": "Per Hour",
  • "start_time": "2024-01-15T09:00:00.000Z",
  • "end_time": "2024-01-15T11:00:00.000Z",
  • "requested_at": "2024-01-10T14:30:00.000Z",
  • "booking_type": "internal",
  • "status": "Confirmed",
  • "duration": 120,
  • "add_ons": "Data analysis service included",
  • "requester_group": {
    },
  • "equipment": {
    },
  • "requester_lab": {
    },
  • "requester_organisation": {
    },
  • "provider_lab": {
    },
  • "provider_organisation": {
    },
  • "creator": {
    },
  • "requester": {
    },
  • "last_public_note": {
    }
}

equipment

A piece of equipment. Ex: Microscope.

List Equipment

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).

Authorizations:
oauth
query Parameters
account
number

The target lab account ID

exclude_parents
boolean
Default: false

When true, only child equipment will be returned (no parent equipment)

page
integer >= 1
Default: 1

Page number (1-based indexing, default: 1)

per_page
integer [ 1 .. 100 ]
Default: 100

Number of records per page (1-100, default: 100, max: 100)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Equipment Details

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

Authorizations:
oauth
path Parameters
id
required
integer

Equipment ID

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "room": "string",
  • "manufacturer": "string",
  • "model": "string",
  • "city": "string",
  • "country": "string",
  • "currency": "string",
  • "charging_type": "string",
  • "description": "string",
  • "category": {
    },
  • "lab": {
    },
  • "image_urls": [],
  • "parent_id": 0,
  • "parent_name": "string",
  • "manufacturing_year": "string",
  • "serial_number": "string"
}

Equipment Bookings

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).

Authorizations:
oauth
path Parameters
id
required
integer

Unique ID of the equipment

query Parameters
page
integer >= 1
Default: 1

Page number (1-based indexing, default: 1)

per_page
integer [ 1 .. 100 ]
Default: 100

Number of records per page (1-100, default: 100, max: 100)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

user

A registered user on the platform

User Resource Owner

Outputs user information when the credential resource owner is a user.

Authorizations:
oauth

Responses

Response samples

Content type
{
  • "id": 0,
  • "first_name": "string",
  • "last_name": "string"
}

projects

Projects within an account

List Projects

Lists all projects under the specified account. Requires read_projects 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).

Authorizations:
oauth
path Parameters
account_id
required
integer

Account ID

query Parameters
page
integer >= 1
Default: 1

Page number (1-based indexing, default: 1)

per_page
integer [ 1 .. 100 ]
Default: 100

Number of records per page (1-100, default: 100, max: 100)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Project Details

Get the full details of a specific project. Requires read_projects scope.

Authorizations:
oauth
path Parameters
account_id
required
integer

Account ID

id
required
integer

Project ID

Responses

Response samples

Content type
application/json
{
  • "name": "Project 31",
  • "supervisor": "Niklas",
  • "additional_information": null,
  • "funding_codes": [
    ],
  • "selected_users": [ ]
}

groups

List Groups

Lists all groups under the specified lab. Requires read_accounts 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).

Authorizations:
oauth
query Parameters
account
number

The target lab account ID

page
integer >= 1
Default: 1

Page number (1-based indexing, default: 1)

per_page
integer [ 1 .. 100 ]
Default: 100

Number of records per page (1-100, default: 100, max: 100)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Group Details

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

Authorizations:
oauth
path Parameters
id
required
integer

Group ID

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "equipment": [
    ]
}