openapi: 3.1.0
info:
title: emnify REST subpackage_applicationTokens subpackage_endpoint API
version: 1.0.0
description: 'The emnify REST API gives programmatic access to the emnify IoT SuperNetwork — global cellular connectivity for IoT devices. Manage SIMs, endpoints (devices), service and tariff profiles, events, SMS, eSIM (SGP.32) profiles, organizations, users, API callbacks, and the Data Streamer. Authenticate with application tokens or user credentials; tokens are short-lived JWTs.
Source: emnify developer documentation (https://docs.emnify.com/developers/api). This spec is assembled from the per-operation OpenAPI fragments published in the emnify llms-full.txt feed.'
contact:
name: emnify Developer Support
url: https://docs.emnify.com/developers
license:
name: Proprietary
url: https://www.emnify.com/legal
servers:
- url: https://cdn.emnify.net
description: emnify REST API base host
security:
- BearerAuth: []
tags:
- name: subpackage_endpoint
x-display-name: Endpoint
paths:
/api/v1/endpoint:
get:
operationId: get-endpoints
summary: List endpoints
description: 'Retrieves all endpoints for your organization.
Use the query parameters to filter, sort, and paginate results.
'
tags:
- subpackage_endpoint
parameters:
- name: q
in: query
description: 'Filters endpoints by field value.
Use `<field>:<criteria>` format.
Combine multiple filters with commas (for example, `status:0,tags:sensor`).
'
required: false
schema:
type: string
- name: sort
in: query
description: 'Sorts endpoints by field value.
Use `<operator><field>` format.
Combine multiple sort fields with commas (for example, `-status,id`).
**Operators:**
- `-` descending (Z-A for text, highest number first)
- `+` ascending (A-Z for text, lowest number first)
Defaults to ascending order if no operator is specified.
Defaults to `id` if no sort field is specified.
Endpoints with identical values are sorted by ascending `id`.
'
required: false
schema:
type: string
- name: page
in: query
description: 'Page number to retrieve.
Starts at 1.
'
required: false
schema:
type: integer
default: 1
- name: per_page
in: query
description: Number of endpoints to return per page.
required: false
schema:
type: integer
default: 1000
- name: Authorization
in: header
description: 'An `auth_token` should be provided to authenticate a session.
To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).
'
required: true
schema:
type: string
responses:
'200':
description: 'Returns an array of endpoint objects.
Pagination metadata is included in the response headers.
'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiV1EndpointGetResponsesContentApplicationJsonSchemaItems'
post:
operationId: create-endpoint
summary: Create an endpoint
description: "Creates a single endpoint with the specified configuration.\n\n<Note>\n For bulk operations, use [`POST /api/v2/endpoint/multi`](/developers/api/endpoint/bulk-create-endpoint) instead (supports up to 2,000 endpoints per request).\n</Note>\n\n<Warning>\n emnify charges for activated SIMs, even if the endpoint status is set to **Disabled**.\n</Warning>\n"
tags:
- subpackage_endpoint
parameters:
- name: Authorization
in: header
description: 'An `auth_token` should be provided to authenticate a session.
To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).
'
required: true
schema:
type: string
responses:
'201':
description: Endpoint created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Endpoint_CreateEndpoint_Response_201'
'400':
description: 'Request body is malformed.
Check JSON syntax.
'
content:
application/json:
schema:
description: Any type
'404':
description: 'IP address space is full, in use for creating another endpoint or the resource wasn''t found.
'
content:
application/json:
schema:
description: Any type
'422':
description: 'Validation failed.
Possible causes:
- Invalid service profile, tariff profile, or status ID
- Invalid IP address space or organization ID
- Endpoint data is invalid
- Organization doesn''t belong to your reseller
'
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEndpointRequestUnprocessableEntityError'
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Display name for the endpoint.
tags:
type: string
description: Comma-separated list of tags (for example, `sensor,outdoor`).
imei:
type: string
description: International Mobile Equipment Identity with Software Version Number (IMEISV) (16 digits).
imei_lock:
type: boolean
default: false
description: If `true`, this endpoint only allows connections from the device with the specified IMEI.
sim:
$ref: '#/components/schemas/ApiV1EndpointPostRequestBodyContentApplicationJsonSchemaSim'
description: 'SIM card to assign to this endpoint.
If omitted, no SIM is assigned.
'
ip_address:
type: string
description: "Private IP address to assign.\n\n<Info>\n If provided, you must also specify `ip_address_space`.\n</Info>\n"
service_profile:
$ref: '#/components/schemas/ApiV1EndpointPostRequestBodyContentApplicationJsonSchemaServiceProfile'
description: 'Service profile that determines network access settings.
Must belong to your organization.
'
tariff_profile:
$ref: '#/components/schemas/ApiV1EndpointPostRequestBodyContentApplicationJsonSchemaTariffProfile'
description: 'Tariff profile that determines pricing and data limits.
Must belong to your organization.
'
status:
$ref: '#/components/schemas/ApiV1EndpointPostRequestBodyContentApplicationJsonSchemaStatus'
description: Initial endpoint status.
organisation:
$ref: '#/components/schemas/ApiV1EndpointPostRequestBodyContentApplicationJsonSchemaOrganisation'
description: 'Organization to create the endpoint in.
Required only for reseller accounts creating endpoints in sub-organizations.
'
ip_address_space:
$ref: '#/components/schemas/ApiV1EndpointPostRequestBodyContentApplicationJsonSchemaIpAddressSpace'
description: "IP address space for the endpoint.\n\n<Info>\n Required if `ip_address` is provided.\n</Info>\n"
required:
- service_profile
- tariff_profile
- status
/api/v1/endpoint/status:
get:
operationId: endpoint-status-get
summary: List endpoint statuses
description: Returns a list of available [endpoint statuses](/developers/reference/endpoint#endpoint-statuses).
tags:
- subpackage_endpoint
parameters:
- name: Authorization
in: header
description: 'An `auth_token` should be provided to authenticate a session.
To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiV1EndpointStatusGetResponsesContentApplicationJsonSchemaItems'
/api/v1/endpoint/{endpoint_id}:
get:
operationId: endpoint-by-id-get
summary: Endpoint details
description: Retrieves endpoint details for a given ID.
tags:
- subpackage_endpoint
parameters:
- name: endpoint_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: 'An `auth_token` should be provided to authenticate a session.
To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).
'
required: true
schema:
type: string
responses:
'200':
description: Successfully returned the endpoint details associated with the provided `id`.
content:
application/json:
schema:
$ref: '#/components/schemas/Endpoint_EndpointByIdGet_Response_200'
delete:
operationId: endpoint-by-id-delete
summary: Delete an endpoint
description: "Deletes an endpoint and all its child entities.\n\n<Note>\n Execute this operation sequentially - wait for each request to complete before starting the next.\n\n For bulk deletions, use [`DELETE /api/v2/endpoint/multi`](/developers/api/endpoint/bulk-delete-endpoint) instead (supports up to 2,000 endpoints).\n</Note>\n\n<Info>\n Endpoints with an assigned SIM cannot be deleted (results in a `409` error).\n</Info>\n"
tags:
- subpackage_endpoint
parameters:
- name: endpoint_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: 'An `auth_token` should be provided to authenticate a session.
To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).
'
required: true
schema:
type: string
responses:
'204':
description: 'Endpoints deleted successfully.
The response payload body should be empty.
'
content:
application/json:
schema:
type: object
properties: {}
'400':
description: 'Request body is malformed
'
content:
application/json:
schema:
description: Any type
'404':
description: 'Requested endpoint ID wasn''t found
'
content:
application/json:
schema:
description: Any type
'409':
description: 'Requested endpoint is still referenced (for example, there is an assigned SIM)
'
content:
application/json:
schema:
description: Any type
patch:
operationId: endpoint-by-id-patch
summary: Update an endpoint
description: "Updates the details of an endpoint.\n\n<Note>\n Execute this operation sequentially - wait for each request to complete before starting the next.\n\n For bulk updates, use [`PATCH /api/v2/endpoint/multi`](/developers/api/endpoint/bulk-update-endpoint) instead (supports up to 2,000 endpoints).\n</Note>\n\n<Warning>\n emnify charges for activated SIMs, even if the endpoint `status` is set to **Disabled**.\n To avoid accruing unexpected charges, update the SIM `status` to **Suspended** (`\"id\": 2`).\n</Warning>\n"
tags:
- subpackage_endpoint
parameters:
- name: endpoint_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: 'An `auth_token` should be provided to authenticate a session.
To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).
'
required: true
schema:
type: string
responses:
'204':
description: Endpoint updated successfully
content:
application/json:
schema:
type: object
properties: {}
'400':
description: Request body is malformed
content:
application/json:
schema:
description: Any type
'403':
description: 'User doesn''t have permission to bulk update endpoints
'
content:
application/json:
schema:
description: Any type
'404':
description: 'Appears in one of the following cases:
- IP address space isn''t found
- IP address space is full
'
content:
application/json:
schema:
description: Any type
'422':
description: 'Appears in one of the following cases:
- Service profile is invalid
- Tariff profile is invalid
- Status is invalid
- IP address space is invalid
- IP address is invalid
- SIM is invalid
'
content:
application/json:
schema:
$ref: '#/components/schemas/EndpointByIdPatchRequestUnprocessableEntityError'
requestBody:
content:
application/json:
schema:
type: object
properties:
service_profile:
$ref: '#/components/schemas/ApiV1EndpointEndpointIdPatchRequestBodyContentApplicationJsonSchemaServiceProfile'
tariff_profile:
$ref: '#/components/schemas/ApiV1EndpointEndpointIdPatchRequestBodyContentApplicationJsonSchemaTariffProfile'
status:
$ref: '#/components/schemas/ApiV1EndpointEndpointIdPatchRequestBodyContentApplicationJsonSchemaStatus'
ip_address_space:
$ref: '#/components/schemas/ApiV1EndpointEndpointIdPatchRequestBodyContentApplicationJsonSchemaIpAddressSpace'
sim:
$ref: '#/components/schemas/ApiV1EndpointEndpointIdPatchRequestBodyContentApplicationJsonSchemaSim'
name:
type: string
tags:
type: string
imei:
type: string
imei_lock:
type: boolean
ip_address:
type: string
required:
- service_profile
- tariff_profile
- status
- ip_address_space
- sim
- name
- tags
- imei
- imei_lock
- ip_address
/api/v1/endpoint/{endpoint_id}/connectivity:
get:
operationId: endpoint-connectivity-by-id-get
summary: Endpoint connectivity status
description: 'Retrieve details about current connectivity status of endpoint.
The following is a list of possible statuses:
* `ATTACHED`:
The Endpoint has succesfully attached to the Home Core network in the past.
The device will be shown as `ATTACHED` until the visited network has signaled that the device is inactive/offline.
Usually the visited network informs the Core Network within 1-2 days after a device went offline.
* `ONLINE`:
The Endpoint has an active data connection
* `OFFLINE`:
The Endpoint has not attached to the core network yet or the device was previously attached but the visited network signaled that the device had no activity for the last 1-2 days.
Note: The device is not reachable for external services (e.g. SMS, MSRN lookup).
* `BLOCKED`:
The device is not granted service. Endpoints are assigned this status when they have exceeded traffic limits.
'
tags:
- subpackage_endpoint
parameters:
- name: endpoint_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: 'An `auth_token` should be provided to authenticate a session.
To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Endpoint_EndpointConnectivityByIdGet_Response_200'
patch:
operationId: update-endpoint-connectivity-by-id
summary: Reset endpoint connectivity
description: "Dispatches a message that causes either a `Cancel Location`, `Delete PDP Context`, or both sent to the endpoint.\nThe return of the call doesn't yet mean the event has been sent towards the device.\n\n<Info>\n Master organization types can reset any endpoints inside their organization hierarchy.\n Enterprises may only reset connectivity of own endpoints.\n</Info>\n"
tags:
- subpackage_endpoint
parameters:
- name: endpoint_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: 'An `auth_token` should be provided to authenticate a session.
To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).
'
required: true
schema:
type: string
responses:
'204':
description: Successful, no content.
content:
application/json:
schema:
type: object
properties: {}
'403':
description: Calling organization is not of correct type.
content:
application/json:
schema:
description: Any type
'404':
description: Endpoint not found.
content:
application/json:
schema:
description: Any type
requestBody:
content:
application/json:
schema:
type: object
properties:
pdp_context:
oneOf:
- description: Any type
- type: 'null'
location:
oneOf:
- description: Any type
- type: 'null'
/api/v1/endpoint/{endpoint_id}/connectivity_info:
get:
operationId: get-connectivity-info-by-endpoint-id
summary: Retrieve connectivity information for an endpoint
description: "Returns device location information based on the cell tower to which the device is connected.\n\n<Note>\n emnify validates the data requested, sends the signal request to the network operator, and interprets the response.\n Whether the network returns useful data is outside of emnify's control.\n\n To distinguish these cases, this call returns the HTTP `200 OK` response code whenever the request is successfully executed, even if it includes an error.\n See the response body for details.\n</Note>\n"
tags:
- subpackage_endpoint
parameters:
- name: endpoint_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: 'An `auth_token` should be provided to authenticate a session.
To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Endpoint_GetConnectivityInfoByEndpointId_Response_200'
'404':
description: 'Endpoint not found.
This error often occurs when the requested endpoint ID is incorrect or doesn''t exist.
It can also happen if you don''t have the correct permissions to see the connectivity information or the endpoint doesn''t belong to the organization you''re logged in to.
'
content:
application/json:
schema:
$ref: '#/components/schemas/GetConnectivityInfoByEndpointIdRequestNotFoundError'
/api/v1/endpoint/{endpoint_id}/event:
get:
operationId: endpoint-events-by-id
summary: List endpoint events
description: "Returns the list of events, filtered, sorted and paged according to query parameters.\n\n<Info>\nA full list of events is found in section \"Retrieve Event Types\" (`/api/v1/event/type`).\n</Info>\n\n<Error>\n This API endpoint deviates from the specified conventions and may not return the same HTTP Codes as the higher layer call (`/api/v1/endpoint/{endpoint_id}`).\n In case the requested `{endpoint_id}` doesn't exist or is not accessible for the user, **HTTP 200** will be returned with empty **[]** as long as the provided `{endpoint_id}` is a number and all parameters are valid.\n\n Please take that into consideration when building automation on top of the error behaviour of this endpoint.\n</Error>\n"
tags:
- subpackage_endpoint
parameters:
- name: endpoint_id
in: path
description: Numeric ID of an endpoint
required: true
schema:
type: integer
- name: page
in: query
description: Current page number
required: false
schema:
type: integer
- name: per_page
in: query
description: Defines the number of items per page
required: false
schema:
type: integer
- name: sort
in: query
description: 'Sort properties according to a comma separated list of accepted fields. Valid fields are:
* `id` - (**event id**)
* `timestamp` - (**event timestamp**)
* `source` - (**event source**)
* `severity` - (**event severity**)
* `alert` - (**alert status**)
* `organisation` - (**organisation name**)
* `user` - (**user id**)
* `endpoint` - (**endpoint name**)
* `tags` - (**endpoint tags**)
* `ip_address` - (**endpoint ip_address**)
* `iccid` - (**sim iccid**)
* `imsi` - (**sim imsi**)
* `type` - (**event type**)
'
required: false
schema:
type: string
- name: q
in: query
description: 'Filter parameter in `<filter>:<value>` format.
Multiple filters must be a comma-separated list of the following fields:
* `from` (**date**, format `YYYY-MM-DDTHH:mm:ssZ`, **only valid with until**)
* `until` (**date**, format `YYYY-MM-DDTHH:mm:ssZ`, **only valid with from**)
* `type` (**event_type**, numerical)
* `source` (**event_type**, numerical, e.g. 0 = Network), 1 = Policy Control, 2 = API)
* `severity` (**event_severity**, numerical, e.g. 0 = Info, 1 = Warn), 2 = Critical)
* `alert` (boolean, e.g. true, false)
* `description` (**event description**, string)
* `organisation` (**organisation name**, string)
* `user` (**user name**, string)
* `endpoint` (**endpoint name**, string)
* `tags` (**endpoint tags**, string)
* `ip_address` (**endpoint IP address**, valid IPv4/IPv6 address)
* `imei` (**endpoint imei**, numerical string)
* `iccid` (**sim iccid**, numerical string)
* `imsi` (**sim imsi**, numerical string)
* `timestamp` (**date**, format `YYYY-MM-DDTHH:mm:ssZ`, for querying events of 1 day, deprecated in future)
* `iccid_with_luhn` (**sim iccid with Luhn**, numerical string)
* `network` (**endpoint network**, string, e.g. Telekom)
* `rat` (**event pdp context rat type**, numerical string, e.g. 6)
* `country` (**endpoint country**, string, e.g. Germany)
Some filters can accept up to 6 values which must be separated by the pipe symbol (`|`) or url-encoded as (`%7C`):
* `iccid` (q: iccid:1234567890123456789|8988303000123456789)
* `iccid_with_luhn` (q: iccid_with_luhn:12345678901234567891|89883030001234567891)
* `endpoint` (q: endpoint:example_endpoint_name|another_endpoint_name)
* `type` (q: type:example_event_type|another_event_type)
* `network` (q: network:example_network|another_network)
* `rat` (q: rat:example_rat|another_rat)
* `country` (q: country:example_country|another_country)
'
required: false
schema:
type: string
- name: Authorization
in: header
description: 'An `auth_token` should be provided to authenticate a session.
To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).
'
required: true
schema:
type: string
responses:
'200':
description: Successfully returned a list of events
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiV1EndpointEndpointIdEventGetResponsesContentApplicationJsonSchemaItems'
'400':
description: '**Bad Request** due to incorrect **Paging** Parameters, **Sorting** Parameter or incorrect `{endpoint_id}`
'
content:
application/json:
schema:
description: Any type
'422':
description: '**Unprocessable Entity** due to incorrect **Query** parameters
'
content:
application/json:
schema:
description: Any type
/api/v1/endpoint/{endpoint_id}/operator_blacklist:
get:
operationId: endpoint-operator-blacklist-by-endpoint-id-get
summary: List operator blacklist for endpoint
description: Returns a list of blacklisted Operators for the requested Endpoint
tags:
- subpackage_endpoint
parameters:
- name: endpoint_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: 'An `auth_token` should be provided to authenticate a session.
To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiV1EndpointEndpointIdOperatorBlacklistGetResponsesContentApplicationJsonSchemaItems'
/api/v1/endpoint/{endpoint_id}/operator_blacklist/{operator_id}:
put:
operationId: endpoint-operator-blacklist-by-ep-id-and-operator-id-put
summary: Add an operator to the blacklist
description: Adds an Operator to the Blacklist of an Endpoint.
tags:
- subpackage_endpoint
parameters:
- name: endpoint_id
in: path
required: true
schema:
type: string
- name: operator_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: 'An `auth_token` should be provided to authenticate a session.
To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).
'
required: true
schema:
type: string
responses:
'204':
description: The server has successfully fulfilled the request and that there is no additional content to send in the response payload body
content:
application/json:
schema:
type: object
properties: {}
'409':
description: Unexpected error in API call. See HTTP response body for details.
content:
application/json:
schema:
$ref: '#/components/schemas/EndpointOperatorBlacklistByEpIdAndOperatorIdPutRequestConflictError'
delete:
operationId: endpoint-operator-blacklist-by-ep-id-and-operator-id-delete
summary: Remove an operator from the blacklist
description: Remove Operator from the Blacklist of an Endpoint.
tags:
- subpackage_endpoint
parameters:
- name: endpoint_id
in: path
required: true
schema:
type: string
- name: operator_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: 'An `auth_token` should be provided to authenticate a session.
To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).
'
required: true
schema:
type: string
responses:
'204':
description: The server has successfully fulfilled the request and that there is no additional content to send in the response payload body
content:
application/json:
schema:
type: object
properties: {}
'404':
description: Unexpected error in API call. See HTTP response body for details.
content:
application/json:
schema:
$ref: '#/components/schemas/EndpointOperatorBlacklistByEpIdAndOperatorIdDeleteRequestNotFoundError'
/api/v1/endpoint/{endpoint_id}/quota/data:
get:
operationId: endpoint-quota-data-by-endpoint-id-get
summary: Retrieve data quota details
description: "Returns details about the assigned Data Quota for an endpoint.\n* `status`: this indicates the current status of the quota and may contain the following values:\n - `ACTIVE`: the endpoint can currently connect and has quota left\n - `EXHAUSTED`: the endpoint has exceeded the quota volume, if it still can use data service depends on the action chosen to be performed on exhaustion\n - `EXPIRED`: the quota has expired; the endpoint is denied from using data services (until new quota is added)\n* `volume`: returns the volume left on this quota in MB\n* `expiry_date`: timestamp when this quota will expire and the endpoint will definitely be denied from using further data services (regardless if the quota volume was used up or not)\n* `peak_throughput`: The maximum bandwidth in octets per second after the endpoint has been throttled.\n* `action_on_exhaustion`: returns the behaviour defined to be applied when quota volume is used up (exhausted).\n - `Throttle`: bandwidth will be throttle to the defined p
# --- truncated at 32 KB (147 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/emnify/refs/heads/main/openapi/emnify-subpackage-endpoint-api-openapi.yml