Flock Safety Alerts API
The Alerts API from Flock Safety — 3 operation(s) for alerts.
OpenAPI Specification
openapi: 3.0.3
info:
title: Flock Safety API Platform (v3) Alerts API
description: Flock Safety v3 API Platform harvested from the public developer hub (docs.flocksafety.com). Combines the Device, Custom Hotlist, LPR Search, Plate Lookup, Hotlist Alerts Subscription, Geolocation, CAD, Inbound Alerts, and Vehicle Detections Ingest APIs. OAuth2 client_credentials (machine) and authorization_code (user) flows against api.flocksafety.com.
version: 3.0.0
contact:
name: Flock Safety Developer Hub
url: https://docs.flocksafety.com/
servers:
- url: https://api.flocksafety.com/api/v3
description: Production
- url: https://dev-api.flocksafety.com/api/v3
description: Development sandbox (at Flock discretion)
tags:
- name: Alerts
paths:
/alerts/{alertId}:
get:
summary: Fetching a single Alert
description: Fetches an existing alert
tags:
- Alerts
security:
- bearerAuth: []
parameters:
- in: path
name: alertId
schema:
type: string
required: true
description: The ID of the alert that will be fetched.
responses:
'200':
description: Successfully fetched single alert.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericAlert'
example:
Generic Alert:
value:
id: 00000000-0000-0000-0000-000000000000
createdAt: '2023-12-31T23:59:59.999999Z'
updatedAt: '2023-12-31T23:59:59.999999Z'
vendorId: 00000000-0000-0000-0000-000000000000
vendorName: Example Vendor
status: closed
type: other
subType: traffic-accident
title: Traffic Accident
description: Traffic Accident at 456 State St
priority: 3
eventTime: '2023-12-31T23:59:59.999999Z'
subjectId: 00000000-0000-0000-0000-000000000000
ttl: 600
location: null
attachments:
- type: link
name: Accident link
url: https://example/links/00000000-0000-0000-0000-000000000000
metadata:
foo: bar
'401':
description: The provided token is either expired or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: The token is either expired or invalid.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: alert not found
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Throttled
put:
summary: Updating an Alert
description: Updates an existing alert displayed in FlockOS
tags:
- Alerts
security:
- bearerAuth: []
parameters:
- in: path
name: alertId
schema:
type: string
required: true
description: The ID of the alert that will be updated.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GenericAlert'
example:
Generic Alert:
value:
type: other
subType: traffic-accident
title: Updated Traffic Accident
description: Traffic Accident at 456 State St
priority: 3
eventTime: '2023-12-31T23:59:59.999999Z'
subjectId: 00000000-0000-0000-0000-000000000000
attachments:
- type: link
name: Accident link
url: https://example/links/00000000-0000-0000-0000-000000000000
metadata:
foo: bar
responses:
'200':
description: The alert was successfully updated.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericAlert'
example:
Generic Alert:
value:
id: 00000000-0000-0000-0000-000000000000
createdAt: '2023-12-31T23:59:59.999999Z'
updatedAt: '2023-12-31T23:59:59.999999Z'
vendorId: 00000000-0000-0000-0000-000000000000
vendorName: Example Vendor
status: open
type: other
subType: traffic-accident
title: Updated Traffic Accident
description: Traffic Accident at 456 State St
priority: 3
eventTime: '2023-12-31T23:59:59.999999Z'
subjectId: 00000000-0000-0000-0000-000000000000
ttl: 600
location: null
attachments:
- type: link
name: Accident link
url: https://example/links/00000000-0000-0000-0000-000000000000
metadata:
foo: bar
'400':
description: The given alert contains one or more errors.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: subject not found
'401':
description: The provided token is either expired or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: The token is either expired or invalid.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: alert not found
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Throttled
/alerts:
get:
summary: Fetching all recent Alerts
description: Fetches all recent alerts that are displayed in FlockOS
tags:
- Alerts
security:
- bearerAuth: []
parameters:
- in: query
name: includeInactive
schema:
type: string
enum:
- 'true'
- 'false'
default: 'false'
required: false
description: Whether to include inactive alerts in the results.
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 100
default: 100
required: false
description: The maximum number of alerts returned in the response (1-100).
- in: query
name: offset
schema:
type: integer
default: 0
minimum: 0
required: false
description: The number of alert results to skip before starting to collect the set of alerts.
responses:
'200':
description: The alerts were successfully fetched.
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/GenericAlert'
example:
results:
- id: 00000000-0000-0000-0000-000000000000
createdAt: '2023-12-31T23:59:59.999999Z'
updatedAt: '2023-12-31T23:59:59.999999Z'
vendorId: 00000000-0000-0000-0000-000000000000
vendorName: Example Vendor
status: open
type: vehicle
subType: other
title: Vehicle Alert
description: Vehicle Alert at 835 Main St
priority: 1
eventTime: '2023-12-31T23:59:59.999999Z'
subjectId: 00000000-0000-0000-0000-000000000000
ttl: 600
location: null
attachments:
- type: link
name: Accident link
url: https://example/links/00000000-0000-0000-0000-000000000000
metadata:
foo: bar
- id: 00000000-0000-0000-0000-000000000000
createdAt: '2023-12-31T23:59:59.999999Z'
updatedAt: '2023-12-31T23:59:59.999999Z'
vendorId: 00000000-0000-0000-0000-000000000000
vendorName: Example Vendor
status: open
type: vehicle
subType: hotlist
title: Vehicle Alert
description: Vehicle Alert at 835 Main St
priority: 1
eventTime: '2023-12-31T23:59:59.999999Z'
subjectId: 00000000-0000-0000-0000-000000000000
ttl: 600
location: null
attachments:
- type: link
name: Accident link
url: https://example/links/00000000-0000-0000-0000-000000000000
metadata:
foo: bar
- id: 00000000-0000-0000-0000-000000000000
createdAt: '2023-12-31T23:59:59.999999Z'
updatedAt: '2023-12-31T23:59:59.999999Z'
vendorId: 00000000-0000-0000-0000-000000000000
vendorName: Example Vendor
status: open
type: vehicle
subType: customHotlist
title: Vehicle Alert
description: Vehicle Alert at 835 Main St
priority: 1
eventTime: '2023-12-31T23:59:59.999999Z'
subjectId: null
ttl: 600
location:
latitude: 40.783871
longitude: -73.97541
address: 129 W 81st St, New York, NY 10024
attachments:
- type: link
name: Accident link
url: https://example/links/00000000-0000-0000-0000-000000000000
metadata:
foo: bar
- id: 00000000-0000-0000-0000-000000000000
createdAt: '2023-12-31T23:59:59.999999Z'
updatedAt: '2023-12-31T23:59:59.999999Z'
vendorId: 00000000-0000-0000-0000-000000000000
vendorName: Example Vendor
status: open
type: other
subType: traffic-accident
title: Traffic Accident
description: Traffic Accident at 456 State St
priority: 3
eventTime: '2023-12-31T23:59:59.999999Z'
subjectId: 00000000-0000-0000-0000-000000000000
ttl: 600
location: null
attachments:
- type: link
name: Accident link
url: https://example/links/00000000-0000-0000-0000-000000000000
metadata:
foo: bar
'401':
description: The provided token is either expired or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: The token is either expired or invalid.
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Throttled
post:
summary: Creating an Generic Alert
description: Creates a new generic alert that will be displayed in FlockOS
tags:
- Alerts
security:
- bearerAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GenericAlert'
example:
Generic Alert:
value:
title: Traffic Accident
description: Traffic Accident at 456 State St
type: other
subType: traffic-accident
priority: 3
eventTime: '2023-12-31T23:59:59.999999Z'
subjectId: 00000000-0000-0000-0000-000000000000
ttl: 600
location: null
attachments:
- type: link
name: Accident link
url: https://example/links/00000000-0000-0000-0000-000000000000
metadata:
foo: bar
responses:
'200':
description: The alert was successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericAlert'
example:
Generic Alert:
value:
id: 00000000-0000-0000-0000-000000000000
createdAt: '2023-12-31T23:59:59.999999Z'
updatedAt: '2023-12-31T23:59:59.999999Z'
vendorId: 00000000-0000-0000-0000-000000000000
vendorName: Example Vendor
status: open
type: other
subType: traffic-accident
title: Traffic Accident
description: Traffic Accident at 456 State St
priority: 3
eventTime: '2023-12-31T23:59:59.999999Z'
subjectId: 00000000-0000-0000-0000-000000000000
ttl: 600
location: null
attachments:
- type: link
name: Accident link
url: https://example/links/00000000-0000-0000-0000-000000000000
metadata:
foo: bar
'400':
description: The given alert contains one or more errors.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: subject not found
'401':
description: The provided token is either expired or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: The token is either expired or invalid.
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Throttled
/alerts/{alertId}/close:
post:
summary: Closing an Alert.
description: Closes an alert so that it is no longer visible
tags:
- Alerts
security:
- bearerAuth: []
parameters:
- in: path
name: alertId
schema:
type: string
required: true
description: The ID of the alert that will be closed.
responses:
'204':
description: The alert was successfully closed.
'401':
description: The provided token is either expired or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: The token is either expired or invalid.
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Throttled
components:
schemas:
Attachment:
type: object
required:
- type
- name
- url
properties:
type:
type: string
enum:
- link
description: The type of attachment.
name:
type: string
description: The display name for the attachment.
url:
type: string
description: The url for the attachment.
ErrorResponse:
properties:
error:
type: string
GenericAlert:
type: object
required:
- title
- priority
- eventTime
- location
- type
properties:
title:
type: string
description: 'The title for the alert. Example: "An Attempted Break-In Occurred"'
description:
type: string
description: "A description for the alert. Example: \"There was an attempted break-in detected at 123 Main St.\" \n"
type:
type: string
enum:
- vehicle
- person
- drone
- other
subType:
type: string
description: A developer provided type that helps differentiate and organize the various alert types within the UI. You can use alphanumeric characters and dashes as part of the string.
priority:
type: integer
default: 3
minimum: 1
maximum: 5
description: The priority of the alert. A priority must be between 1 and 5, where 1 is the highest priority.
eventTime:
type: string
format: date-time
description: The timestamp (RFC3339 UTC format) of when the event related to this alert occurred.
example: '2023-12-31T23:59:59.999999Z'
subjectId:
type: string
description: The subjectId from the Geo API from which this alert was generated.
ttl:
type: integer
description: 'The amount of time (in seconds) that the alert should be visible for. If a TTL is not provided, the alert will remain visible until closed.
'
location:
type: object
description: The location of the alert. If a subjectId is provided, a location will not be accepted in this request, as the location of the related subject will take priority.
required:
- latitude
- longitude
properties:
latitude:
type: number
format: double
minimum: -90
maximum: 90
description: The latitude of the event that this alert is related to. Precision is only 32 bit so it is only accurate for 6 to 9 decimal places.
example: 33.786147
longitude:
type: number
format: double
minimum: -180
maximum: 180
description: The longitude of the event that this alert is related to. Precision is only 32 bit so it is only accurate for 6 to 9 decimal places.
example: -84.412822
address:
type: string
description: The address that this alert is related to.
example: 1170 Howell Mill Rd NW, Atlanta, GA 30318
attachments:
type: array
maxItems: 1
items:
anyOf:
- $ref: '#/components/schemas/Attachment'
description: Attachments that will be displayed with the alert.
metadata:
type: object
additionalProperties:
type: string
description: Custom metadata for the alert
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
oauth2Auth:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.flocksafety.com/oauth/token
scopes:
custom-holists:read: Read access to custom hotlists
custom-holists:write: Write access to custom hotlists
FlockOAuth:
type: oauth2
description: OAuth 2 with the client credentials flow
flows:
clientCredentials:
scopes:
plate-reads:lookup: Access to perform lookups on license plate reads.
tokenUrl: https://api.flocksafety.com/oauth/token
oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.flocksafety.com/oauth/token
scopes: {}