API section

Operations

Operations: status by id (with Prefer: wait — wait for the end), recent operations and Server-Sent Events — operation progress, scanner codes, card reads, power.

GET	`/api/v1/operations`	Recent operations
GET	`/api/v1/operations/{id}`	Operation
GET	`/api/v1/events`	Events (Server-Sent Events)

Recent operations#

GET/api/v1/operations

Newest first; the journal keeps the last 1000, including after a restart

Parameters

Name	In	Type	Description
`limit`	query	integer int32

Response 200 application/json

Array · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesarray of string
statusstring
values: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultany value
errorOperationError
3 fields · OperationError
- codestring
- messagestring
- detailsany value
warningsarray of string

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/operations'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/operations' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Operation#

GET/api/v1/operations/{id}

With the Prefer: wait=N header waits up to N seconds for completion

Parameters

Name	In	Type	Description
`id`required	path	string uuid
`Prefer`	header	string

Response 200 application/json

Fields · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesarray of string
statusstring
values: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultany value
errorOperationError
3 fields · OperationError
- codestring
- messagestring
- detailsany value
warningsarray of string

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/operations/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/operations/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Events (Server-Sent Events)#

GET/api/v1/events

event: operation, data: the operation — on every status or stage change. The token can be passed in ?access_token=

Response 200 text/event-stream

Event stream (Server-Sent Events).

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/events'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/events' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'