Detections API

API v1

Overview

This API provides access to detection events. The endpoint retrieves detection events provided by Cerrion. Users can filter events by a timestamp.

Endpoint

GET /api/v1/detections

Retrieves a list of detection events for a given project. Optionally, results can be filtered using the since query parameter.

Request

• URL: /api/v1/detections
• Method: GET
• Authentication: Bearer token is required. Include the token in the request header.

Query Parameters:

• since (optional): A timestamp in ISO 8601 format to filter events created after the specified date. If not provided, events from the last 10 days will be returned.
• updated_at (optional): A timestamp in ISO 8601 format to filter events updated after the specified date.

Example Request:

curl 'https://YOUR-PROJECT.cerrion.com/api/v1/detections?since=2025-05-10T00:00:00Z' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response

Returns a list of detection events. Each event contains the following fields:

Response Fields:

• event_id (string): Unique identifier for the event.
• line_name (string): Production line identifier.
• roi_name (string): Region of interest where the event occurred.
• roi_title (string): Title of the region of interest.
• roi_api_name (string): Custom API name of the region of interest.
• label_name (string): Detailed or general label for the event.
• label_title (string): Title of the label, same as on dashboard.
• detected_at (string): The timestamp of when the event was detected (in UTC).
• updated_at (string): The timestamp of when the event was last updated (in UTC).
• duration_seconds (float): Duration of the event in seconds.
• downtime_seconds (float): Downtime duration of the event in seconds.

Example Response:

[
  {
    "event_id": "b42c96db-b1c5-44dd-b493-088fbfa68aa7",
    "line_name": "C-2",
    "roi_name": "C-2_7",
    "roi_title": "Section 7",
    "label_name": "missing_bottles_in_pusher",
    "label_title": "Missing Bottles",
    "detected_at": "2024-10-16T15:46:56+00:00",
    "updated_at": "2024-10-16T15:47:54+00:00",
    "duration_seconds": 32.8,
    "downtime_seconds": 40.4
  }
]

Error Response

If the since parameter is invalid, the API returns a 400 error:

{
  "code": 400,
  "message": "Invalid 'since' parameter"
}

GET /api/v1/video

Retrieves a video of the detection event.

Request

• URL: /api/v1/video
• Method: GET
• Authentication: Bearer token is required.

Query Parameters:

• event_id (required): The unique identifier of the event.

Example Request:

curl 'https://YOUR-PROJECT.cerrion.com/api/v1/video?event_id=b42c96db-b1c5-44dd-b493-088fbfa68aa7' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --output video.mp4