1NCE OS APIs for the bundled IoT operating system services. Covers IoT Integrator (CoAP/UDP/LwM2M device endpoints, PSK provisioning, AWS IoT cloud integration), Device Locator (positions, geofences), Device Inspector (device stats and diagnostics), Optimizer (payload compression savings and message tests), Devices, Settings, Administration Logs, Agreements, and the Plugin system (Datacake, Memfault, Mender, Tartabit).
openapi: 3.0.1
info:
contact:
email: info@1nce.com
name: 1NCE GmbH
url: https://1nce.com
description: Documentation of the 1NCE OS API which can be used for managing the 1NCE OS Service.
title: 1NCE OS
version: v1.3
servers:
- url: https://api.1nce.com/management-api
tags:
- description: Integrate Devices and Clouds
name: IoT Integrator
- description: Optimize energy consumption
name: Optimizer
- description: Inspect details of the devices
name: Device Inspector
- description: Get device positions and manage geofences
name: Device Locator
- description: 1NCE OS Agreements
name: Agreements
- description: 1NCE OS Administration Logs
name: Administration Logs
- description: Device Management
name: Devices
- description: 1NCE OS Settings
name: Settings
- description: 1NCE OS Plugin System
name: Plugin system
paths:
/v1/integrate/devices/endpoints:
get:
description: Get details about the device endpoints.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/getAllResponseschema'
description: OK
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Get device endpoints
tags:
- IoT Integrator
/v1/integrate/devices/endpoints/{protocol}:
get:
description: Get details about the device endpoint of a specific protocol.
parameters:
- description: 'Available protocols: <ul><li>LWM2M</li><li>UDP</li><li>COAP</li></ul>'
explode: false
in: path
name: protocol
required: true
schema:
example: COAP
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/getResponseschema'
description: OK
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Get single device endpoint
tags:
- IoT Integrator
patch:
description: Update endpoint related settings.
parameters:
- description: 'Available protocols: <ul><li>LWM2M</li><li>UDP</li><li>COAP</li></ul>'
explode: false
in: path
name: protocol
required: true
schema:
example: COAP
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/patchschema'
description: The Body of the device endpoints patch request allows to update endpoint related settings.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/patchResponseschema'
description: OK
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Patch single device endpoint
tags:
- IoT Integrator
/v1/integrate/devices/actions/requests:
get:
deprecated: true
description: Get a list of device action requests in the last 7 days.
parameters:
- description: Number of the requested page. Use this parameter to iterate through all items on the different pages.
The total amount of pages is listed in the response body (pageAmount).
explode: true
in: query
name: page
required: false
schema:
default: 1
maximum: 50
minimum: 1
type: integer
style: form
- description: Parameter for specifying the queried items per page.
explode: true
in: query
name: pageSize
required: false
schema:
default: 10
example: 10
minimum: 1
type: integer
style: form
- description: The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query.
For 1NCE SIMS the device ID is equal to its iccid.
explode: true
in: query
name: deviceId
required: false
schema:
example: <device_id>
type: string
style: form
- description: 'Filter out data for specific protocols: <ul><li>LWM2M</li><li>UDP</li><li>COAP</li></ul>'
explode: true
in: query
name: protocol
required: false
schema:
example: COAP
type: string
style: form
- explode: true
in: query
name: status
required: false
schema:
enum:
- SCHEDULED
- IN_PROGRESS
- FAILED
- SUCCEEDED
- CANCELLED
example: IN_PROGRESS
type: string
style: form
- explode: true
in: query
name: sort
required: false
schema:
default: -created
enum:
- created
- -created
- updated
- -updated
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/getAllResponseschema_1'
description: OK
'400':
$ref: '#/components/responses/BadRequestError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Get device action requests
tags:
- IoT Integrator
/v1/integrate/devices/actions/requests/active:
get:
description: Get a list of active device action requests in the last 7 days.
parameters:
- description: Number of the requested page. Use this parameter to iterate through all items on the different pages.
The total amount of pages is listed in the response body (pageAmount).
explode: true
in: query
name: page
required: false
schema:
default: 1
maximum: 50
minimum: 1
type: integer
style: form
- description: Parameter for specifying the queried items per page.
explode: true
in: query
name: pageSize
required: false
schema:
default: 10
example: 10
minimum: 1
type: integer
style: form
- description: The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query.
For 1NCE SIMS the device ID is equal to its iccid.
explode: true
in: query
name: deviceId
required: false
schema:
example: <device_id>
type: string
style: form
- description: 'Filter out data for specific protocols: <ul><li>LWM2M</li><li>UDP</li><li>COAP</li></ul>'
explode: true
in: query
name: protocol
required: false
schema:
example: COAP
type: string
style: form
- explode: true
in: query
name: status
required: false
schema:
enum:
- SCHEDULED
- IN_PROGRESS
example: IN_PROGRESS
type: string
style: form
- explode: true
in: query
name: sort
required: false
schema:
default: -created
enum:
- created
- -created
- updated
- -updated
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/getActiveResponseschema'
description: OK
'400':
$ref: '#/components/responses/BadRequestError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Get active device action requests
tags:
- IoT Integrator
/v1/integrate/devices/actions/requests/archived:
get:
description: Get a list of archived device action requests in the last 7 days.
parameters:
- description: Number of the requested page. Use this parameter to iterate through all items on the different pages.
The total amount of pages is listed in the response body (pageAmount).
explode: true
in: query
name: page
required: false
schema:
default: 1
maximum: 50
minimum: 1
type: integer
style: form
- description: Parameter for specifying the queried items per page.
explode: true
in: query
name: pageSize
required: false
schema:
default: 10
example: 10
minimum: 1
type: integer
style: form
- description: The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query.
For 1NCE SIMS the device ID is equal to its iccid.
explode: true
in: query
name: deviceId
required: false
schema:
example: <device_id>
type: string
style: form
- description: 'Filter out data for specific protocols: <ul><li>LWM2M</li><li>UDP</li><li>COAP</li></ul>'
explode: true
in: query
name: protocol
required: false
schema:
example: COAP
type: string
style: form
- explode: true
in: query
name: status
required: false
schema:
enum:
- FAILED
- SUCCEEDED
- CANCELLED
example: SUCCEEDED
type: string
style: form
- explode: true
in: query
name: sort
required: false
schema:
default: -created
enum:
- created
- -created
- updated
- -updated
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/getArchivedResponseschema'
description: OK
'400':
$ref: '#/components/responses/BadRequestError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Get archived device action requests
tags:
- IoT Integrator
/v1/integrate/devices/{deviceId}/actions/requests:
delete:
description: Cancel all device action requests.
parameters:
- description: The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query.
For 1NCE SIMS the device ID is equal to its iccid.
explode: false
in: path
name: deviceId
required: true
schema:
example: <device_id>
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/deleteAllResponseschema'
description: OK
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Cancel all device action requests
tags:
- IoT Integrator
/v1/integrate/devices/actions/requests/{requestId}:
delete:
description: Cancel single device action request.
parameters:
- description: ID of device action request
explode: false
in: path
name: requestId
required: true
schema:
example: <request_id>
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/deleteResponseschema'
description: OK
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Cancel single device action request
tags:
- IoT Integrator
get:
description: Get details about the device action request.
parameters:
- description: ID of device action request
explode: false
in: path
name: requestId
required: true
schema:
example: <request_id>
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/getResponseschema_1'
description: OK
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Get single device action request
tags:
- IoT Integrator
/v1/integrate/devices/{deviceId}/presharedkey:
post:
description: Post a new Custom Pre-Shared Key for a specific Device.
parameters:
- description: The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query.
For 1NCE SIMS the device ID is equal to its iccid.
explode: false
in: path
name: deviceId
required: true
schema:
example: <device_id>
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postPreSharedKeyschema'
description: The Body for creating a new Custom Pre-Shared Key for a specific Device.The request body for setting
a new Custom Pre-Shared Key for a specific Device.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/postPreSharedKeyResponseschema'
description: OK
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Create Pre-Shared Device Key
tags:
- IoT Integrator
/v1/integrate/devices/presharedkey/jobs:
get:
description: Get status of Pre-Shared Keys Import jobs for the last 30 days.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/getResponseschema_2'
description: OK
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Pre-Shared Devices Keys Import Job Status
tags:
- IoT Integrator
post:
description: Import new Custom Pre-Shared Keys for multiple Devices.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postschema'
description: Array of objects containing deviceId (same as iccid for 1NCE sims) and PreSharedKey.
required: true
responses:
'202':
description: Accepted
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Import Pre-Shared Devices Keys
tags:
- IoT Integrator
/v1/integrate/devices/{deviceId}/psk:
post:
description: Post a new Custom Pre-Shared Key for a specific Device.
parameters:
- description: The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query.
For 1NCE SIMS the device ID is equal to its iccid.
explode: false
in: path
name: deviceId
required: true
schema:
example: <device_id>
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postPreSharedKeyschema'
description: The Body for creating a new Custom Pre-Shared Key for a specific Device.The request body for setting
a new Custom Pre-Shared Key for a specific Device.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/postPreSharedKeyResponseschema'
description: OK
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Create Pre-Shared Device Key
tags:
- IoT Integrator
/v1/integrate/devices/{deviceId}/psk/{protocol}:
get:
description: Get the Pre-Shared Key of a specific Device.
parameters:
- description: The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query.
For 1NCE SIMS the device ID is equal to its iccid.
explode: false
in: path
name: deviceId
required: true
schema:
example: <device_id>
type: string
style: simple
- description: 'Available protocols: <ul><li>LWM2M</li><li>UDP</li><li>COAP</li></ul>'
explode: false
in: path
name: protocol
required: true
schema:
example: COAP
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/postPreSharedKeyResponseschema'
description: OK
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Get Pre-Shared Device Key
tags:
- IoT Integrator
/v1/integrate/devices/psk/jobs:
get:
description: Get status of Pre-Shared Keys Import jobs for the last 30 days.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/getResponseschema_2'
description: OK
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Pre-Shared Devices Keys Import Job Status
tags:
- IoT Integrator
post:
description: Import new Custom Pre-Shared Keys for multiple Devices.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postschema'
description: Array of objects containing deviceId (same as iccid for 1NCE sims) and PreSharedKey.
required: true
responses:
'202':
description: Accepted
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Import Pre-Shared Devices Keys
tags:
- IoT Integrator
/v1/integrate/devices/{deviceId}/actions/LWM2M:
post:
description: Initiate LwM2M action like read, write, execute on specific device. It has to be connected to 1NCE LwM2M
endpoint to invoke this event.
parameters:
- description: The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query.
For 1NCE SIMS the device ID is equal to its iccid.
explode: false
in: path
name: deviceId
required: true
schema:
example: <device_id>
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postschema_1'
description: The Body for posting new LWM2M action to device.
required: true
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/postResponseschema'
description: Message describing the result of operation
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/ConflictError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Create Action Request On Specific LwM2M Device.
tags:
- IoT Integrator
/v1/integrate/devices/actions/LWM2M:
post:
description: Initiate LwM2M actions like read, write, execute on the specified devices. The devices have to be connected
to 1NCE LwM2M endpoint to invoke this event.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/bulkPostschema'
description: The Body for posting new LWM2M actions to the devices.
required: true
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/bulkPostResponseschema'
description: Message describing the result of operation
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Create Action Requests for LwM2M Devices.
tags:
- IoT Integrator
/v1/integrate/devices/{deviceId}/actions/COAP:
post:
description: Initiate CoAP action on specific device.
parameters:
- description: The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query.
For 1NCE SIMS the device ID is equal to its iccid.
explode: false
in: path
name: deviceId
required: true
schema:
example: <device_id>
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postschema_2'
description: The Body for posting new CoAP action to device.
required: true
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/postResponseschema'
description: Message describing the result of operation
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/ConflictError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Create Action Request On Specific CoAP Device.
tags:
- IoT Integrator
/v1/integrate/devices/actions/COAP:
post:
description: Initiate CoAP action on the devices.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/bulkPostschema_1'
description: The Body for posting new CoAP actions to the devices.
required: true
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/bulkPostResponseschema'
description: Message describing the result of operation
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Create Action Requests for CoAP Devices.
tags:
- IoT Integrator
/v1/integrate/devices/{deviceId}/actions/UDP:
post:
description: Initiate UDP action on specific device.
parameters:
- description: The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query.
For 1NCE SIMS the device ID is equal to its iccid.
explode: false
in: path
name: deviceId
required: true
schema:
example: <device_id>
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postschema_3'
description: The Body for posting new UDP action to device.
required: true
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/postResponseschema'
description: Message describing the result of operation
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/ConflictError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Create Action Request On Specific UDP Device.
tags:
- IoT Integrator
/v1/integrate/devices/actions/UDP:
post:
description: Initiate UDP action on devices.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/bulkPostschema_2'
description: The Body for posting new UDP action to the devices.
required: true
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/bulkPostResponseschema'
description: Message describing the result of operation
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Create Action Requests for UDP Devices.
tags:
- IoT Integrator
/v1/optimize/messages/test:
post:
description: Test a template with a sample input message.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postschema_4'
description: The Body of the template tester post request.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/postResponseschema_1'
description: OK
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Test template
tags:
- Optimizer
/v1/optimize/savings:
get:
description: Get statistics about the savings by using the optimizer.
parameters:
- description: Specify the range in days to receive data about.
explode: true
in: query
name: range
required: false
schema:
default: '1'
enum:
- '1'
- '7'
- '30'
example: '1'
type: string
style: form
- description: 'Filter out by specific protocols: <ul><li>UDP</li><li>COAP</li></ul>'
explode: true
in: query
name: protocol
required: false
schema:
enum:
- UDP
- COAP
example: COAP
type: string
style: form
- description: ICCID of a SIM device, used to identifiy each 1NCE SIM.
explode: true
in: query
name: iccid
required: false
schema:
example: '8988280666000000000'
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/getResponseschema_3'
description: OK
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuthentication: []
summary: Get savings
tags:
- Optimizer
/v1/agreements/1nceos:
post:
description: Post request to accept the 1NCE OS Terms of Use and Data Processing agreements. Please note that with this
request the agreements can only be accepted.
requestBody:
content:
application/json:
schema:
# --- truncated at 32 KB (227 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/1nce/refs/heads/main/openapi/1nce-os-openapi.yml