Soracom Air for Sigfox API

openapi: 3.0.0
info:
  title: Soracom Air for Sigfox API
  description: Manage Soracom Air for Sigfox devices.
  version: 20250903-043502
servers:
- description: Japan coverage production API endpoint
  url: https://api.soracom.io/v1
- description: Global coverage production API endpoint
  url: https://g.api.soracom.io/v1
paths:
  /sigfox_devices:
    get:
      description: 'Returns a list of Sigfox devices that match certain criteria. If the total number of Sigfox devices does
        not fit in one page, a URL for accessing the next page is returned in the `link` header of the response.

        '
      operationId: listSigfoxDevices
      parameters:
      - description: Tag name for filtering the search (exact match).
        in: query
        name: tag_name
        required: false
        schema:
          type: string
      - description: Tag search string for filtering the search. Required when `tag_name` has been specified.
        in: query
        name: tag_value
        required: false
        schema:
          type: string
      - description: Tag match mode.
        in: query
        name: tag_value_match_mode
        required: false
        schema:
          default: exact
          enum:
          - exact
          - prefix
          type: string
      - description: Maximum number of Sigfox devices to retrieve.
        in: query
        name: limit
        required: false
        schema:
          type: integer
      - description: The device ID of the last Sigfox device retrieved on the previous page. By specifying this parameter,
          you can continue to retrieve the list from the next Sigfox device onward.
        in: query
        name: last_evaluated_key
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SigfoxDevice'
                type: array
          description: A list of Sigfox devices.
      security:
      - api_key: []
        api_token: []
      summary: List Sigfox devices.
      tags:
      - SigfoxDevice
      x-soracom-cli:
      - sigfox-devices list
      x-soracom-cli-pagination:
        request:
          param: last_evaluated_key
        response:
          header: x-soracom-next-key
  /sigfox_devices/{device_id}:
    get:
      description: Returns information about the specified Sigfox device.
      operationId: getSigfoxDevice
      parameters:
      - description: Device ID of the target Sigfox device.
        in: path
        name: device_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigfoxDevice'
          description: The Sigfox device's detailed information.
        '404':
          description: The specified Sigfox device does not exist.
      security:
      - api_key: []
        api_token: []
      summary: Get Sigfox device.
      tags:
      - SigfoxDevice
      x-soracom-cli:
      - sigfox-devices get
  /sigfox_devices/{device_id}/data:
    get:
      description: 'Retrieves data that matches the specified conditions from the data sent by the specified Sigfox device
        to Harvest Data. If the data entries do not fit in one page, a URL to retrieve the next page with the same conditions
        will be included in the `link` header of the response.

        '
      operationId: getDataFromSigfoxDevice
      parameters:
      - description: ID of the Sigfox device from which to retrieve data. The ID of a Sigfox device can be obtained using
          the [SigfoxDevice:listSigfoxDevices API](#!/SigfoxDevice/listSigfoxDevices).
        in: path
        name: device_id
        required: true
        schema:
          type: string
      - description: Start time of the target period (UNIX time in milliseconds).
        in: query
        name: from
        required: false
        schema:
          type: integer
      - description: End time of the target period (UNIX time in milliseconds).
        in: query
        name: to
        required: false
        schema:
          type: integer
      - description: Sort order of data entries. Either descending order (latest data entry first) or ascending order (oldest
          data entry first).
        in: query
        name: sort
        required: false
        schema:
          default: desc
          enum:
          - desc
          - asc
          type: string
      - description: Maximum number of data entries to retrieve (1 to 1000). The default is `10`.
        in: query
        name: limit
        required: false
        schema:
          maximum: 1000
          minimum: 1
          type: integer
      - description: Timestamp of the last data entry retrieved on the previous page. By specifying this parameter, the list
          starting from the next data entry can be obtained.
        in: query
        name: last_evaluated_key
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DataEntry'
                type: array
          description: A list of data entries.
      security:
      - api_key: []
        api_token: []
      summary: Retrieves data sent from a Sigfox device to Harvest Data
      tags:
      - SigfoxDevice
      x-soracom-cli:
      - sigfox-devices get-data
      x-soracom-cli-pagination:
        request:
          param: last_evaluated_key
        response:
          header: x-soracom-next-key
    post:
      description: Sends data to the specified Sigfox device. The data will be stored until the device sends a next uplink
        message. If another message destined for the same Sigfox device ID is already waiting to be sent, the existing message
        will be discarded, and the new message will be sent instead.
      operationId: sendDataToSigfoxDevice
      parameters:
      - description: ID of the recipient device.
        in: path
        name: device_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SigfoxData'
        description: Binary data encoded as a hexadecimal string. Length of original binary data must be 8 octets (16 characters
          when encoded as a hexadecimal string).
        required: true
      responses:
        '202':
          description: Data has been received by server and waiting for the recipient device to retrieve.
        '404':
          description: No such device found.
      security:
      - api_key: []
        api_token: []
      summary: Send data to a Sigfox device.
      tags:
      - SigfoxDevice
      x-soracom-cli:
      - sigfox-devices send-data
  /sigfox_devices/{device_id}/disable_termination:
    post:
      description: Disables termination of specified Sigfox device.
      operationId: disableTerminationOnSigfoxDevice
      parameters:
      - description: Device ID of the target Sigfox device.
        in: path
        name: device_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigfoxDevice'
          description: The Sigfox device's detailed information after the update.
        '404':
          description: The specified Sigfox device does not exist.
      security:
      - api_key: []
        api_token: []
      summary: Disable Termination of Sigfox device.
      tags:
      - SigfoxDevice
      x-soracom-cli:
      - sigfox-devices disable-termination
  /sigfox_devices/{device_id}/enable_termination:
    post:
      description: Enables termination of specified Sigfox device.
      operationId: enableTerminationOnSigfoxDevice
      parameters:
      - description: Device ID of the target Sigfox device.
        in: path
        name: device_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigfoxDevice'
          description: The Sigfox device's detailed information after the update.
        '404':
          description: The specified Sigfox device does not exist.
      security:
      - api_key: []
        api_token: []
      summary: Enable Termination of Sigfox device.
      tags:
      - SigfoxDevice
      x-soracom-cli:
      - sigfox-devices enable-termination
  /sigfox_devices/{device_id}/register:
    post:
      description: Registers a Sigfox device.
      operationId: registerSigfoxDevice
      parameters:
      - description: Device ID of the target Sigfox device to register.
        in: path
        name: device_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SigfoxRegistrationRequest'
        description: Sigfox device registration request.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigfoxDevice'
          description: Sigfox device successfully registered.
        '400':
          description: PAC code is missing.
      security:
      - api_key: []
        api_token: []
      summary: Registers a Sigfox device.
      tags:
      - SigfoxDevice
      x-soracom-cli:
      - sigfox-devices register
  /sigfox_devices/{device_id}/set_group:
    post:
      description: Adds a Sigfox device to a Sigfox group.
      operationId: setSigfoxDeviceGroup
      parameters:
      - description: ID of the target Sigfox device. The ID of a Sigfox device can be obtained using the [SigfoxDevice:listSigfoxDevices
          API](#!/SigfoxDevice/listSigfoxDevices).
        in: path
        name: device_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetGroupRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigfoxDevice'
          description: Detailed information of the updated Sigfox device.
        '404':
          description: The specified Sigfox device does not exist.
      security:
      - api_key: []
        api_token: []
      summary: Adds a Sigfox device to a Sigfox group
      tags:
      - SigfoxDevice
      x-soracom-cli:
      - sigfox-devices set-group
  /sigfox_devices/{device_id}/tags:
    put:
      description: Inserts/updates tags for the specified Sigfox device.
      operationId: putSigfoxDeviceTags
      parameters:
      - description: Device ID of the target Sigfox device.
        in: path
        name: device_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/TagUpdateRequest'
              type: array
        description: Array of tags to be inserted/updated.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigfoxDevice'
          description: The Sigfox device's detailed information after the update.
        '404':
          description: The specified Sigfox device does not exist.
      security:
      - api_key: []
        api_token: []
      summary: Bulk Insert or Update Sigfox device Tags.
      tags:
      - SigfoxDevice
      x-soracom-cli:
      - sigfox-devices put-tags
  /sigfox_devices/{device_id}/tags/{tag_name}:
    delete:
      description: Deletes a tag from the specified Sigfox device.
      operationId: deleteSigfoxDeviceTag
      parameters:
      - description: Device ID of the target Sigfox device.
        in: path
        name: device_id
        required: true
        schema:
          type: string
      - description: Tag name to be deleted. (This will be part of a URL path, so it needs to be percent-encoded. In JavaScript,
          specify the name after it has been encoded using encodeURIComponent().)
        in: path
        name: tag_name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Deletion of specified tag complete.
        '404':
          description: The specified Sigfox device or the tag does not exist.
      security:
      - api_key: []
        api_token: []
      summary: Delete Sigfox device Tag.
      tags:
      - SigfoxDevice
      x-sam-operationId: deleteTag
      x-soracom-cli:
      - sigfox-devices delete-tag
  /sigfox_devices/{device_id}/terminate:
    post:
      description: Terminates the specified Sigfox device.
      operationId: terminateSigfoxDevice
      parameters:
      - description: Device ID of the target Sigfox device.
        in: path
        name: device_id
        required: true
        schema:
          type: string
      - description: If the Sigfox device is deleted immediately.
        in: query
        name: delete_immediately
        required: false
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigfoxDevice'
          description: The Sigfox device's detailed information after the update.
        '404':
          description: The specified Sigfox device does not exist.
      security:
      - api_key: []
        api_token: []
      summary: Terminate Sigfox device.
      tags:
      - SigfoxDevice
      x-soracom-cli:
      - sigfox-devices terminate
  /sigfox_devices/{device_id}/unset_group:
    post:
      description: Removes a Sigfox device from a Sigfox group.
      operationId: unsetSigfoxDeviceGroup
      parameters:
      - description: ID of the target Sigfox device. The ID of a Sigfox device can be obtained using the [SigfoxDevice:listSigfoxDevices
          API](#!/SigfoxDevice/listSigfoxDevices).
        in: path
        name: device_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigfoxDevice'
          description: Detailed information of the updated Sigfox device.
        '404':
          description: The specified Sigfox device does not exist.
      security:
      - api_key: []
        api_token: []
      summary: Removes a Sigfox device from a Sigfox group
      tags:
      - SigfoxDevice
      x-soracom-cli:
      - sigfox-devices unset-group
tags:
- description: '[Soracom Air for Sigfox](/en/docs/air-for-sigfox/) devices'
  name: SigfoxDevice
components:
  schemas:
    TagUpdateRequest:
      properties:
        tagName:
          type: string
        tagValue:
          type: string
      required:
      - tagName
      - tagValue
      type: object
    LastSeen:
      properties:
        rssi:
          format: int32
          type: integer
        snr:
          format: int32
          type: integer
        time:
          format: date-time
          type: string
      type: object
    SigfoxRegistrationRequest:
      properties:
        registrationSecret:
          type: string
        tags:
          additionalProperties:
            type: string
          type: object
      type: object
    SetGroupRequest:
      properties:
        groupId:
          description: Group ID. The group ID can be obtained using the [Group:listGroups API](#!/Group/listGroups).
          type: string
      type: object
    DataEntry:
      properties:
        category:
          type: string
        content:
          type: string
        contentType:
          type: string
        resourceId:
          type: string
        resourceType:
          enum:
          - Subscriber
          - LoraDevice
          - Sim
          - SigfoxDevice
          - Device
          - SoraCam
          type: string
        time:
          format: int64
          type: integer
      type: object
    SigfoxDevice:
      properties:
        device_id:
          type: string
        groupId:
          type: string
        lastModifiedTime:
          format: date-time
          type: string
        lastSeen:
          $ref: '#/components/schemas/LastSeen'
        operatorId:
          type: string
        status:
          enum:
          - active
          - ready
          - terminated
          - instock
          type: string
        tags:
          additionalProperties:
            type: string
          type: object
        terminationEnabled:
          default: false
          type: boolean
      type: object
    SigfoxData:
      properties:
        data:
          type: string
      type: object
  securitySchemes:
    api_key:
      description: 'API key for authentication. Obtain this from the Soracom User Console or via the Auth API.

        Required in combination with an API token for all authenticated requests.

        '
      in: header
      name: X-Soracom-API-Key
      type: apiKey
    api_token:
      description: 'API token for authentication. This token has an expiration time and must be refreshed periodically.

        Required in combination with an API key for all authenticated requests.'
      in: header
      name: X-Soracom-Token
      type: apiKey