The Flock Safety v3 API Platform — Device, Custom Hotlist, LPR Search, Plate Lookup, Hotlist Alerts Subscription, Geolocation, CAD, Inbound Alerts, and Vehicle Detections Ingest APIs — served from api.flocksafety.com behind OAuth 2.0 client_credentials and authorization_code flows.
openapi: 3.0.3
info:
title: Flock Safety API Platform (v3)
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)
paths:
/geo/subjects/{externalSubjectId}:
delete:
summary: Disable a Tracked Subject
tags:
- Tracked Subjects
security:
- bearerAuth: []
parameters:
- name: externalSubjectId
in: path
description: ID of the subject you are updating
required: true
schema:
type: string
responses:
'200':
description: Disable a subject
content:
application/json:
schema:
$ref: '#/components/schemas/Heartbeat'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found (provided id doesn't match any existing)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
summary: Retrieving a Tracked Subject
description: Get a single subject's current location.
tags:
- Tracked Subjects
security:
- bearerAuth: []
parameters:
- name: externalSubjectId
in: path
description: ID of the subject type you are fetching
required: true
schema:
type: string
responses:
'200':
description: Get a single subject's current location
content:
application/json:
schema:
$ref: '#/components/schemas/Heartbeat'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found (provided id doesn't match any existing)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/geo/types/{typeId}:
delete:
summary: Deleting a Subject Type
description: Delete a subject type. This will delete tracking information on subjects of that type
tags:
- Tracked Subject Types
security:
- bearerAuth: []
parameters:
- name: typeId
in: path
description: ID of the subject type you are deleting
required: true
schema:
type: string
responses:
'200':
description: Delete a subject type. This will remove tracking information on subjects of that
type
content:
application/json:
schema:
$ref: '#/components/schemas/SubjectType'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found (provided id doesn't match any existing)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/hotlists/{hotlistId}:
delete:
description: Delete hotlist
summary: Delete a custom hotlist
tags:
- Custom Hotlists
security:
- oauth2Auth:
- custom-hotlists:write
parameters:
- $ref: '#/components/parameters/HotlistIdParam'
responses:
'204':
description: The hotlist was deleted successfully
'401':
description: Unauthorized, authentication token was invalid or not provided
'403':
description: Forbidden, your client does not have access to this resource
'404':
description: No hotlist was found with the given ID
get:
description: Retrieve a hotlist with the given ID
summary: Retrieve a custom hotlist
tags:
- Custom Hotlists
security:
- oauth2Auth:
- custom-hotlists:read
parameters:
- $ref: '#/components/parameters/HotlistIdParam'
responses:
'200':
description: The hotlist was successfully retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/Hotlist'
'401':
description: Unauthorized, authentication token was invalid or not provided
'403':
description: Forbidden, your client does not have access to this resource
'404':
description: No hotlist was found with the given ID
put:
description: Update a hotlist
summary: Update a custom hotlist
tags:
- Custom Hotlists
security:
- oauth2Auth:
- custom-hotlists:write
parameters:
- $ref: '#/components/parameters/HotlistIdParam'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateHotlistRequest'
responses:
'204':
description: The hotlist was updated successfully
'401':
description: Unauthorized, authentication token was invalid or not provided
'403':
description: Forbidden, your client does not have access to this resource
'404':
description: No hotlist was found with the given ID
'413':
description: Request entity too large, the number of entries exceeds the organization's limit
/integrations/lpr/alerts/subscriptions/{id}:
delete:
summary: Delete Subscription
description: Delete existing LPR hotlist alert webhook subscription by id
tags:
- LPR Hotlist Alert Subscriptions
security:
- bearerAuth: []
parameters:
- in: path
name: id
schema:
type: string
format: uuid
required: true
responses:
'204':
description: Success
'403':
description: Forbidden (lacking appropriate scope or client claims)
'404':
description: Subscription Not Found
'500':
description: Internal Server Error
get:
summary: Get Subscription
description: Get existing LPR hotlist alert webhook subscription by id
tags:
- LPR Hotlist Alert Subscriptions
security:
- bearerAuth: []
parameters:
- in: path
name: id
schema:
type: string
format: uuid
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
'403':
description: Forbidden (lacking appropriate scope or client claims)
'404':
description: Subscription Not Found
'500':
description: Internal Server Error
/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
/cad/events/active:
get:
summary: Retrieving Active Events
description: Gets all active events in chronological order of when they were created (most recent
first)
tags:
- CAD Events
security:
- bearerAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EventsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: Updating Active Events
description: Creates or updates each provided event in the same manner as /v3/cad/events, then closes
any open events not provided in the request
tags:
- CAD Events
security:
- bearerAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EventsBody'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EventsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Event Not Found (provided externalId doesn't match any existing)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/cad/events/{externalId}:
get:
summary: Retrieving an Event by ExternalID
description: gets event for provided externalId
tags:
- CAD Events
security:
- bearerAuth: []
parameters:
- in: path
name: externalId
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Event Not Found (provided externalId doesn't match any existing)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/cad/events:
get:
summary: Retrieving Events
description: Gets events in chronological order of when they were created (most recent first)
tags:
- CAD Events
security:
- bearerAuth: []
parameters:
- in: query
name: start
required: true
schema:
type: string
format: date-time
description: RFC3339 UTC datetime string
description: start of time range to get events for
- in: query
name: end
schema:
type: string
format: date-time
description: RFC3339 UTC datetime string
description: end of time range to get events for (defaults to current time if not provided)
- in: query
name: pageSize
schema:
type: integer
minimum: 1
maximum: 25
description: maximum number of events to return per request (defaults to max of 25 if not provided)
- in: query
name: page
schema:
type: integer
minimum: 1
description: page number of events to return (defaults to first page if not provided)
- in: query
name: activeOnly
schema:
type: boolean
description: whether to return only active events (defaults to false)
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EventsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: Creating or Updating an Event
description: Creates a new event, or updates an event if externalId matches an existing event
tags:
- CAD Events
security:
- bearerAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Event Not Found (provided externalId doesn't match any existing)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/devices/{deviceId}:
get:
summary: Retrieving a device.
description: Retrieves a particular device.
tags:
- Devices
parameters:
- $ref: '#/components/parameters/DeviceIdParam'
security:
- bearerAuth: []
responses:
'200':
description: The device was successfully retrieved.
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/Device'
'401':
$ref: '#/components/responses/AuthorizationError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitError'
'500':
$ref: '#/components/responses/InternalError'
patch:
summary: Updating a device.
description: Updates a device.
tags:
- Devices
parameters:
- $ref: '#/components/parameters/DeviceIdParam'
security:
- bearerAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDeviceRequest'
examples:
Update Device Metadata:
value:
metadata:
deviceSerial: 21204
url: https://example.com/cameras/0021204
Update Device Name:
value:
name: 'Camera #0004 - Bowman Rd'
responses:
'204':
description: The device was successfully updated.
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthorizationError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
description: The given device update request contains one or more errors.
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimitError'
'500':
$ref: '#/components/responses/InternalError'
/devices:
get:
summary: Retrieving devices.
description: Retrieves the devices that belong to your organization.
tags:
- Devices
security:
- bearerAuth: []
parameters:
- in: query
name: latitude
description: Used to filter by area.
required: false
schema:
type: number
- in: query
name: longitude
description: Used to filter by area.
required: false
schema:
type: number
- in: query
name: radius
description: Used to filter by area.
required: false
schema:
type: number
- in: query
name: page
description: The page from which to retrieve results.
required: false
schema:
type: number
- in: query
name: pageSize
description: The maximum number of results that should be on each page.
required: false
schema:
type: number
responses:
'200':
description: The devices were successfully retrieved.
content:
application/json:
schema:
type: object
required:
- results
- totalItems
- totalPages
properties:
results:
type: array
description
# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/flock-safety/refs/heads/main/openapi/flock-safety-openapi-original.yml