The BitRefine Heads API is served by the Manager. The API allows developers to retrieve data from the platform’s System DB. In general, the BitRefine Heads API uses HTTP GET requests with JSON responses.

Authentication

Request authentication is performed via APIKey. API requests without authentication will fail. User needs to request an identity token from the /api/v1/auth endpoint.

Request POST /api/v1/auth

Provide valid login/password to receive your token.

curl -v -X POST \
    'http://192.168.0.50:8005/api/v1/auth' \
    -H 'content-type: application/json' \
    -d '{"username": "admin", "password": "12345"}'

Response JSON

{
  "APIKey":"62c587f46ae3c08671d09472"
}

Use this API key every time you send API request.

curl -v -X GET \
  'http://192.168.0.50:8005/api/v1/servers' \
  -H 'APIKey: 62c587f46ae3c08671d09472'

Inspect Heads

Return detailed information about all the Heads controlled by the Manager.

Request GET /api/v1/servers

No parameters accepted.

Response JSON

{
    "servers": [
        {
            "server_id": "4791-422e-9232",
            "description": "",
            "ip_addresses": "192.168.0.26 / HK Office",
            "last_status": "STANDBY",
            "name": "Jetson 4",
            "parameters": {
                "Head's level": "L3",
                "Restart policy": "no",
                "Forced modules update": true,
                "Description": "",
                "Server ID": "27d9-45fc-bad9",
                "Update modules": "always",
                "Log level": "ERROR",
                "Storage size (Mb)": "2000"
            },
            "type": "Server",
            "status": "STANDBY",
            "inputs_models": "Sources: 4 / Models: 2 / Pipelines: 4 active of 12"
        },
        {
            "server_id": "c5aa-4b1f-a8b9",
            "description": "",
            "ip_addresses": "192.168.0.38 / HK Remote",
            "last_status": "STANDBY",
            "name": "Head 3",
            "parameters": {
                "Head's level": "default",
                "Storage size (Mb)": 100,
                "Restart policy": "on-failure",
                "Update modules": "new_version",
                "Log level": "ERROR",
                "Description": "",
                "Server ID": "c5aa-4b1f-a8b9"
            },
            "type": "Server",
            "status": "OFFLINE",
            "inputs_models": "Sources: 3 / Models: 2 / Pipelines: 3 active of 5"
        }
    ]
}

List pipelines

Return a list of pipelines with their descriptions and status information.

Request GET /api/v1/pipelines

Available query parameters:

  • server_id : (Required) Return pipelines that belong to this Head.

Response JSON

{
    "pipelines": [
        {
            "pipeline_id": "1st_circle-4bbf09c7",
            "name": "Circle_10",
            "server_id": "27d9-45fc-bad9",
            "description": "Circle_CT0 > 10 processing elements.",
            "last_status": "stop",
            "source": "Circle_10-193231ee"
        },
        {
            "pipeline_id": "nvr_ch2-8acce645",
            "name": "nvr_ch2",
            "server_id": "27d9-45fc-bad9",
            "description": "nvr_ch2 > 8 processing elements.",
            "last_status": "stop",
            "source": "Video-6411064b"
        },
        {
            "pipeline_id": "Batch-of-videofiles-3df66b83",
            "name": "Batch of videofiles",
            "server_id": "27d9-45fc-bad9",
            "description": "Batch of videofiles > 3 processing elements.",
            "last_status": "run",
            "source": "Batch-of-videofiles-646133f5"
        },
        {
            "pipeline_id": "cctv_store-baa5b6ad",
            "name": "cctv_store_1",
            "server_id": "27d9-45fc-bad9",
            "description": "cctv_store > 8 processing elements.",
            "last_status": "run",
            "source": "cctv_store-f222304e"
        }
    ]
}

List events

Return a list of event IDs. Note that the request doesn't return any details about the events.

Request GET /api/v1/events

Available query parameters:

  • start : Only return events since this time, as a UNIX timestamp 1137013177.0. Default is: 24h ago from Now.
  • stop : Only return events before this time, as a UNIX timestamp. Default is: Now.
  • server_id : Only return events generated by this server.
  • pipeline_name : Only return events generated by this pipeline.
  • object_name : Only return events that have this object class.
  • event : Only return events of this type.
  • limit : Limit number of returned results. Default is 300000.
  • ack_status : Only return events generated by this server. Options are confirm or reject.
  • object_props : Add objects properties as a filter, encoded as JSON. For example, {"gender": "F"} will return only females.
  • event_props : Add events properties as a filter, encoded as JSON. For example, {"direction": "backward"} will return only objects that crossed lines backward.

Response JSON

{
    "total": 145,
    "events": [
        ["62c3fb267c8df0d85839b056", "2022-07-05 08:49:40.708000"],
        ["62c3fbc97c8df0d85839b560", "2022-07-05 08:52:23.752000"],
        ["62c404237c8df0d85839ca64", "2022-07-05 09:28:03.441000"],
        ["62c404247c8df0d85839cd4c", "2022-07-05 09:28:04.085000"],
        ...
        ["6305e6c230e0c320bc9c3a14", "2022-08-24 08:52:18.140000"],
        ["6305e6c330e0c320bc9c3aad", "2022-08-24 08:52:19.019000"]
    ]
}

Get event details

Return detailed information about an event.

Request GET /api/v1/events/{EVENT_ID}

Available query parameters:

  • osd : The response will contain link to the event's reference snapshot. If OSD parameter is 0 the image will not contain any OSD information such as bounding boxes.

Response JSON

{
    "_id": "62d6694741104f6c14c458c4",
    "timestamp": "2022-02-11T08:20:22.195000",
    "head_name": "Head A4",
    "pipeline_name": "CAM 15-4",
    "event": "best_shot",
    "confidence": 0.9228585720062256,
    "properties": {},
    "server_id": "27d9-45fc-bad9",
    "image": "/arch_img?server=27d9-45fc-bad9&doc=62d6694741104f6c14c458c4&sp=873732112&ep=873783697&osd=0",
    "stream": "/arch_vid?server=27d9-45fc-bad9&sp=873783697&ep=895656959",
    "objects": [
        {
            "object_name": "truck",
            "confidence": 0.9228585720062256,
            "bbox": [[[340, 471], [899, 471], [899, 1119], [340, 1119]]],
            "track": [[598, 1244], [598, 1216], [604, 1176], [618, 1145], [619, 1119]],
            "track_length": 5,
            "properties": {},
            "bbox_color": [255, 0, 191]
        }
    ]
}

Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call.

  • 200 Success
  • 400 Bad request
  • 401 Not authorized
  • 404 Not found
  • 500 Server error