SkyDriver API

root

GET /

Root ping

Example request:

GET / HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    Empty object

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{}

openapi

GET /openapi.json

Endpoint for retrieving the OpenAPI spec

Example request:

GET /openapi.json HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    The OpenAPI spec

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{}

scans

POST /scans/find

Find scan manifests matching a filter

Example request:

POST /scans/find HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "filter": {},
    "include_deleted": true,
    "manifest_projection": "*"
}
Status Codes:

  • 200 OK –

    Matching manifests (possibly projected).

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "manifests": [
        {
            "scan_id": "string",
            "timestamp": 1.0,
            "is_deleted": true,
            "scanner_server_args": "string",
            "ewms_workflow_id": "string",
            "ewms_address": "string",
            "ewms_task": {},
            "priority": 1,
            "classifiers": {},
            "i3_event_id": "string",
            "event_i3live_json_dict": {},
            "event_i3live_json_dict__hash": "string",
            "event_metadata": {
                "run_id": 1,
                "event_id": 1,
                "event_type": "string",
                "mjd": 1.0,
                "is_real_event": true
            },
            "scan_metadata": {},
            "progress": {
                "summary": "string",
                "epilogue": "string",
                "tallies": {},
                "processing_stats": {
                    "start": {},
                    "runtime": {},
                    "rate": {},
                    "end": "string",
                    "finished": true,
                    "predictions": {}
                },
                "predictive_scanning_threshold": 1.0,
                "last_updated": "string",
                "start": 1,
                "end": 1
            },
            "replaced_by_scan_id": "string",
            "last_updated": 1.0
        }
    ]
}

  • 400 Bad Request –

    Bad request (argument validation failed or request-level precondition violated).

    Example response:

    HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

scan

POST /scan

Start a new scan

Example request:

POST /scan HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "docker_tag": "string",
    "scanner_server_memory_bytes": "string",
    "scanner_server_memory": "string",
    "worker_memory_bytes": "string",
    "worker_memory": "string",
    "memory": "string",
    "worker_disk_bytes": "string",
    "worker_disk": "string",
    "request_clusters": {},
    "cluster": {},
    "reco_algo": "string",
    "event_i3live_json": "string",
    "i3_event_id": "string",
    "nsides": {},
    "real_or_simulated_event": "real",
    "predictive_scanning_threshold": 1.0,
    "max_pixel_reco_time": 1,
    "debug_mode": "client-logs",
    "classifiers": {},
    "priority": 1,
    "scanner_server_env_from_user": {},
    "scanner_server_env": {},
    "manifest_projection": "*"
}
Status Codes:

  • 200 OK –

    Manifest for the newly enqueued scan (possibly projected).

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "scan_id": "string",
    "timestamp": 1.0,
    "is_deleted": true,
    "scanner_server_args": "string",
    "ewms_workflow_id": "string",
    "ewms_address": "string",
    "ewms_task": {},
    "priority": 1,
    "classifiers": {},
    "i3_event_id": "string",
    "event_i3live_json_dict": {},
    "event_i3live_json_dict__hash": "string",
    "event_metadata": {
        "run_id": 1,
        "event_id": 1,
        "event_type": "string",
        "mjd": 1.0,
        "is_real_event": true
    },
    "scan_metadata": {},
    "progress": {
        "summary": "string",
        "epilogue": "string",
        "tallies": {},
        "processing_stats": {
            "start": {},
            "runtime": {},
            "rate": {},
            "end": "string",
            "finished": true,
            "predictions": {}
        },
        "predictive_scanning_threshold": 1.0,
        "last_updated": "string",
        "start": 1,
        "end": 1
    },
    "replaced_by_scan_id": "string",
    "last_updated": 1.0
}

  • 400 Bad Request –

    Bad request (argument validation failed or request-level precondition violated).

    Example response:

    HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

POST /scan/{scan_id}/actions/rescan

Copy a scan’s request and start a new scan from it

Parameters:

  • scan_id (string) – Unique scan identifier.

Example request:

POST /scan/{scan_id}/actions/rescan HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "no_redirect": true,
    "abort_first": true,
    "replace_scan": true,
    "manifest_projection": "*"
}
Status Codes:

  • 200 OK –

    Manifest of the new (rescan) scan.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "scan_id": "string",
    "timestamp": 1.0,
    "is_deleted": true,
    "scanner_server_args": "string",
    "ewms_workflow_id": "string",
    "ewms_address": "string",
    "ewms_task": {},
    "priority": 1,
    "classifiers": {},
    "i3_event_id": "string",
    "event_i3live_json_dict": {},
    "event_i3live_json_dict__hash": "string",
    "event_metadata": {
        "run_id": 1,
        "event_id": 1,
        "event_type": "string",
        "mjd": 1.0,
        "is_real_event": true
    },
    "scan_metadata": {},
    "progress": {
        "summary": "string",
        "epilogue": "string",
        "tallies": {},
        "processing_stats": {
            "start": {},
            "runtime": {},
            "rate": {},
            "end": "string",
            "finished": true,
            "predictions": {}
        },
        "predictive_scanning_threshold": 1.0,
        "last_updated": "string",
        "start": 1,
        "end": 1
    },
    "replaced_by_scan_id": "string",
    "last_updated": 1.0
}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

POST /scan/{scan_id}/actions/add-workers

Add more EWMS workers to an ongoing scan

Parameters:

  • scan_id (string) – Unique scan identifier.

Example request:

POST /scan/{scan_id}/actions/add-workers HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "no_redirect": true,
    "n_workers": 1,
    "cluster_location": "string"
}
Status Codes:

  • 200 OK –

    New taskforce info.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "taskforce_uuid": "string",
    "n_workers": 1
}

  • 422 Unprocessable Entity –

    Request is well-formed but the scan is in a state that disallows the action.

    Example response:

    HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

  • 500 Internal Server Error –

    Internal / upstream failure (EWMS).

    Example response:

    HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

GET /scan/{scan_id}

Get a scan’s manifest and result

Parameters:

  • scan_id (string) – Unique scan identifier.

Query Parameters:

  • no_redirect (boolean) – If true, suppresses the redirect that @maybe_redirect_scan_id would otherwise issue for replaced scans.

  • include_deleted (boolean) – If true, deleted manifests/results are included.

Example request:

GET /scan/{scan_id} HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    Manifest plus result (result may be empty {} if not yet produced).

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "manifest": {
        "scan_id": "string",
        "timestamp": 1.0,
        "is_deleted": true,
        "scanner_server_args": "string",
        "ewms_workflow_id": "string",
        "ewms_address": "string",
        "ewms_task": {},
        "priority": 1,
        "classifiers": {},
        "i3_event_id": "string",
        "event_i3live_json_dict": {},
        "event_i3live_json_dict__hash": "string",
        "event_metadata": {
            "run_id": 1,
            "event_id": 1,
            "event_type": "string",
            "mjd": 1.0,
            "is_real_event": true
        },
        "scan_metadata": {},
        "progress": {
            "summary": "string",
            "epilogue": "string",
            "tallies": {},
            "processing_stats": {
                "start": {},
                "runtime": {},
                "rate": {},
                "end": "string",
                "finished": true,
                "predictions": {}
            },
            "predictive_scanning_threshold": 1.0,
            "last_updated": "string",
            "start": 1,
            "end": 1
        },
        "replaced_by_scan_id": "string",
        "last_updated": 1.0
    },
    "result": {
        "scan_id": "string",
        "skyscan_result": {},
        "is_final": true
    }
}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

DELETE /scan/{scan_id}

Abort a scan and mark manifest/result as deleted

Parameters:

  • scan_id (string) – Unique scan identifier.

Example request:

DELETE /scan/{scan_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "no_redirect": true,
    "delete_completed_scan": true,
    "manifest_projection": "*"
}
Status Codes:

  • 200 OK –

    Deleted manifest plus (possibly empty) result.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "manifest": {
        "scan_id": "string",
        "timestamp": 1.0,
        "is_deleted": true,
        "scanner_server_args": "string",
        "ewms_workflow_id": "string",
        "ewms_address": "string",
        "ewms_task": {},
        "priority": 1,
        "classifiers": {},
        "i3_event_id": "string",
        "event_i3live_json_dict": {},
        "event_i3live_json_dict__hash": "string",
        "event_metadata": {
            "run_id": 1,
            "event_id": 1,
            "event_type": "string",
            "mjd": 1.0,
            "is_real_event": true
        },
        "scan_metadata": {},
        "progress": {
            "summary": "string",
            "epilogue": "string",
            "tallies": {},
            "processing_stats": {
                "start": {},
                "runtime": {},
                "rate": {},
                "end": "string",
                "finished": true,
                "predictions": {}
            },
            "predictive_scanning_threshold": 1.0,
            "last_updated": "string",
            "start": 1,
            "end": 1
        },
        "replaced_by_scan_id": "string",
        "last_updated": 1.0
    },
    "result": {
        "scan_id": "string",
        "skyscan_result": {},
        "is_final": true
    }
}

  • 400 Bad Request –

    Bad request (argument validation failed or request-level precondition violated).

    Example response:

    HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

GET /scan/{scan_id}/manifest

Get a scan’s manifest

Parameters:

  • scan_id (string) – Unique scan identifier.

Query Parameters:

  • no_redirect (boolean) – If true, suppresses the redirect that @maybe_redirect_scan_id would otherwise issue for replaced scans.

  • include_deleted (boolean) – If true, deleted manifests/results are included.

  • projection (string) – Pipe-delimited list of Manifest field names to include, or ‘*’ for all fields. Example: ?projection=scan_id|priority|classifiers.

Example request:

GET /scan/{scan_id}/manifest HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    The scan’s manifest (possibly projected).

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "scan_id": "string",
    "timestamp": 1.0,
    "is_deleted": true,
    "scanner_server_args": "string",
    "ewms_workflow_id": "string",
    "ewms_address": "string",
    "ewms_task": {},
    "priority": 1,
    "classifiers": {},
    "i3_event_id": "string",
    "event_i3live_json_dict": {},
    "event_i3live_json_dict__hash": "string",
    "event_metadata": {
        "run_id": 1,
        "event_id": 1,
        "event_type": "string",
        "mjd": 1.0,
        "is_real_event": true
    },
    "scan_metadata": {},
    "progress": {
        "summary": "string",
        "epilogue": "string",
        "tallies": {},
        "processing_stats": {
            "start": {},
            "runtime": {},
            "rate": {},
            "end": "string",
            "finished": true,
            "predictions": {}
        },
        "predictive_scanning_threshold": 1.0,
        "last_updated": "string",
        "start": 1,
        "end": 1
    },
    "replaced_by_scan_id": "string",
    "last_updated": 1.0
}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

PATCH /scan/{scan_id}/manifest

Update scan progress / event metadata / scan metadata

Parameters:

  • scan_id (string) – Unique scan identifier.

Example request:

PATCH /scan/{scan_id}/manifest HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "progress": {
        "summary": "string",
        "epilogue": "string",
        "tallies": {},
        "processing_stats": {
            "start": {},
            "runtime": {},
            "rate": {},
            "end": "string",
            "finished": true,
            "predictions": {}
        },
        "predictive_scanning_threshold": 1.0,
        "last_updated": "string",
        "start": 1,
        "end": 1
    },
    "event_metadata": {
        "run_id": 1,
        "event_id": 1,
        "event_type": "string",
        "mjd": 1.0,
        "is_real_event": true
    },
    "scan_metadata": {}
}
Status Codes:

  • 200 OK –

    Updated manifest (full, no projection).

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "scan_id": "string",
    "timestamp": 1.0,
    "is_deleted": true,
    "scanner_server_args": "string",
    "ewms_workflow_id": "string",
    "ewms_address": "string",
    "ewms_task": {},
    "priority": 1,
    "classifiers": {},
    "i3_event_id": "string",
    "event_i3live_json_dict": {},
    "event_i3live_json_dict__hash": "string",
    "event_metadata": {
        "run_id": 1,
        "event_id": 1,
        "event_type": "string",
        "mjd": 1.0,
        "is_real_event": true
    },
    "scan_metadata": {},
    "progress": {
        "summary": "string",
        "epilogue": "string",
        "tallies": {},
        "processing_stats": {
            "start": {},
            "runtime": {},
            "rate": {},
            "end": "string",
            "finished": true,
            "predictions": {}
        },
        "predictive_scanning_threshold": 1.0,
        "last_updated": "string",
        "start": 1,
        "end": 1
    },
    "replaced_by_scan_id": "string",
    "last_updated": 1.0
}

  • 400 Bad Request –

    Bad request (argument validation failed or request-level precondition violated).

    Example response:

    HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

GET /scan/{scan_id}/i3-event

Get a scan’s underlying i3 event payload

Parameters:

  • scan_id (string) – Unique scan identifier.

Example request:

GET /scan/{scan_id}/i3-event HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    Wrapped i3 event payload.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "i3_event": {}
}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

GET /scan/{scan_id}/result

Get a scan’s persisted result

Parameters:

  • scan_id (string) – Unique scan identifier.

Query Parameters:

  • no_redirect (boolean) – If true, suppresses the redirect that @maybe_redirect_scan_id would otherwise issue for replaced scans.

  • include_deleted (boolean) – If true, deleted manifests/results are included.

Example request:

GET /scan/{scan_id}/result HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    The scan’s result (empty {} if not yet produced).

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "scan_id": "string",
    "skyscan_result": {},
    "is_final": true
}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

PUT /scan/{scan_id}/result

Persist a scan’s result

Parameters:

  • scan_id (string) – Unique scan identifier.

Example request:

PUT /scan/{scan_id}/result HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "skyscan_result": {},
    "is_final": true
}
Status Codes:

  • 200 OK –

    Persisted result (or {} if skyscan_result was falsy).

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "scan_id": "string",
    "skyscan_result": {},
    "is_final": true
}

  • 400 Bad Request –

    Bad request (argument validation failed or request-level precondition violated).

    Example response:

    HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

GET /scan/{scan_id}/status

Get a scan’s status

Parameters:

  • scan_id (string) – Unique scan identifier.

Example request:

GET /scan/{scan_id}/status HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    Aggregated scan status.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "scan_state": "string",
    "is_deleted": true,
    "ewms_deactivated": "string",
    "scan_complete": true,
    "scanner_server_logs": {
        "url": "string"
    },
    "ewms_workforce": {}
}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

GET /scan/{scan_id}/logs

Get a scan’s log URLs

Parameters:

  • scan_id (string) – Unique scan identifier.

Example request:

GET /scan/{scan_id}/logs HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    Log URL(s) for the scan.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "scanner_server": {
        "url": "string"
    }
}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

scan-request

GET /scan-request/{scan_id}

Get the persisted scan-request object for a scan

Parameters:

  • scan_id (string) – Unique scan identifier.

Example request:

GET /scan-request/{scan_id} HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    The scan-request object originally used to start the scan.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "scan_id": "string",
    "rescan_ids": [
        "string"
    ],
    "docker_tag": "string",
    "scanner_server_memory_bytes": "string",
    "reco_algo": "string",
    "nsides": {},
    "real_or_simulated_event": "real",
    "predictive_scanning_threshold": 1.0,
    "classifiers": {},
    "request_clusters": {},
    "worker_memory_bytes": "string",
    "worker_disk_bytes": "string",
    "max_pixel_reco_time": 1,
    "priority": 1,
    "debug_mode": [
        "string"
    ],
    "i3_event_id": "string",
    "scanner_server_env_from_user": {}
}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

backlog

GET /scans/backlog

List all scan IDs currently on the backlog

Example request:

GET /scans/backlog HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    All scan backlog entries.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "entries": [
        {
            "scan_id": "string",
            "timestamp": 1.0,
            "pickled_k8s_job": "string",
            "priority": 1,
            "pending_timestamp": 1.0,
            "next_attempt": 1
        }
    ]
}

ewms

GET /scan/{scan_id}/ewms/workflow-id

Get a scan’s EWMS workflow id

Parameters:

  • scan_id (string) – Unique scan identifier.

Example request:

GET /scan/{scan_id}/ewms/workflow-id HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    EWMS workflow id info.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "workflow_id": "string",
    "requested_ewms_workflow": true,
    "eligible_for_ewms": true,
    "ewms_address": "string"
}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

POST /scan/{scan_id}/ewms/workflow-id

Assign a scan’s EWMS workflow id

Parameters:

  • scan_id (string) – Unique scan identifier.

Example request:

POST /scan/{scan_id}/ewms/workflow-id HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "workflow_id": "string",
    "ewms_address": "string"
}
Status Codes:

  • 200 OK –

    Updated manifest (as a raw dict).

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "scan_id": "string",
    "timestamp": 1.0,
    "is_deleted": true,
    "scanner_server_args": "string",
    "ewms_workflow_id": "string",
    "ewms_address": "string",
    "ewms_task": {},
    "priority": 1,
    "classifiers": {},
    "i3_event_id": "string",
    "event_i3live_json_dict": {},
    "event_i3live_json_dict__hash": "string",
    "event_metadata": {
        "run_id": 1,
        "event_id": 1,
        "event_type": "string",
        "mjd": 1.0,
        "is_real_event": true
    },
    "scan_metadata": {},
    "progress": {
        "summary": "string",
        "epilogue": "string",
        "tallies": {},
        "processing_stats": {
            "start": {},
            "runtime": {},
            "rate": {},
            "end": "string",
            "finished": true,
            "predictions": {}
        },
        "predictive_scanning_threshold": 1.0,
        "last_updated": "string",
        "start": 1,
        "end": 1
    },
    "replaced_by_scan_id": "string",
    "last_updated": 1.0
}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

GET /scan/{scan_id}/ewms/workforce

Get a scan’s EWMS workforce statuses

Parameters:

  • scan_id (string) – Unique scan identifier.

Example request:

GET /scan/{scan_id}/ewms/workforce HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    Workforce status object (shape defined by EWMS).

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}

GET /scan/{scan_id}/ewms/taskforces

Get a scan’s EWMS taskforces (condor submissions)

Parameters:

  • scan_id (string) – Unique scan identifier.

Example request:

GET /scan/{scan_id}/ewms/taskforces HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    Taskforce info objects.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "taskforces": [
        {}
    ]
}

  • 404 Not Found –

    Not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "string",
    "reason": "string",
    "message": "string"
}