REST APIs

Event Capture

The following APIs allow the API client to capture an event from a camera from past or current times.

The Event capture process is asynchronous. The Event Capture API returns a request ID for the Event Capture request. API client can use this request ID to poll your Event capture status using the Event Capture Status API or subscribe to our Webhooks to receive the Event capture status asynchronously.

Request Execution Behavior

The Event capture request can be served immediately or queued based on the camera state.

  • Online and Not in the Parking mode - The Event will be captured immediately when the Camera is online and not in the parking mode.
  • Online but in the parking mode - The Event capture request will be queued for the time specified by the queueTime parameter. Our cloud will wake the camera from the parking mode and execute the Event Capture request.
  • Offline - The Event capture request will be queued. Once the camera comes back online, the request will be executed.

Queue Behaviour

  • Our cloud will queue at most 16 Event Capture requests per camera.
  • The default queue time is 24 hours (1440 minutes). API clients can set preferred queue times from 1 minute to 5000 minutes. The request will expire after this time is over. In this scenario, our cloud will send a Webhook notification with the status EXPIRED.
  • Our service iterates the queue every 10 minutes to execute or expire an Event capture request in the queue.

Naming Strategy of the Captured Event

The Captured Event will be named in three different ways.

  • Using referenceEventId -API clients can include a reference Event ID in the request's referenceEventId field. If the reference Event is from the Smarter AI System, the captured Event will be named by combining the caller tenant name with the original Event name. For example, if the tenant is "Birds Nest" and the API client uses a "Tailgating" Event ID, the captured Event will be named "Birds.Nest.Tailgating". This method takes top priority.
  • Using referenceEventName - API clients can enter an Event name in the request's referenceEventName field. The captured Event will use your tenant name as a prefix followed by the referenceEventName formatted according to Smarter AI's conventions. For example, if your tenant is "Birds Nest" and you input "Door Closed," the captured Event name will be "Birds.Nest.Door.Closed". This strategy has a second priority.
  • Default name -The event name will combine the tenant name with the suffix "System Generated." For example, if the tenant is "Birds Nest," the name will be "Birds.Nest.System.Generated." This method has the lowest priority.

Event Capture status

Event Capture request can have the following status throughout its lifecycle.

  • SENT - The Event Capture request is sent to the Camera.
  • ONGOING - The Camera has started processing the Event capture request. The Event has been created, and the Camera is uploading media.
  • COMPLETED - The Event is fully available now. You can play the Event.
  • FAIL - The Event Capture Request has failed. Check the failureReason field for details in the Recording Request status API or Webhook message.
  • DUPLICATE - An Event Capture request for the same time range for the same Camera exists. The Service will return the duplicate request ID in the requestId field over the Recording Request status API or Webhook message.
  • QUEUED - The request has been queued to execute later.
  • EXPIRED - The request was QUEUED, but the queue time is over.