openapi: 3.0.0
info:
title: Coram alerts cameras API
description: "# Introduction\n\nThe Coram API enables seamless programmatic access to your security camera infrastructure, allowing you to build custom integrations and automate workflows.\n\n# Supported Actions\n\nManage and interact with your Coram platform resources:\n\n| Resource | Description |\n| -------- | ----------- |\n| **Camera Groups** | Organize and configure camera collections |\n| **Cameras** | Access camera settings, streams, and metadata |\n| **Locations** | Manage physical site configurations |\n| **NVRs** | Control and monitor network video recorders |\n| **Access Control** | List access control doors and trigger remote unlocks |\n\n# Required Headers\n\nEvery API request must include the following headers:\n\n| Header | Required | Description |\n| ------ | -------- | ----------- |\n| `X-Auth-Token` | Yes | Your API key (from the API key List Page) |\n\n**Example:**\n```\ncurl -X GET \"https://api.coram.ai/developer-api/v1/cameras\" \\\n -H \"X-Auth-Token: xxxxxxxxxxxxxxx\"\n```\n\n# Response Format\n\nAll API responses follow a consistent structure based on the operation result.\n\n## Success Response\n\n**List Operations** (e.g., `GET /v1/cameras`)\n\nReturns a `results` array with pagination support:\n\n```json\n{\n \"results\": [\n { \"id\": \"cam_001\", \"name\": \"Front Door\", ... },\n { \"id\": \"cam_002\", \"name\": \"Lobby\", ... }\n ],\n \"has_more\": true\n}\n```\n\nWhen `has_more` is `true`, additional results are available. Use pagination parameters to fetch more.\n\n**Bulk/Batch Operations** (e.g., `POST /v1/cameras`, `PATCH /v1/cameras`)\n\nReturns a top-level `status` field indicating whether the API request was processed, and a `results` array where each item reflects the outcome of an individual operation:\n\n```json\n{\n \"status\": \"success\",\n \"results\": [\n { \"status\": \"success\", \"data\": { \"id\": \"cam_001\", \"mac_address\": \"...\" } },\n { \"status\": \"error\", \"error\": { \"code\": \"VALIDATION_ERROR\", \"message\": \"...\" } }\n ]\n}\n```\n\n| Field | Description |\n| ----- | ----------- |\n| `status` (top-level) | `\"success\"` if the request was processed |\n| `results[].status` | `\"success\"` or `\"error\"` for each operation |\n| `results[].data` | Present when `status` is `\"success\"` |\n| `results[].error` | Present when `status` is `\"error\"` |\n\n## Error Response\n\nWhen an error occurs, the response includes `status` set to `\"error\"` along with detailed error information:\n\n```json\n{\n \"status\": \"error\",\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Invalid MAC address format\",\n \"field\": \"mac_address\"\n }\n}\n```\n\n**Error Fields:**\n\n| Field | Type | Description |\n| ----- | ---- | ----------- |\n| `code` | string | Machine-readable error code |\n| `message` | string | Human-readable error description |\n| `field` | string | The field that caused the error (if applicable) |\n\n\n# HTTP Status Codes\n\nThe API uses standard HTTP status codes to indicate the success or failure of requests:\n\n## Success Codes\n\n| Code | Description |\n| ---- | ----------- |\n| `200 OK` | Request succeeded |\n| `201 Created` | Resource successfully created |\n| `204 No Content` | Request succeeded with no response body |\n\n## Client Error Codes\n\n| Code | Description |\n| ---- | ----------- |\n| `400 Bad Request` | Invalid request syntax or parameters |\n| `401 Unauthorized` | Missing or invalid API key |\n| `403 Forbidden` | Valid API key but insufficient permissions |\n| `404 Not Found` | Requested resource does not exist |\n| `422 Unprocessable Entity` | Validation error in request body |\n| `429 Too Many Requests` | Rate limit exceeded |\n\n## Server Error Codes\n\n| Code | Description |\n| ---- | ----------- |\n| `500 Internal Server Error` | Unexpected server error (rare) |\n| `502 Bad Gateway` | Upstream service unavailable |\n| `503 Service Unavailable` | Service temporarily unavailable |\n\n\n# Error Handling Best Practices\n\n1. **Always check the `status` field** — Verify if the response indicates `\"success\"` or `\"error\"`\n\n2. **Handle specific error codes** — Use the `error.code` field to handle different error types programmatically\n\n3. **Implement retry logic** — For `429` and `5xx` errors, implement exponential backoff\n\n4. **Log error details** — Capture `error.code`, `error.message`, and `error.field` for debugging\n\n**Example error handling:**\n```python\nresponse = api.create_camera(data)\n\nif response[\"status\"] == \"error\":\n error = response[\"error\"]\n if error[\"code\"] == \"VALIDATION_ERROR\":\n print(f\"Invalid {error['field']}: {error['message']}\")\n elif error[\"code\"] == \"DUPLICATE_RESOURCE\":\n print(\"Camera already exists\")\n else:\n print(f\"Error: {error['message']}\")\n```\n\n---\n\n# Getting Started\n\n1. **Generate an API key** from your Coram app settings\n2. **Explore the endpoints** in the navigation to begin integrating\n\nNeed help? Contact [support@coram.ai](mailto:support@coram.ai)\n"
version: 1.0.0
servers:
- url: https://developer.coram.ai
description: Production
security:
- X-Auth-Token: []
tags:
- name: cameras
description: Manage individual cameras within your organization. Use these endpoints to register new cameras, update camera settings, retrieve camera information and status, move cameras between locations, and delete cameras from your system.
paths:
/v1/cameras:
get:
tags:
- cameras
summary: List cameras
description: 'List all cameras accessible to the user.
Retrieve cameras accessible to the user with their current status and
configuration details. Results can be filtered by NVR, location,
MAC address, IP address, or camera group ID.'
operationId: list_cameras
parameters:
- required: false
schema:
items:
type: string
type: array
title: nvr
name: nvrs
in: query
- required: false
schema:
items:
type: integer
type: array
title: location_id
name: location_ids
in: query
- required: false
schema:
type: boolean
title: exclude_disabled
default: false
name: exclude_disabled
in: query
- required: false
schema:
items:
type: string
type: array
title: mac_address
name: mac_addresses
in: query
- required: false
schema:
items:
type: string
type: array
title: ip
name: ips
in: query
- required: false
schema:
items:
type: integer
type: array
title: group_id
name: group_ids
in: query
- required: false
schema:
type: integer
minimum: 1.0
title: page
default: 1
name: page
in: query
- required: false
schema:
type: integer
maximum: 100.0
minimum: 1.0
title: limit
default: 100
name: limit
in: query
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CameraList'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-public-api-version: v1
x-public-api: true
security:
- X-Auth-Token: []
post:
tags:
- cameras
summary: Register cameras
description: 'Register multiple cameras in single location.
Register one or more cameras at a location by assigning them to available NVRs.
Cameras are automatically load-balanced across NVRs based on available capacity.'
operationId: register_cameras
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterCameraRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterCameraResponse'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- X-Auth-Token: []
x-public-api-version: v1
x-public-api: true
parameters: []
delete:
tags:
- cameras
summary: Delete cameras
description: 'Delete one or more cameras.
Remove one or more cameras from the system.'
operationId: delete_cameras
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/DeleteCameraPayload'
type: array
title: DeleteCameraPayload
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteCameraResponse'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- X-Auth-Token: []
x-public-api-version: v1
x-public-api: true
parameters: []
patch:
tags:
- cameras
summary: Update cameras
description: 'Update one or more cameras.
Update configuration, credentials, feature flags, and group assignments
for one or more cameras. Each camera is updated independently - if one
camera''s update fails, others can still succeed. Within each camera''s
update, all changes are atomic.
**Group Assignment:**
- Provide `group_ids` to assign the camera to specific groups
- An empty list `[]` resets the camera to the default group
- Omit `group_ids` (null) to leave group assignments unchanged'
operationId: update_cameras
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/UpdateCameraPayload'
type: array
title: UpdateCameraPayload
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCameraResponse'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- X-Auth-Token: []
x-public-api-version: v1
x-public-api: true
parameters: []
/v1/cameras/move:
post:
tags:
- cameras
summary: Move cameras
description: 'Move one or more cameras to different NVRs.
Transfer one or more cameras from one NVR to another.'
operationId: move_cameras
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/MoveCameraPayload'
type: array
title: MoveCameraPayload
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MoveCameraResponse'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- X-Auth-Token: []
x-public-api-version: v1
x-public-api: true
parameters: []
components:
schemas:
FeatureFlags:
properties:
is_audio_enabled:
type: boolean
title: Is Audio Enabled
description: Whether audio recording is enabled
is_license_plate_detection_enabled:
type: boolean
title: Is License Plate Detection Enabled
description: Whether license plate detection is enabled
is_force_fps_enabled:
type: boolean
title: Is Force Fps Enabled
description: Whether FPS is forced to a specific value
auto_tracking:
type: boolean
title: Auto Tracking
description: Whether PTZ auto-tracking is enabled
type: object
required:
- is_audio_enabled
- is_license_plate_detection_enabled
- is_force_fps_enabled
- auto_tracking
title: FeatureFlags
description: Current feature flag settings for a camera.
x-public-api-group: cameras
CameraLocation:
properties:
id:
type: integer
title: Id
description: Unique location identifier
name:
type: string
title: Name
description: Location display name
timezone:
type: string
title: Timezone
description: IANA timezone (e.g., 'America/New_York')
type: object
required:
- id
- name
- timezone
title: CameraLocation
description: Location associated with cameras and camera groups.
x-public-api-group: cameras
UpdateCameraPayload:
properties:
mac_address:
type: string
title: mac_address
description: Camera MAC address
name:
type: string
title: name
description: New display name (max 30 characters)
credentials:
allOf:
- $ref: '#/components/schemas/Credentials'
title: credentials
description: Camera credentials
enforced_rtsp_url:
type: string
title: Enforced Rtsp Url
description: Custom RTSP URL to override auto-discovery. Provide the path component beginning with '/' (e.g. '/Streaming/Channels/101'); it is combined with the camera's IP, port and credentials at connection time. A full 'rtsp://host:port/path' URL is also accepted and reduced to its path.
feature_flags:
allOf:
- $ref: '#/components/schemas/CameraFeatureFlag'
title: CameraFeatureFlag
description: Camera feature flags
group_ids:
items:
type: integer
type: array
title: group_ids
description: List of group IDs to assign (empty list resets to default group)
type: object
required:
- mac_address
title: UpdateCameraPayload
description: Request model for updating a single camera in bulk operation.
x-public-api-group: cameras
MoveCameraSuccessResult:
properties:
status:
type: string
enum:
- success
title: Status
default: success
data:
allOf:
- $ref: '#/components/schemas/MoveCameraSuccessData'
title: MoveCameraSuccessData
description: Success data
type: object
required:
- data
title: MoveCameraSuccessResult
description: Success result for camera move.
x-public-api-group: cameras
UpdateCameraSuccessResult:
properties:
status:
type: string
enum:
- success
title: Status
default: success
data:
allOf:
- $ref: '#/components/schemas/UpdateCameraSuccessData'
title: UpdateCameraSuccessData
description: Success data
type: object
required:
- data
title: UpdateCameraSuccessResult
description: Success result for camera update.
x-public-api-group: cameras
DeleteCameraErrorResult:
properties:
status:
type: string
enum:
- error
title: Status
default: error
error:
allOf:
- $ref: '#/components/schemas/ErrorDetails'
title: ErrorDetails
description: Error details
type: object
required:
- error
title: DeleteCameraErrorResult
description: Error result for camera delete.
x-public-api-group: cameras
MoveCameraSuccessData:
properties:
mac_address:
type: string
title: mac_address
description: Camera MAC address
target_nvr:
type: string
title: target_nvr
description: Name of the NVR the camera was moved to
type: object
required:
- mac_address
- target_nvr
title: MoveCameraSuccessData
description: Data returned for a successfully moved camera.
x-public-api-group: cameras
CameraGroup:
properties:
id:
type: integer
title: Id
description: Unique camera group identifier
name:
type: string
title: Name
description: Camera group display name
type: object
required:
- id
- name
title: CameraGroup
description: A logical grouping of cameras for organization and access control.
x-public-api-group: camera-groups
MoveCameraErrorResult:
properties:
status:
type: string
enum:
- error
title: Status
default: error
error:
allOf:
- $ref: '#/components/schemas/ErrorDetails'
title: ErrorDetails
description: Error details
type: object
required:
- error
title: MoveCameraErrorResult
description: Error result for camera move.
x-public-api-group: cameras
RegisterCameraSuccessData:
properties:
mac_address:
type: string
title: mac_address
description: Camera MAC address
nvr:
allOf:
- $ref: '#/components/schemas/CameraNVRInfo'
title: Nvr
description: NVR the camera was assigned to
type: object
required:
- mac_address
- nvr
title: RegisterCameraSuccessData
description: Data returned for a successfully registered camera.
x-public-api-group: cameras
Credentials:
properties:
username:
type: string
title: Username
description: Camera login username
password:
type: string
title: Password
description: Camera login password
type: object
required:
- username
- password
title: Credentials
description: Authentication credentials for camera access.
x-public-api-group: cameras
MoveCameraPayload:
properties:
mac_address:
type: string
title: mac_address
description: Camera MAC address
target_nvr:
type: string
title: target_nvr
description: Name of the NVR to move the camera to
type: object
required:
- mac_address
- target_nvr
title: MoveCameraPayload
description: Request model for moving a camera to a different NVR.
x-public-api-group: cameras
UpdateCameraResponse:
properties:
status:
type: string
enum:
- success
title: Status
default: success
summary:
allOf:
- $ref: '#/components/schemas/Summary'
title: Summary
description: Summary of the update operation
results:
items:
oneOf:
- $ref: '#/components/schemas/UpdateCameraSuccessResult'
- $ref: '#/components/schemas/UpdateCameraErrorResult'
discriminator:
propertyName: status
mapping:
success: '#/components/schemas/UpdateCameraSuccessResult'
error: '#/components/schemas/UpdateCameraErrorResult'
type: array
title: UpdateCameraResult
description: List of camera update results
type: object
required:
- summary
title: UpdateCameraResponse
description: Response model for bulk camera update.
x-public-api-group: cameras
RegisterCameraPayload:
properties:
mac_address:
type: string
title: mac_address
description: Camera MAC address. If omitted, a synthetic unique identifier is generated server-side.
name:
type: string
minLength: 1
title: name
description: Camera display name
ip:
type: string
title: ip
description: Camera IP address
vendor:
type: string
title: vendor
description: Camera manufacturer. Defaults to 'Unknown' when not provided.
rtsp_port:
type: integer
maximum: 65535.0
minimum: 1.0
title: rtsp_port
description: RTSP port number
default: 554
rtsp_url_path:
type: string
title: rtsp_url_path
description: Path component of the RTSP URL (e.g. '/Streaming/Channels/101'). Combined with ip, rtsp_port and credentials at runtime to form the full URL. Defaults to '/unknown' to match the placeholder used elsewhere in the system; callers should set this when the actual path is known.
default: /unknown
credentials:
allOf:
- $ref: '#/components/schemas/Credentials'
title: Credentials
description: Camera credentials
nvrs:
items:
type: string
minLength: 1
type: array
minLength: 1
title: nvrs
description: List of NVR display names from which the camera will be assigned to one. The system selects an available NVR from this list during registration.
type: object
required:
- name
- ip
- nvrs
title: RegisterCameraPayload
description: Request model for registering a single camera in bulk operation.
x-public-api-group: cameras
DeleteCameraSuccessResult:
properties:
status:
type: string
enum:
- success
title: Status
default: success
data:
allOf:
- $ref: '#/components/schemas/DeleteCameraSuccessData'
title: DeleteCameraSuccessData
description: Success data
type: object
required:
- data
title: DeleteCameraSuccessResult
description: Success result for camera delete.
x-public-api-group: cameras
RegisterCameraRequest:
properties:
cameras:
items:
$ref: '#/components/schemas/RegisterCameraPayload'
type: array
title: RegisterCameraPayload
description: List of cameras to register
location_id:
type: integer
title: location_id
description: Location ID to assign cameras to
type: object
required:
- cameras
- location_id
title: RegisterCameraRequest
description: Request model for bulk camera registration.
x-public-api-group: cameras
CameraStatus:
properties:
is_online:
type: boolean
title: Is Online
description: Indicates whether the camera is currently connected and accessible
last_seen_time:
type: string
title: Last Seen Time
description: Last connection timestamp (ISO 8601 format)
type: object
required:
- is_online
title: CameraStatus
description: Current connectivity status of a camera.
x-public-api-group: cameras
ErrorResponse:
properties:
status:
type: string
enum:
- error
title: Status
default: error
error:
allOf:
- $ref: '#/components/schemas/ErrorDetails'
title: Error
description: Error details
type: object
required:
- error
title: ErrorResponse
description: Error response model.
ErrorDetails:
properties:
code:
allOf:
- $ref: '#/components/schemas/ErrorCode'
description: Error code
message:
type: string
title: Message
description: Error message
field:
type: string
title: Field
description: Error field
docs:
type: string
title: Docs
description: Error docs
type: object
required:
- code
- message
title: ErrorDetails
description: Error message
UpdateCameraErrorResult:
properties:
status:
type: string
enum:
- error
title: Status
default: error
error:
allOf:
- $ref: '#/components/schemas/ErrorDetails'
title: ErrorDetails
description: Error details
type: object
required:
- error
title: UpdateCameraErrorResult
description: Error result for camera update.
x-public-api-group: cameras
UpdateCameraSuccessData:
properties:
mac_address:
type: string
title: Mac Address
description: Camera MAC address
name:
type: string
title: name
description: Camera display name
credentials:
allOf:
- $ref: '#/components/schemas/Credentials'
title: Credentials
description: Camera credentials
enforced_rtsp_url:
type: string
title: enforced_rtsp_url
description: Custom RTSP URL
feature_flags:
allOf:
- $ref: '#/components/schemas/CameraFeatureFlag'
title: CameraFeatureFlag
description: Camera feature flags
group_ids:
items:
type: integer
type: array
title: group_ids
description: Updated group IDs
type: object
required:
- mac_address
title: UpdateCameraSuccessData
description: Data returned for a successfully updated camera.
x-public-api-group: cameras
CameraFeatureFlag:
properties:
is_audio_enabled:
type: boolean
title: Is Audio Enabled
description: Whether audio recording is enabled
is_license_plate_detection_enabled:
type: boolean
title: Is License Plate Detection Enabled
description: Whether license plate detection is enabled
auto_tracking:
type: boolean
title: Auto Tracking
description: Whether PTZ auto-tracking is enabled
type: object
title: CameraFeatureFlag
description: Feature flags to update on a camera.
x-public-api-group: cameras
CameraNVRInfo:
properties:
name:
type: string
title: Name
description: NVR display name
timezone:
type: string
title: Timezone
description: NVR timezone (IANA format, e.g., 'America/New_York')
type: object
required:
- name
title: CameraNVRInfo
description: NVR (Network Video Recorder) associated with the camera.
x-public-api-group: cameras
Summary:
properties:
total:
type: integer
title: Total
description: Total number of operations in request
success_count:
type: integer
minimum: 0.0
title: Success Count
description: Number of successful operations
failure_count:
type: integer
minimum: 0.0
title: Failure Count
description: Number of failed operations
type: object
required:
- total
- success_count
- failure_count
title: Summary
description: Summary of operation.
Camera:
properties:
id:
type: integer
title: Id
description: Unique camera identifier
mac_address:
type: string
title: Mac Address
description: Camera MAC address
name:
type: string
title: Name
description: Camera display name
ip:
type: string
title: Ip
description: Camera IP address on the local network
vendor:
type: string
title: Vendor
description: Camera manufacturer/brand
manufacturer:
type: string
title: Manufacturer
description: Camera hardware manufacturer
model:
type: string
title: Model
description: Camera hardware model
is_enabled:
type: boolean
title: Is Enabled
description: Whether the camera is enabled for recording
status:
allOf:
- $ref: '#/components/schemas/CameraStatus'
title: Status
description: Current connectivity status
nvr:
allOf:
- $ref: '#/components/schemas/CameraNVRInfo'
title: Nvr
description: NVR the camera is assigned to
rtsp_port:
type: integer
title: Rtsp Port
description: RTSP streaming port number
width:
type: integer
title: Width
description: Video resolution width in pixels
height:
type: integer
title: Height
description: Video resolution height in pixels
fps:
type: integer
title: Fps
description: Video frames per second
codec:
type: string
title: Codec
description: Video codec (e.g., 'H264', 'H265')
onvif_enabled:
type: boolean
title: Onvif Enabled
description: Whether ONVIF protocol is enabled
video_orientation_type:
type: string
title: Video Orientation Type
description: Video orientation (e.g., 'normal', 'rotated_180')
feature_flags:
allOf:
- $ref: '#/components/schemas/FeatureFlags'
title: Feature Flags
description: Current feature flag settings
camera_groups:
items:
$ref: '#/components/schemas/CameraGroup'
type: array
title: CameraGroup
description: Groups this camera belongs to
location:
allOf:
- $ref: '#/components/schemas/CameraLocation'
title: Location
description: Location where the camera is installed
type: object
required:
- id
- mac_address
- name
- ip
- vendor
- is_enabled
- status
- nvr
- rtsp_port
- onvif_enabled
- video_orientation_type
- feature_flags
- camera_groups
title: Camera
description: Complete camera information in list response.
x-public-api-group: cameras
RegisterCameraSuccessResult:
properties:
status:
type: string
enum:
- success
title: Status
default: success
data:
allOf:
- $ref: '#/components/schemas/RegisterCameraSuccessData'
title: RegisterCameraSuccessData
description: Success data
type: object
required:
- data
title: RegisterCameraSuccessResult
description: Success result for camera registration.
x-public-api-group: cameras
DeleteCameraResponse:
properties:
status:
type: string
enum:
- success
title: Status
default: success
summary:
allOf:
- $ref: '#/components/schemas/Summary'
title: Summary
description: Summary of the delete operation
results:
items:
oneOf:
- $ref: '#/components/schemas/DeleteCameraSuccessResult'
- $ref: '#/components/schemas/DeleteCameraErrorResult'
discriminator:
pro
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coram-ai/refs/heads/main/openapi/coram-ai-cameras-api-openapi.yml