Integrations API

Colabmacs7/7/26About 3 min

Integrations API

Colabmacs includes a basic public API for trusted integrations.

This API is intended for controlled operational workflows such as:

creating training records from an external training process
reading resource information for reporting or synchronization
reading infrastructure information for status-aware integrations
reading usage records for downstream analysis or billing support

It is not intended to replace the main Colabmacs user interface. Instead, it provides a stable way to connect a small set of external systems to core operational data.

What This API Is For

The integrations API is best suited to cases where another approved system needs to:

push completed training outcomes into Colabmacs
read resource or infrastructure inventories
read usage history for exports, reporting, or data warehousing

Typical examples include:

importing completion data from an external learning or compliance workflow
syncing resource metadata into a signage, reporting, or monitoring tool
pulling usage records into a finance, BI, or analytics process

Access Requirements

To use the integrations API, the person creating the token must have:

view api tokens to access the API token management page
the underlying application permissions required by the target endpoint

For example:

a token used to create training records should be created by someone who can create training records
a token used to read resources should be created by someone who can view resources
a token used to read usage records should be created by someone who can view usage records

Info

API tokens are managed from the user-facing API Tokens settings page, not from the Admin section.

Creating an API Token

An admin or integration owner can create a token from their account settings and choose the permissions that token should have.

The available token permissions currently include:

Token Permission	Use
`training-records:create`	Create training records through the integrations API
`resources:read`	Read public resource data
`infrastructures:read`	Read public infrastructure data
`usage-records:read`	Read usage record data
`calendar:read`	Access generated calendar feeds

Recommended practice:

create a separate token for each integration
give each token only the permissions it needs
use descriptive token names such as lms-training-import or bi-usage-export
expire or delete tokens that are no longer needed

Authentication

The integrations API uses Bearer token authentication.

Requests must include an Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

If the request does not use a bearer token, the API rejects it.

Current Endpoints

All endpoints are from the base: https://your.colabmacs.app/api/public

The current integrations API supports:

creating training records
reading resources
reading infrastructure
reading usage records

Create Training Records

Use this endpoint when an approved external workflow needs to mark one or more users as having completed a training.

Endpoint

POST /v1/training-records/create

Required token permission

training-records:create

Supported fields

Field	Required	Notes
`training_id`	Yes	Training to apply
`user_id[]`	Sometimes	Required when no session or event is supplied
`trainer_id`	No	Trainer user ID
`trainer_email`	No	Alternate way to identify the trainer
`training_session_id`	No	Associate records with a training session
`event_id`	No	Associate records with an event-backed session
`request_id`	No	Associate the record creation with an existing request

Behavior notes:

if a valid training session is supplied, Colabmacs can derive the users from that session
if no session is supplied, at least one user_id must be included
API-created records are audited with the access token that created them

Example:

curl -X POST https://your-colabmacs.example/api/public/v1/training-records/create \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json" \
  -d "training_id=TRAINING_UUID" \
  -d "user_id[]=USER_UUID"

Read Resources

Use this endpoint to read public resource information.

Endpoint

GET /v1/resources

Required token permission

resources:read

Common filters

Filter	Notes
`id[]`	Filter by one or more resource IDs
`location_id[]`	Filter by location
`resource_type_id[]`	Filter by resource type
`process_area_id[]`	Filter by process area
`tag_id[]`	Filter by tag
`state[]`	Filter by resource state
`search`	Search by name or description
`with[]`	Include `location`, `type`, `processAreas`, `tags`, or `infrastructure`
`itemsPerPage`	Up to 300 records per page

Read Infrastructure

Use this endpoint to read infrastructure records and dependency relationships.

Endpoint

GET /v1/infrastructures

Required token permission

infrastructures:read

Common filters

Filter	Notes
`id[]`	Filter by one or more infrastructure IDs
`resource_id[]`	Filter infrastructure attached to resources
`location_id[]`	Filter by location
`state[]`	Filter by infrastructure state
`search`	Search by name or description
`with[]`	Include `resources`, `dependencies`, `dependants`, or `locations`
`itemsPerPage`	Up to 300 records per page

Read Usage Records

Use this endpoint to export or analyze recorded usage activity.

Endpoint

GET /v1/usage-records

Required token permission

usage-records:read

Common filters

Filter	Notes
`id[]`	Filter by usage record ID
`usable_id[]`	Filter by the billed or tracked object
`usable_type[]`	Used with `usable_id[]` to identify the object type
`user_id[]`	Filter by user
`event_id[]`	Filter by event
`project_id[]`	Filter by project
`request_id[]`	Filter by related request
`start_date` / `end_date`	Filter by created date
`search`	Search by user, project, usable name, or quantity
`with[]`	Include `user`, `project`, `event`, `usable`, `usageSession`, `charge`, or `tags`
`sortBy[]`	Sort by supported columns such as `created_at` or `qty`
`itemsPerPage`	Up to 500 records per page

Warning

Large usage-record queries can be rejected if too many relationships are requested together with a large page size. If that happens, reduce itemsPerPage or request fewer related models in with[].

Operational Guidance

When setting up integrations:

create one token per integration
document who owns each token and what it is used for
review token permissions periodically
expire or delete tokens when an integration is retired
keep training-record integrations limited to approved operational workflows

For most facilities, API tokens should be treated like service credentials and controlled as carefully as any other privileged system secret.