openapi: 3.2.0
info:
  title: Live Objects REST API Guide Decoders - CSV API
  description: API description for Live Objects service
  contact:
    name: Live Objects Support
    url: https://liveobjects.orange-business.com/#/cms/support
  version: 2026.7.0
servers:
- url: https://liveobjects.orange-business.com
security:
- X-API-KEY: []
  OAuth2.0: []
tags:
- name: Decoders - CSV
  description: CSV decoder provisioning
paths:
  /api/v0/decoders/csv/{decoderId}:
    get:
      tags:
      - Decoders - CSV
      summary: Retrieve a CSV decoder
      description: 'A data decoder allows you to decode your data message payload into a json format. When an encoding is defined in the device interface or in the data message, the decoder will be be applied and the data message will be updated accordingly. A CSV decoder handles payload with CSV format.<br/><br/>Restricted to API keys with at least one of the following roles: DATA_PROCESSING_R.'
      operationId: getCsvDecoder
      parameters:
      - name: decoderId
        in: path
        description: id of the CSV decoder to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          description: CSV decoder
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CsvPayloadDescription'
    put:
      tags:
      - Decoders - CSV
      summary: Update a CSV decoder
      description: 'A data decoder allows you to decode your data message payload into a json format. When an encoding is defined in the device interface or in the data message, the decoder will be be applied and the data message will be updated accordingly. A CSV decoder handles payload with CSV format.<br/><br/>Usage of this API will be reported in your access log under ''data_decoder'' category.<br/><br/>Restricted to API keys with at least one of the following roles: DATA_PROCESSING_W.'
      operationId: updateCsvDecoder
      parameters:
      - name: decoderId
        in: path
        description: id of the csv decoder to update
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CsvPayloadDescription'
        required: true
      responses:
        '200':
          description: Csv decoder updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CsvPayloadDescription'
    delete:
      tags:
      - Decoders - CSV
      summary: Delete a CSV decoder
      description: 'A data decoder allows you to decode your data message payload into a json format. When an encoding is defined in the device interface or in the data message, the decoder will be be applied and the data message will be updated accordingly. A CSV decoder handles payload with CSV format.<br/><br/>Usage of this API will be reported in your access log under ''data_decoder'' category.<br/><br/>Restricted to API keys with at least one of the following roles: DATA_PROCESSING_W.'
      operationId: deleteCsvDecoder
      parameters:
      - name: decoderId
        in: path
        description: id of the CSV decoder to delete
        required: true
        schema:
          type: string
      responses:
        '204':
          description: CSV decoder deleted
  /api/v0/decoders/csv/{decoderId}/enabled:
    put:
      tags:
      - Decoders - CSV
      summary: Activate or deactivate a CSV decoder
      description: 'A data decoder allows you to decode your data message payload into a json format. When an encoding is defined in the device interface or in the data message, the decoder will be be applied and the data message will be updated accordingly. A CSV decoder handles payload with CSV format. A non enabled decoder will not be applied on data messages. This allows you to temporarily disable a decoder without deleting it.<br/><br/>Usage of this API will be reported in your access log under ''data_decoder'' category.<br/><br/>Restricted to API keys with at least one of the following roles: DATA_PROCESSING_W.'
      operationId: activateCsvDecoder
      parameters:
      - name: decoderId
        in: path
        description: id of the CSV decoder to activate or deactivate
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
              description: true to activate, false otherwise
        required: true
      responses:
        '204':
          description: Update request has been accepted.
  /api/v0/decoders/csv:
    get:
      tags:
      - Decoders - CSV
      summary: Retrieve the list of CSV decoders filtered by tags
      description: 'A data decoder allows you to decode your data message payload into a json format. When an encoding is defined in the device interface or in the data message, the decoder will be be applied and the data message will be updated accordingly. A CSV decoder handles payload with CSV format.<br/><br/>Restricted to API keys with at least one of the following roles: DATA_PROCESSING_R.'
      operationId: listCsvDecoders
      parameters:
      - name: tags
        in: query
        description: filter on decoders containing at least one of these tags
        required: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: list of CSV decoders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CsvPayloadDescription'
    post:
      tags:
      - Decoders - CSV
      summary: Create a CSV decoder
      description: 'A data decoder allows you to decode your data message payload into a json format. When an encoding is defined in the device interface or in the data message, the decoder will be be applied and the data message will be updated accordingly. A CSV decoder handles payload with CSV format. The number of csv decoders is limited to 100.<br/><br/>Usage of this API will be reported in your access log under ''data_decoder'' category.<br/><br/>Restricted to API keys with at least one of the following roles: DATA_PROCESSING_W.'
      operationId: registerCsvDecoder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CsvPayloadDescription'
        required: true
      responses:
        '201':
          description: Csv decoder created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CsvPayloadDescription'
  /api/v0/decoders/csv/test:
    post:
      tags:
      - Decoders - CSV
      summary: Test a CSV decoder format with an encoded payload
      description: 'A data decoder allows you to decode your data message payload into a json format. When an encoding is defined in the device interface or in the data message, the decoder will be be applied and the data message will be updated accordingly. A CSV decoder handles payload with CSV format. This API allows you to test the CSV decoder format with an encoded payload. It can be used for troubleshooting or for testing the decoding result before applying it on data messages. The response contains the decoded data as Json if the decoding is successful.<br/><br/>Restricted to API keys with at least one of the following roles: DATA_PROCESSING_R.'
      operationId: test
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CsvPayloadDescriptionTestRequest'
        required: true
      responses:
        '200':
          description: Test has been performed. Response body contains decoded data as Json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayloadDescriptionTestResult'
components:
  schemas:
    CsvPayloadDescription:
      type: object
      description: binary decoder provisioning information
      properties:
        id:
          type: string
          description: id of the decoder. Should be null when used for POST. Required for update.
        encoding:
          type: string
          description: unique decoder name. Will be used to trigger the decoding function. To be applied, it must match exactly the data message 'metadata.encoding' field or the 'encoding' property of the device's interface.
        enabled:
          type: boolean
          description: decoder activation. Default is false. If disabled, the decoder will not be applied on the data messages.
        model:
          type: string
          description: if empty, the decoded data will use the value of 'model' field from encoded data. If set, this value will be used to override 'model' field in decoded data.
        type:
          type: string
          description: 'decoder type : csv, binary, javascript, javascript-split'
          readOnly: true
        template:
          type: string
          description: 'decoding result optional template. Use mustache-like format. Available mustache functions : math, toUpperCase, toLowerCase. e.g. ''{{#math}}{{temperature}} * 1.8 + 32{{/math}}''The template will be applied on the decoded result only if the decoder is enabled and the decoding is successful. If not set, the decoded result will be used as is.'
        mathEvalEnabled:
          type: boolean
          description: Applying, or not, math evaluation on templated decoded result. Default is true
        tags:
          type: array
          description: tags used for description and filtering
          items:
            type: string
        metadata:
          $ref: '#/components/schemas/PayloadDescriptionMetadata'
          description: decoder metadata. Read-only, set by the platform.
          readOnly: true
        updated:
          type: string
          description: date of the last update. ISO 8601 date time. Read-only, set by the platform.
          example: '2019-05-15T07:55:55.555Z'
          readOnly: true
        columns:
          type: array
          description: columns description for the CSV format
          items:
            $ref: '#/components/schemas/CsvColumn'
        options:
          $ref: '#/components/schemas/CsvOptions'
          description: CSV decoding options to apply
      required:
      - columns
      - enabled
      - encoding
    CsvPayloadDescriptionTestRequest:
      type: object
      description: Csv format and encoded payload on which decoding shall be performed
      properties:
        columns:
          type: array
          description: the colums description of the CSV format
          items:
            $ref: '#/components/schemas/CsvColumn'
        options:
          $ref: '#/components/schemas/CsvOptions'
          description: the CSV decoding options to apply
        csvPayload:
          type: string
          description: The encoded payload to test, in CSV format
        template:
          type: string
          description: 'The template to apply after the decoding, it can include mustache operations. e.g. ''{"tempF": {{#math}}{{temperature}} * 1.8 + 32{{/math}} }'''
        mathEvalEnabled:
          type: boolean
          description: Applying, or not, math evaluation on templated decoded result. Default is true
      required:
      - columns
      - csvPayload
    PayloadDescriptionMetadata:
      type: object
      properties:
        certified:
          type: boolean
          description: the decoder is certified for the specified encoding. Only a public decoder can be certified. The default value is false.
          readOnly: true
        certifiedSince:
          type: string
          description: date since when the decoder is certified. ISO 8601 date time.
          example: '2019-05-15T07:55:55.555Z'
          readOnly: true
    PayloadDescriptionTestResult:
      type: object
      properties:
        parsingOk:
          type: boolean
          description: indicates if the data payload can be parsed according to the data payload description
        decodingResult:
          description: the decoded data
        decodingFailureReason:
          type: string
          description: if decoding has failed, the reason why it failed
        descriptionValid:
          type: boolean
          description: 'indicates if the payload description is valid according to the type of decoding : csv, binary, js, js-split'
        templatingOK:
          type: boolean
          description: indicates if the template has been successfully applied on decoded data
    CsvColumn:
      type: object
      properties:
        name:
          type: string
          description: the name of the column that will be used as field name
          example: column1
        jsonType:
          type: string
          description: 'the json type of the value : STRING, NUMERIC, BOOLEAN'
          example: NUMERIC
      required:
      - jsonType
      - name
    CsvOptions:
      type: object
      properties:
        columnSeparator:
          type: string
          description: Character used to separate values. Default is comma ','
          example: ;
        quoteChar:
          type: string
          description: Character used for quoting values that contain column separator characters or linefeed. Default is double-quote '"'.
          example: ''''
        useEscapeChar:
          type: boolean
          description: Set to true if you want to use an escape char. Default is false.
        escapeChar:
          type: string
          description: Character used to escape values. Default is backslash '\'
          example: \
        skipWhiteSpace:
          type: boolean
          description: if set to true, it will trim the decoded values (white spaces before and after will be removed). Default is false.
        lineFeedSeparator:
          type: string
          description: Character used to separate data rows. If the message payload contains several rows, only the first one will be decoded. Default is line feed '\n'.
          example: \n
  securitySchemes:
    X-API-KEY:
      type: apiKey
      name: X-API-KEY
      in: header
    OAuth2.0:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://liveobjects.orange-business.com/api/v1/oauth2/authorize
          tokenUrl: https://liveobjects.orange-business.com/api/v1/oauth2/token
          refreshUrl: https://liveobjects.orange-business.com/api/v1/oauth2/token
          scopes:
            API_KEY_R: Read parameters and status of an API key.
            API_KEY_W: Create, modify, disable an API key.
            BOOTSTRAP_R: Read parameters and status of the LwM2M Bootstrap configurations and entries.
            BOOTSTRAP_W: Create ans modify LwM2M Bootstrap configurations and entries.
            BUS_CONFIG_R: Read config parameters of a FIFO queue.
            BUS_CONFIG_W: Create, modify a FIFO queue.
            BUS_R: Read data on the Live Objects bus. Minimum permission for the API key of an application collecting data on Live Objects in MQTT(s).
            BUS_W: Publish data on the Live Objects bus.
            CAMPAIGN_R: Read parameters and status of a massive deployment campaign on your Device Fleet.
            CAMPAIGN_W: Create, modify a campaign on your Device Fleet.
            CONNECTOR_ACCESS: Role to set on a external connector API key to allow only MQTT external connector mode
            DATA_PROCESSING_R: Read parameters and status of an event processing rule or a Data decoder.
            DATA_PROCESSING_W: Create, modify, disable an event processing rule or a Data decoder.
            DATA_R: Read the data collected by the Store Service or search into this data using the Search Service.
            DATA_W: Insert a data record to the Store Service. Minimum permission required for the API key of a device pushing data to Live Objects in HTTPS.
            DEVICE_ACCESS: Role to set on a Device API key to allow only MQTT Device mode
            DEVICE_R: Read parameters and status of a Device management.
            DEVICE_W: Create, modify, disable a Device management, send command, modify config, update resource of a Device.
            LOGS_R: Read the logs collected by the Audit Log service. This right allows users to use the Audit Log service as debugging tool.
            SETTINGS_R: Read the tenant account custom settings.
            SETTINGS_W: Create, modify tenant account custom settings.
            USER_R: Read parameters and status of a user.
            USER_W: Create, modify, disable a user.
externalDocs:
  description: Live Objects Developer Guide
  url: https://liveobjects.orange-business.com/doc/html/lo_manual_v2.html
x-examples: ''