SCscanopy
Discoveries
internal

Receive discovery progress from daemon

Changed on

Internal endpoint for daemons to report discovery progress.

post/api/v1/discoveries/{session_id}/update

Request

  • Base URL
    https://app.scanopy.net
  • URL
    https://app.scanopy.net/api/v1/discoveries/{session_id}/update
  • Auth
    API key in header Authorization

Path parameters

session_idstring uuid required

Discovery session ID

Request body

daemon_idstring uuid required

The daemon this entity refers to.

daemon_versionstring nullable

The daemon's version when the run ended. Stamped by the server at terminal, so it survives the daemon being deleted or upgraded.

discovery_idstring uuid nullable

The discovery configuration this session belongs to. Always enriched server-side; daemons do not send this field.

errorstring nullable

Failure message, when the run did not complete.

estimated_remaining_secsinteger nullable

Rough estimate of the time left, in seconds.

finished_atstring date-time nullable

When the run finished. null while it is still going.

hosts_discoveredinteger nullable

Hosts found so far.

last_update_atstring date-time nullable

When the server last heard about this run. Stamped by the server at terminal.

phase'AwaitingSnapshot' | 'Queued' | 'Pending' | 'Starting' | 'Started' | 'Scanning' | 'Complete' | 'Failed' | 'Cancelled' required
progressinteger required

Completion of the current phase, from 0 to 1.

reason'Completed' | 'UserCancelled' | 'DaemonReportedFailure' | 'StalledNoUpdates' | 'DaemonRestarted' | 'DaemonUnreachable' | 'DaemonBusy' | 'WatchdogTimeout' | 'DaemonOffline' | 'SessionSilent' | 'DaemonDroppedSession'

Why a session reached its terminal phase.

phase says that a run ended; this says why. A stall reaped by the server, a daemon that lost its state in a restart and a user pressing cancel all used to land as the same phase with no way to tell them apart afterwards, which is what made stall reports undiagnosable.

The server decides every reason except the two the daemon alone can know, see [Self::daemon_assigned]. Absent on runs recorded before this field existed.

session_idstring uuid required

The discovery run this update belongs to.

site_idstring uuid required

The site this entity belongs to.

started_atstring date-time nullable

When the run started.

Example request

{
  "warnings": [
    {
      "daemon_version": "0.18.0",
      "last_unsupported_daemon_version": "0.18.0"
    }
  ]
}

Response

Update received

dataTupleUnit

No payload. Present only so the envelope keeps its shape.

errorstring nullable

Not sent on a successful response. Failure messages arrive in an ApiErrorResponse.

successboolean required

Always true on a successful response.

Example response

{
  "meta": {
    "api_version": 1,
    "server_version": "0.19.4"
  }
}

Changes

  • c94279effef3Revision changes
    • info

      added subschema #56 to the / request property oneOf list

  • 959e33713b20Revision changes
    • info

      added the new DaemonDroppedSession enum value to the request property ////

    • info

      added the new DaemonOffline enum value to the request property ////

    • info

      added the new SessionSilent enum value to the request property ////