Introduction

Cloud

The Cogniteam Cloud Platform provides a robust RESTful API gateway, optimized for fleet-level monitoring and management of robotic systems.

While not designed for real-time operation, the API is perfect for retrieving metric data, accessing robot information, and monitoring sensory data streams from ROS and ROS2 environments. It also supports sending commands and accessing fleet-wide data streams, offering comprehensive insights into robotic performance and behavior.

With built-in rate limits, the API ensures stable and efficient usage, making it an ideal tool for non-real-time applications such as fleet monitoring, status tracking, and operational oversight across diverse robotic deployments.

API Gateway V2 is the latest version of the Cogniteam Cloud Platform REST API. It replaces the Protobuf-based V1 interface with native JSON models, making integration simpler across any language or platform.

Base URL

• Global: https://api.cognimbus.com/apigateway/v2
• Asia region: https://api.ap1.cognimbus.com/apigateway/v2

What's New in V2

• Native JSON request/response models (no Protobuf dependency)
• Polymorphic metric types using JSON type discriminators
• Stream upload support
• Robot resource listing and pre-signed download URLs
• Event log ingestion
• Fleet Custom KPI WebSocket for live KPI updates across fleet members

Authentication

All endpoints (except /auth/login) require a Bearer token in the Authorization header. See Authentication for details.

Local

The Local API Gateway is an agent-hosted REST and WebSocket API for applications that run on the same network as an edge device. It exposes the same API model as the cloud, so local tools can log in, list robots, read metrics, list resources, submit event logs, read and write stream data, connect to live robot streams, and subscribe to local-fleet Custom KPI updates — without going through the Cogniteam cloud.

Examples on these pages use:

http://<agent-host>:19992

Replace that base URL with the HTTP or HTTPS address of the local agent you are connecting to. HTTP does not encrypt credentials or payloads; use it only on a trusted network. Prefer HTTPS on an untrusted network and configure clients to trust the Agent certificate.

API Prefix

All Local API Gateway endpoints use this prefix:

/apigateway/v2

For example:

GET /apigateway/v2/robots

Canonical robot routes use the same plural /robots form as the Cloud API. Current agents also accept the older singular /robot form as a compatibility alias.

Local Scope

• The API is served by the agent on the robot or local fleet node.
• It is intended for local applications, scripts, tests, and offline workflows.
• It does not proxy the Cogniteam cloud backend.
• Tokens are local to the agent process and are lost when the agent restarts.
• Requests for configured local-fleet member robots can be proxied to the member agent for normal REST calls.
• Robot-scoped live WebSocket stream tunneling to local-fleet members is not currently supported.
• The fleet-level Custom KPI WebSocket runs on the fleet manager agent and publishes Custom KPI batches received from configured local-fleet members.

Authentication

When NoAuthentication is false, all routes except /auth/login require a bearer token:

{
  "authorization": "bearer <local-api-gateway-token>"
}

First call POST /apigateway/v2/auth/login with the local agent token or password to receive a local bearer token. See Authentication for details.

Browser WebSocket clients cannot set an Authorization header. For approved Local API Gateway WebSocket routes, the same token can be sent as the access_token query parameter.

When NoAuthentication is true, protected Local REST and WebSocket routes bypass bearer validation. Login remains available but is not required.

Disabled Mode

The agent can disable the Local API Gateway through its security configuration. When disabled, every /apigateway/v2/* request returns:

{
  "error": "Local API is disabled."
}

with HTTP status 403.

Error Shape

Endpoint-specific failures return standard HTTP status codes with this JSON shape:

{
  "error": "Human-readable error message."
}

Common statuses:

• 400: request fields or query parameters are missing or invalid.
• 401: login or bearer-token authentication failed.
• 403: Local API Gateway is disabled.
• 404: robot, fleet, metric, resource, stream, or stream type was not found.
• 408: a one-shot stream read timed out.
• 501: the requested local-fleet WebSocket behavior is not implemented.

note

This documentation is under active development.