Skip to main content

Create or replace a Custom Device data parser

PUT 
/api/v1/orgs/{orgId}/devices/{deviceId}/data-source/data-parser

Create the device's data parser if none exists yet, or fully replace it if one does (upsert). The entire configs array is replaced. Channels omitted from the request are removed, not preserved.

Request Body

  • name (string, required): A descriptive name for the data parser.
  • description (string, optional): A detailed description of the data parser.
  • configs (array, required): Channel-based parser configuration. Each item:
    • channel (integer, required): Channel identifier. Each channel defines one mapping block.
    • description (string, optional): Description of this channel.
    • dataPacks (array, required): Mapping rules for regular values; a channel can have multiple. Each item:
      • valueObjJsonPath (string, required): JSON path to the source data field in the raw payload.
      • timePath (string, optional): JSON path to the time field. Its value must resolve to a Unix-millisecond number or an ISO 8601 string; if present but neither, ingestion of that record fails with 400. Omit to use the server's receive time. If the path is configured but the field is missing from the payload, the server time is used as a fallback.
      • dataStreamId (UUID, required): The output DataStream this rule publishes to. Must already be registered (in KV_DataStreams_V1).
    • blob (object, optional): At most one blob mapping per channel, same shape as a dataPacks entry.
    • Every dataStreamId across the whole parser (dataPacks and blob combined, across all channels) must be unique. Reusing one returns 400.

Parameters

  • orgId (string, required, path): Organization identifier.
  • deviceId (UUID, required, path): Custom device identifier.

Responses

  • 201 Created: No data parser existed yet for this device. A new one was created.
  • 200 OK: A data parser already existed. It was replaced.
  • 400 Bad Request: A channel's dataPacks/blob mappings share a duplicate dataStreamId (rejected during request validation: the outer title is the generic ValidationError, and the specific code is in validationItems[].title), or a mapping references a dataStreamId that doesn't exist (CustomDevice.DataStreamIdNotFound).
  • 417 Expectation Failed: The data parser was saved, but applying it failed. The whole change was rolled back.

Request​

Responses​

OK