Create, list, and delete device tags and link or unlink tags to one or many devices for fleet grouping and bulk operations.
openapi: 3.0.1
info:
title: Hologram REST API
description: >-
REST API for the Hologram global cellular IoT connectivity platform.
Manage devices and cellular links (SIMs), activate and pause SIMs, change
data plans, query data and SMS usage, send SMS and cloud messages to
devices, manage device tags, and read available data plans. All requests
are authenticated with HTTP Basic auth using the username `apikey` and the
API key as the password.
termsOfService: https://www.hologram.io/terms/
contact:
name: Hologram Support
url: https://support.hologram.io/
version: '1.0'
servers:
- url: https://dashboard.hologram.io/api/1
security:
- apikeyAuth: []
tags:
- name: Devices
- name: Cellular Links
- name: Tags
- name: Usage
- name: SMS
- name: Messaging
- name: Plans
- name: Webhooks
paths:
/devices:
get:
operationId: listDevices
tags:
- Devices
summary: List devices
description: Retrieve a list of devices, optionally filtered by organization, tag, SIM, name, type, or IMEI.
parameters:
- $ref: '#/components/parameters/orgid'
- name: tagid
in: query
schema:
type: integer
- name: tagname
in: query
schema:
type: string
- name: sim
in: query
schema:
type: string
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/startafter'
responses:
'200':
description: A list of devices.
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceListResponse'
/devices/{deviceid}:
get:
operationId: getDevice
tags:
- Devices
summary: Retrieve a device
parameters:
- $ref: '#/components/parameters/deviceid'
responses:
'200':
description: The requested device.
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceResponse'
put:
operationId: updateDevice
tags:
- Devices
summary: Update a device
description: Update the device name, owning organization, or tunnelable flag.
parameters:
- $ref: '#/components/parameters/deviceid'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
orgid:
type: integer
tunnelable:
type: boolean
responses:
'200':
description: The updated device.
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceResponse'
/devices/{deviceid}/state:
post:
operationId: setDeviceState
tags:
- Devices
summary: Pause or unpause device data
parameters:
- $ref: '#/components/parameters/deviceid'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- state
properties:
state:
type: string
enum:
- pause
- live
responses:
'200':
description: The device state was updated.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
/devices/tags:
get:
operationId: listDeviceTags
tags:
- Tags
summary: List device tags
parameters:
- $ref: '#/components/parameters/orgid'
- $ref: '#/components/parameters/limit'
responses:
'200':
description: A list of device tags.
content:
application/json:
schema:
$ref: '#/components/schemas/TagListResponse'
post:
operationId: createDeviceTag
tags:
- Tags
summary: Create a device tag
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
deviceids:
type: array
items:
type: integer
responses:
'200':
description: The created tag.
content:
application/json:
schema:
$ref: '#/components/schemas/TagResponse'
/devices/tags/{tagid}:
delete:
operationId: deleteDeviceTag
tags:
- Tags
summary: Delete a device tag
parameters:
- $ref: '#/components/parameters/tagid'
responses:
'200':
description: The tag was deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
/devices/tags/{tagid}/link:
post:
operationId: linkDeviceTag
tags:
- Tags
summary: Link a tag to devices
parameters:
- $ref: '#/components/parameters/tagid'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- deviceids
properties:
deviceids:
type: array
items:
type: integer
responses:
'200':
description: The tag was linked to the devices.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
/devices/tags/{tagid}/unlink:
post:
operationId: unlinkDeviceTag
tags:
- Tags
summary: Unlink a tag from devices
parameters:
- $ref: '#/components/parameters/tagid'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- deviceids
properties:
deviceids:
type: array
items:
type: integer
responses:
'200':
description: The tag was unlinked from the devices.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
/links/cellular:
get:
operationId: listCellularLinks
tags:
- Cellular Links
summary: List cellular links (SIMs)
description: Retrieve cellular links, optionally filtered by organization, SIM, MSISDN, IMSI, or device.
parameters:
- $ref: '#/components/parameters/orgid'
- name: sim
in: query
schema:
type: string
- name: deviceid
in: query
schema:
type: integer
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/startafter'
responses:
'200':
description: A list of cellular links.
content:
application/json:
schema:
$ref: '#/components/schemas/CellularLinkListResponse'
/links/cellular/{linkid}:
get:
operationId: getCellularLink
tags:
- Cellular Links
summary: Retrieve a cellular link
parameters:
- $ref: '#/components/parameters/linkid'
responses:
'200':
description: The requested cellular link.
content:
application/json:
schema:
$ref: '#/components/schemas/CellularLinkResponse'
/links/cellular/sim_{iccid}/claim:
post:
operationId: claimSim
tags:
- Cellular Links
summary: Activate (claim) a SIM
description: Activate a single SIM by ICCID onto a data plan and zone.
parameters:
- name: iccid
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- plan
properties:
plan:
type: integer
zone:
type: string
orgid:
type: integer
tagid:
type: integer
overage_limit:
type: integer
responses:
'200':
description: The SIM was activated.
content:
application/json:
schema:
$ref: '#/components/schemas/CellularLinkResponse'
/links/cellular/bulkclaim:
post:
operationId: bulkClaimSims
tags:
- Cellular Links
summary: Activate (claim) multiple SIMs in bulk
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- plan
properties:
sims:
type: array
items:
type: string
simrange:
type: string
plan:
type: integer
zone:
type: string
orgid:
type: integer
tagid:
type: integer
responses:
'200':
description: The SIMs were activated.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
/links/cellular/{linkid}/state:
post:
operationId: setCellularLinkState
tags:
- Cellular Links
summary: Pause or unpause a SIM
parameters:
- $ref: '#/components/parameters/linkid'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- state
properties:
state:
type: string
enum:
- pause
- live
responses:
'200':
description: The SIM state was updated.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
/links/cellular/{linkid}/changeplan:
post:
operationId: changeCellularLinkPlan
tags:
- Cellular Links
summary: Change a SIM data plan
parameters:
- $ref: '#/components/parameters/linkid'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- planid
properties:
planid:
type: integer
zone:
type: string
overage_limit:
type: integer
responses:
'200':
description: The SIM plan was changed.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
/usage/data:
get:
operationId: listDataUsage
tags:
- Usage
summary: List data usage sessions
parameters:
- $ref: '#/components/parameters/orgid'
- name: linkid
in: query
schema:
type: integer
- name: tagid
in: query
schema:
type: integer
- name: timestart
in: query
schema:
type: integer
- name: timeend
in: query
schema:
type: integer
- $ref: '#/components/parameters/limit'
responses:
'200':
description: A list of data usage sessions.
content:
application/json:
schema:
$ref: '#/components/schemas/UsageListResponse'
/usage/data/daily:
get:
operationId: listDailyDataUsage
tags:
- Usage
summary: Daily data usage summaries
parameters:
- $ref: '#/components/parameters/orgid'
- name: linkid
in: query
schema:
type: integer
- name: timestart
in: query
schema:
type: integer
- name: timeend
in: query
schema:
type: integer
- $ref: '#/components/parameters/limit'
responses:
'200':
description: Daily data usage summaries.
content:
application/json:
schema:
$ref: '#/components/schemas/UsageListResponse'
/usage/sms:
get:
operationId: listSmsUsage
tags:
- Usage
summary: List device-originated SMS usage
parameters:
- $ref: '#/components/parameters/orgid'
- name: linkid
in: query
schema:
type: integer
- $ref: '#/components/parameters/limit'
responses:
'200':
description: A list of SMS usage records.
content:
application/json:
schema:
$ref: '#/components/schemas/UsageListResponse'
/sms/incoming:
post:
operationId: sendSmsToDevice
tags:
- SMS
summary: Send an SMS to one or more devices
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- body
properties:
deviceid:
type: integer
deviceids:
type: array
items:
type: integer
fromnumber:
type: string
body:
type: string
base64body:
type: string
responses:
'200':
description: The SMS was queued for delivery.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
/devices/messages:
post:
operationId: sendCloudMessage
tags:
- Messaging
summary: Send a cloud message to devices
description: Send a TCP or UDP message to one or more devices over the Hologram cloud.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- deviceids
- protocol
- port
properties:
deviceids:
type: array
items:
type: integer
protocol:
type: string
enum:
- TCP
- UDP
port:
type: integer
data:
type: string
base64data:
type: string
responses:
'200':
description: The message was sent.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
/devices/messages/{deviceid}/{webhookguid}:
post:
operationId: sendWebhookMessage
tags:
- Webhooks
summary: Send a message to a device via a webhook GUID
description: >-
Pre-authenticated inbound endpoint that delivers a message to a device
addressed by its id and a per-device webhook GUID. Does not require API
key authentication.
security: []
parameters:
- $ref: '#/components/parameters/deviceid'
- name: webhookguid
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
type: string
base64data:
type: string
responses:
'200':
description: The message was delivered.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
/plans:
get:
operationId: listPlans
tags:
- Plans
summary: List data plans
parameters:
- $ref: '#/components/parameters/orgid'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/startafter'
responses:
'200':
description: A list of data plans.
content:
application/json:
schema:
$ref: '#/components/schemas/PlanListResponse'
/plans/{planid}:
get:
operationId: getPlan
tags:
- Plans
summary: Retrieve a data plan
parameters:
- name: planid
in: path
required: true
schema:
type: integer
responses:
'200':
description: The requested data plan.
content:
application/json:
schema:
$ref: '#/components/schemas/PlanResponse'
components:
securitySchemes:
apikeyAuth:
type: http
scheme: basic
description: >-
HTTP Basic authentication. Use the literal username `apikey` and your
Hologram API key as the password. The API key may alternatively be
supplied as an `apikey` query parameter.
parameters:
orgid:
name: orgid
in: query
description: Organization id to scope the request.
schema:
type: integer
deviceid:
name: deviceid
in: path
required: true
schema:
type: integer
linkid:
name: linkid
in: path
required: true
schema:
type: integer
tagid:
name: tagid
in: path
required: true
schema:
type: integer
limit:
name: limit
in: query
description: Maximum number of records to return.
schema:
type: integer
startafter:
name: startafter
in: query
description: Record id to paginate after.
schema:
type: integer
schemas:
SuccessResponse:
type: object
properties:
success:
type: boolean
error:
type: string
Device:
type: object
properties:
id:
type: integer
orgid:
type: integer
name:
type: string
phonenumber:
type: string
imei:
type: string
iccid:
type: string
lastsession:
type: object
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
links:
type: object
DeviceResponse:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/Device'
DeviceListResponse:
type: object
properties:
success:
type: boolean
size:
type: integer
limit:
type: integer
continues:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/Device'
CellularLink:
type: object
properties:
id:
type: integer
deviceid:
type: integer
sim:
type: string
msisdn:
type: string
imsi:
type: string
planid:
type: integer
zone:
type: string
state:
type: string
whenclaimed:
type: string
whenexpires:
type: string
CellularLinkResponse:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/CellularLink'
CellularLinkListResponse:
type: object
properties:
success:
type: boolean
size:
type: integer
limit:
type: integer
continues:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/CellularLink'
Tag:
type: object
properties:
id:
type: integer
name:
type: string
orgid:
type: integer
devices:
type: array
items:
type: integer
TagResponse:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/Tag'
TagListResponse:
type: object
properties:
success:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/Tag'
Plan:
type: object
properties:
id:
type: integer
name:
type: string
data:
type: integer
price:
type: integer
zone:
type: string
sms:
type: integer
carrier:
type: string
PlanResponse:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/Plan'
PlanListResponse:
type: object
properties:
success:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/Plan'
UsageRecord:
type: object
properties:
id:
type: integer
deviceid:
type: integer
linkid:
type: integer
bytes:
type: integer
timestamp:
type: string
network:
type: string
UsageListResponse:
type: object
properties:
success:
type: boolean
size:
type: integer
limit:
type: integer
continues:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/UsageRecord'