Public API

The Public API is the REST API behind the Hub and the fun CLI: one API, with one token, to manage your fleet, your data, your alerts and who has access. This page gives the base URL, how to authenticate, where to find the OpenAPI specs, and a map of the operations by domain.

Base URL and versions

Item	Value
Base URL	`https://api.fundamentum-iot.com`
v1	Paths under `/v1/projects/{projectId}/...`: devices and fleets, data routing, alerts
v2	Paths under `/v2/...`: organizations, projects, access control, registries, functions, Insight, licenses

Both versions are current and complementary: each domain lives in one of them. Use the same token for both.

Authentication

Send an OAuth2 bearer token on every request:

GET /v2/users/introspect HTTP/1.1
Host: api.fundamentum-iot.com
Authorization: Bearer $TOKEN

The token is either a user token (from fun login or your own OAuth client) or a service-account token for integrations. See Authentication.

A 401 means the token is missing, expired or for another environment. A 403 with a valid token means your role lacks the permission. Device credentials (device JWT, provisioning key) are never accepted here.

OpenAPI specs and Swagger UI

Version	Spec	Swagger UI
v1	`/v1/api/swagger.json` (also `/v1/openapi.yaml`)	Swagger UI v1
v2	`/v2/api/openapi.json` (also `/v2/openapi.json` and `/v2/openapi.yaml`)	Swagger UI v2

Each area below links to its section in Swagger UI, where you can sign in and try requests. Both specs are OpenAPI 3.1. They are the reference for every field, parameter and response; this page only summarizes them.

Domains

Devices and fleets

Area	Swagger UI	Main paths
Devices	v1 · Device	`devices`, `devices/summaries`, `devices/{deviceId}/authentication`
States	v1 · Device	`devices/{deviceId}/states`, `last-states`, `state-types`
Heartbeats	v1 · Heartbeat	`devices/{deviceId}/heartbeats`, `last-heartbeats`, `registries/{registryId}/heartbeats`, `heartbeats`, `device-types/{deviceTypeId}/heartbeats/config`
Device types and firmware	v1 · Device Type	`device-types`, `device-types/{deviceTypeId}/versions` (a version is a firmware release), `versions/{versionId}/files`
Commands	v1 · Commands	`device/{deviceId}/commands/{shortName}`, `registries/{registryId}/batch-commands` (batches and their report)
Actions	v1 · Action	`action-types`, `registries/{registryId}/actions`, `actions/{actionId}:cancel`, `:retry`, `devices/{deviceId}/actions`
Capabilities and encoders	v1 · Capability	`capabilities`, `capabilities/{capabilityId}/encoders`, `encoders`, `encoder-protocols`
File transfers	v1 · FileTransfers	`transfers`, `transfers/{transferId}/files`, `history`, `:execute`, `:cancel`
Registries	v1	`registries`, `registries/{registryId}/topics`, `registries/{registryId}/configuration`

Remote terminal and port forwarding are available from the Hub and the fun CLI. They are not part of the published specs. See Remote terminal and port forwarding.

Data

Area	Swagger UI	Main paths
Topics	v1 · PubSub	`pub-sub-topics`, `pub-sub-topics/scopeable`, `pub-sub-topics/{scopeableTopic}/scoped`
Connectors	v1 · PubSub	`connectors`, `connectors/{connectorId}/links`, `connectors/{connectorId}/status`
Inbound HTTPS messages	v1 · PubSub	`POST connectors/{connectorId}/links/{linkId}/publish`
Cloud functions	v2 · Functions	`/v2/projects/{project_id}/functions`, `executions`, `file` (upload), `:invoke`
Insight	v2 · Insight	`/v2/projects/{project_id}/instances`, pipelines (`:submit`, `:cancel`), tables, users

See Topics, Connectors, Inbound flows, Cloud functions and Query your data with Insight.

Alerts

Area	Swagger UI	Main paths
Alert rules and alerts	v1 · Alert	`alert-rules`, `alert-rules/{alertRuleId}/alerts`, `devices/{deviceId}/alerts`, `alerts/{alertId}:resolve`
Notifications	v2 · Projects: Alert Notifier	`/v2/projects/{project_id}/alert-rules/{alert_rule_id}/notifiers`
Notifiable users	v1 · Alert	`notifiable`

See Alerts.

Governance

Area	Swagger UI	Main paths
Organizations	v2 · Organizations	`/v2/organizations`
Projects	v2 · Projects	`/v2/organizations/{organization_id}/projects`
Registries	v2	`/v2/projects/{project_id}/registries`, `registries/{registry_id}/device_types` (quotas), `registries/{registry_id}/topics`
Users and invitations	v2 · Projects: Users/Invitations	`/v2/projects/{project_id}/users`
Roles and permissions	v2 · Authorization: Containers	`/v2/projects/{project_id}/containers`, with their `actions`, `roles` and `permissions`
Service accounts	v2 · Service Accounts	`/v2/projects/{project_id}/service-accounts`, with roles and tokens
Licenses	v2 · Licenses	`/v2/projects/{project_id}/licenses`, license and site users
Feature flags	v2 · Features Flags	`/v2/projects/{project_id}/features/{code}`
Current user	v2 · Users	`GET /v2/users/introspect`

A registry created through v2 takes a name and a provisioning window (provisioning_start_at, provisioning_end_at, RFC 3339 timestamps). Devices can be provisioned into it only inside that window. Its quotas, the number of devices of each device type that may be provisioned into it, are set with POST /v2/projects/{project_id}/registries/{registry_id}/device_types:

{
  "ids": {
    "<device-type-id>": { "provisioning_quantity": 100 }
  }
}

See Licenses and Roles and permissions.

Call the API

With the fun CLI, every operation is available as fun api <version> <group> <operation>:

fun api refresh
fun api v1 device list-devices --project-id <project-id> --data-only
fun api v2 registries list-registries --project-id <project-id>

With curl:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.fundamentum-iot.com/v1/projects/<project-id>/devices?page=1&item_per_page=25"

Responses, errors, pagination and filters follow the Conventions.

Generate a client

Point any OpenAPI 3.1 generator at the spec URL. For example, with OpenAPI Generator:

curl -o fundamentum-v2.json https://api.fundamentum-iot.com/v2/api/openapi.json
openapi-generator-cli generate -i fundamentum-v2.json -g python -o ./fundamentum-client

Generate one client per version, or merge them in your build. Configure the client to send Authorization: Bearer <token>.