Integration API Methods

1. Validate Integration Key

Checks whether the provided Integration Key is valid.

POST /v1/integration-key/validate

Header	Type	Required	Description
X-Integration-Key	string	yes	integration key

Example:

curl -X POST \
  "https://cloud.faceter.cam/integration-api/v1/integration-key/validate" \
  -H "X-Integration-Key: YOUR_INTEGRATION_KEY"

Response 200:

{ "isValid": true }

Field	Type	Description
isValid	boolean	whether the key is valid

2. Get Camera Information

Returns complete information about a specific camera.

GET /v1/cameras/{cameraId}

Parameter	Type	Description
cameraId	uuid	camera identifier

Example:

curl -X GET \
  "https://cloud.faceter.cam/integration-api/v1/cameras/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Integration-Key: YOUR_INTEGRATION_KEY"

Response 200:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "deviceId": "1fa85f64-5717-4562-b3fc-2c963f66afb1",
  "title": "Entrance Camera",
  "previewUrl": "https://example.com/preview.jpg",
  "archiveApiToken": { "signature": "string", "exp": 1712745600 },
  "archiveApiUrl": "https://archive.example.com",
  "archiveDays": 30,
  "liveRtspUrl": "rtsp://example.com/live",
  "liveHlsUrl": "https://example.com/live.m3u8",
  "isOnline": true,
  "lastOnlineDate": "2026-04-10T09:00:00Z",
  "cameraModel": "Model X",
  "platform": "Embedded",
  "serialNumber": "ABC123",
  "firmwareVersion": "1.0.0",
  "applicationVersion": "2.1.0",
  "isOwner": true,
  "isFullAccess": true,
  "isArchiveGranted": true,
  "isAudioGranted": true,
  "tempAccessExpiryDate": "2026-04-20T09:00:00Z",
  "location": {
    "id": "loc-1",
    "title": "Main Office",
    "room": { "id": "room-1", "title": "Hall" }
  }
}

Field	Type	Description
id	uuid	camera identifier
deviceId	uuid	device identifier
title	string	camera name
previewUrl	string	preview URL
archiveApiToken	object	Archive API token
archiveApiToken.signature	string	token signature
archiveApiToken.exp	int64	token expiry in Unix time
archiveApiUrl	string	Archive API base URL
archiveDays	integer	archive depth in days
liveRtspUrl	string	live stream RTSP URL
liveHlsUrl	string	live stream HLS URL
isOnline	boolean	camera is online
lastOnlineDate	datetime	last online timestamp
cameraModel	string	camera model
platform	string	`Embedded` / `ThirdParty` / `Mobile`
serialNumber	string	serial number
firmwareVersion	string	firmware version
applicationVersion	string	app version
isOwner	boolean	user is the owner
isFullAccess	boolean	full access granted
isArchiveGranted	boolean	archive access granted
isAudioGranted	boolean	audio access granted
tempAccessExpiryDate	datetime	temporary access expiry
location.id	string	location identifier
location.title	string	location name
location.room.id	string	room identifier
location.room.title	string	room name

Errors: 404 Not Found

3. Get Camera List

Returns all cameras available to the integration.

GET /v1/cameras

Example:

curl -X GET \
  "https://cloud.faceter.cam/integration-api/v1/cameras" \
  -H "X-Integration-Key: YOUR_INTEGRATION_KEY"

Response 200 — array of objects, each with the same structure as GET /v1/cameras/{cameraId}.

4. Get Camera Events

Returns camera events with optional filtering.

GET /v1/cameras/{cameraId}/events

Query parameters:

Parameter	Type	Description
eventTypes	array[string]	list of event types
startDate	datetime	period start
endDate	datetime	period end
mergeInterval	integer	event merge interval
limit	integer	maximum number of records
sortOrder	string	`None` / `Asc` / `Desc`

Event types: Motion, Human, Vehicle, LineCrossing, Intrusion, PeopleCounting, LicensePlate, Pet, PersonalMobilityVehicle, Face, Custom

Example:

curl -G \
  "https://cloud.faceter.cam/integration-api/v1/cameras/3fa85f64-5717-4562-b3fc-2c963f66afa6/events" \
  -H "X-Integration-Key: YOUR_INTEGRATION_KEY" \
  --data-urlencode "startDate=2026-04-01T00:00:00Z" \
  --data-urlencode "endDate=2026-04-10T00:00:00Z" \
  --data-urlencode "eventTypes=Motion" \
  --data-urlencode "sortOrder=Desc" \
  --data-urlencode "limit=100"

Response 200:

{
  "items": [
    {
      "id": "7fa85f64-5717-4562-b3fc-2c963f66afa1",
      "cameraId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "Motion",
      "startTime": "2026-04-10T08:00:00Z",
      "endTime": "2026-04-10T08:01:00Z",
      "previewUrl": "https://example.com/event-preview.jpg",
      "mergedEventsCount": 2,
      "attributes": [{ "confidence": "0.98" }]
    }
  ],
  "hasMore": false
}

Errors: 400 Bad Request, 404 Not Found

5. Create Camera Event

Creates a new event for the camera.

POST /v1/cameras/{cameraId}/events

Request Body:

{
  "eventId": "7fa85f64-5717-4562-b3fc-2c963f66afa1",
  "startDate": "2026-04-10T08:00:00Z",
  "endDate": "2026-04-10T08:01:00Z",
  "eventType": "Motion",
  "instant": false,
  "grid": { "rows": 3, "cols": 3, "cells": [1, 0, 0, 1, 1, 0, 0, 0, 1] },
  "attributes": { "confidence": "0.98" },
  "snapshot": "base64-or-url",
  "objectSnapshot": "base64-or-url"
}

Response 204 — no response body.

Errors: 400 Bad Request, 404 Not Found

6. Get Recording Intervals

Returns available recording intervals for a camera.

GET /v1/cameras/{cameraId}/recordings

Response 200:

[{ "startDate": "2026-04-10T08:00:00Z", "durationSeconds": 300 }]

Field	Type	Description
startDate	datetime	recording start
durationSeconds	integer	duration in seconds

Errors: 404 Not Found

7. Get Archive Clip (Synchronous)

Returns a video clip from the archive for the given interval.

GET /v1/cameras/{cameraId}/archive/clip

Parameter	Type	Description
startDate	datetime	clip start
duration	int64	duration in seconds

Example:

curl -G \
  "https://cloud.faceter.cam/integration-api/v1/cameras/3fa85f64-5717-4562-b3fc-2c963f66afa6/archive/clip" \
  -H "X-Integration-Key: YOUR_INTEGRATION_KEY" \
  --data-urlencode "startDate=2026-04-10T08:00:00Z" \
  --data-urlencode "duration=60" \
  -o clip.mp4

Response 200 — binary video file.

Errors: 400 Bad Request, 404 Not Found

8. Start Archive Export (Asynchronous)

Creates an asynchronous archive export task.

POST /v1/cameras/{cameraId}/archive/exports

Request Body:

{
  "startDate": "2026-04-10T08:00:00Z",
  "durationSeconds": 120,
  "audioEnabled": true,
  "callbackUrl": "https://example.com/webhook"
}

Field	Type	Description
startDate	datetime	export interval start
durationSeconds	int32	duration in seconds
audioEnabled	boolean	include audio
callbackUrl	string	callback URL when done

Response 202:

{ "exportId": "9fa85f64-5717-4562-b3fc-2c963f66afa2", "status": "Queued" }

Errors: 400 Bad Request, 404 Not Found, 500 Server Error

9. Archive Export Status

GET /v1/cameras/{cameraId}/archive/exports/{exportId}

Response 200:

{
  "exportId": "9fa85f64-5717-4562-b3fc-2c963f66afa2",
  "status": "Completed",
  "videoUrl": "https://example.com/archive.mp4",
  "previewUrl": "https://example.com/archive-preview.jpg",
  "errorMessage": null,
  "createdAtUtc": "2026-04-10T08:00:00Z",
  "completedAtUtc": "2026-04-10T08:02:00Z"
}

Errors: 403 Forbidden, 404 Not Found, 500 Server Error

10. Start Audio Export (Asynchronous)

POST /v1/cameras/{cameraId}/exports/audio

Request Body:

{
  "startDate": "2026-04-10T08:00:00Z",
  "durationSeconds": 120,
  "callbackUrl": "https://example.com/webhook"
}

Response 202:

{ "exportId": "afa85f64-5717-4562-b3fc-2c963f66afa3", "status": "Queued" }

Errors: 400 Bad Request, 404 Not Found, 500 Server Error

11. Audio Export Status

GET /v1/cameras/{cameraId}/exports/audio/{exportId}

Response 200:

{
  "exportId": "afa85f64-5717-4562-b3fc-2c963f66afa3",
  "status": "Completed",
  "audioUrl": "https://example.com/audio.mp3",
  "errorMessage": null,
  "createdAtUtc": "2026-04-10T08:00:00Z",
  "completedAtUtc": "2026-04-10T08:02:00Z"
}

Errors: 403 Forbidden, 404 Not Found, 500 Server Error

Type Reference

SortOrder: None · Asc · Desc

CameraPlatform: Embedded · ThirdParty · Mobile

ClientsEventType: Motion · Human · Vehicle · LineCrossing · Intrusion · PeopleCounting · LicensePlate · Pet · PersonalMobilityVehicle · Face · Custom