Skip to content

REST API / OpenAPI

Compatible with: picoScan100

The REST API is the primary way to configure and control the picoScan. It is a JSON-over-HTTP interface on port 80 (or 443 with HTTPS) that mirrors the SOPASair web UI: every variable and method you see in the UI is reachable programmatically.

Base URL and JSON envelope

http[s]://<device-ip>/api/<VariableOrMethod>

Every response uses the same envelope. A status of 0 in the header means success:

{
  "header": { "status": 0, "message": "Ok" },
  "data": { "<VariableName>": <value> }
}

Reading vs. writing

Operation Method Authentication
Read a parameter GET /api/<Variable> None
Write a parameter POST /api/<Variable> Challenge-response
Call a method (reboot, defaults, teach-in, …) POST /api/<Method> Challenge-response
Binary file transfer (backup, firmware) GET/PUT /api/parameterbackup, PUT /api/update Session token

Read the current device location with GET /api/LocationName (no auth required):

{
  "header": { "status": 0, "message": "Ok" },
  "data": { "LocationName": "picoScan150 25420067" }
}

Every writable parameter follows the same pattern. The data key must match the endpoint name exactly, including capitalisation. See Authentication for the full write sequence.

A POST to a parameter only changes the in-RAM working copy. This change is lost on power-cycle until you persist it:

POST /api/WriteEeprom      # persist current RAM parameters to flash

RebootDevice also persists RAM to EEPROM before rebooting. A SoftReset or a hard power-cycle discards unsaved changes. See Integrity & checksums for how this shows up in MD5Parameters.

User levels

Writes require an authenticated user level. Only Service is enabled at the factory.

Level Factory default
Maintenance Disabled
Authorized Client Disabled
Service Enabled

Change credentials with changePassword and enable other levels with EnableUserLevel. See User levels for the activation requirement and setup guidance.

Authentication

The REST API supports two authentication methods depending on the operation type:

Method Use case Reference
Challenge-Response Writes (parameters, methods) via POST Challenge-response
Session Token Binary file transfer (backup, firmware updates) Session token

Challenge-Response Authentication

All write operations (POST) require challenge-response authentication. This mechanism ensures the client proves it knows the password using a SHA-256 hash chain, without transmitting the password itself:

  1. Request a challenge from the device
  2. Compute a hash response using the challenge nonce, password, and realm
  3. Send the authenticated request with the hash

The nonce is single-use; fetch a fresh challenge before each POST. For client libraries and automation, add a pre-request script to compute the hash automatically.

Session Token Authentication

File transfer operations (backup/restore configurations, firmware updates) use session token authentication:

  1. Authenticate once to receive a session token
  2. Use the token to upload or download files
  3. Session tokens remain valid across multiple operations

This approach is more efficient for large binary transfers compared to challenge-response hashing per request.

OpenAPI

OpenAPI (formerly Swagger) is a machine-readable specification of every REST endpoint, including paths, request and response schemas, and parameters. Feed it to a code generator to create a typed REST client in almost any language, or import it directly into a REST client to prepare every endpoint without entering URLs manually.

SICK publishes an OpenAPI description of the REST interface with each firmware. Find openapi.yaml for your device and firmware on the applicable SICK product page under Software, or through the device REST interface.

Import the OpenAPI file into Postman or Insomnia to create a ready-made endpoint collection. Because writes require challenge-response, add a collection-level pre-request script that fetches a fresh challenge and computes the response hash automatically; see Challenge Response Authentication for the algorithm.

If you see "Access Denied" on a POST in Insomnia, install the SICK challenge-response plugin so the hash is computed for you.

Download the SICK REST Insomnia plugin.

A POST may return HTTP 429 when the REST rate limit is hit; apply exponential back-off. A 401 / Access Denied error almost always means a stale nonce (fetch a new challenge per request) or a user level that is not enabled.

Sample OpenAPI descriptions for the Service interface, shipped with this guide for reference:

Always match the file to your device's actual firmware version; endpoints, parameters, and schemas change between releases.

The full endpoint reference below is rendered directly from the OpenAPI files above. Expand an endpoint to see its parameters, request body, and response schema, or use Try it out against a reachable device (writes still require challenge-response).