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
Content-Type: multipart/form-data

The request body is sent as multipart/form-data. Text values are sent as separate form fields, while snapshot and objectSnapshot are sent as binary files.

Form fields:

Field	Type	Description
eventId	uuid	event identifier
startDate	datetime	event start date in UTC, ISO 8601
endDate	datetime, nullable	event end date in UTC, ISO 8601
eventType	string	event type
instant	boolean	instant-event flag
grid.rows	integer	number of grid rows
grid.cols	integer	number of grid columns
grid.cells	int64, repeated field	grid cell values; each value is sent as a separate `grid.cells` field
attributes[key]	string	additional attribute, where `key` is the attribute name
snapshot	binary file, nullable	event snapshot, up to 5 MB
objectSnapshot	binary file, nullable	object snapshot, up to 5 MB

If grid is sent, grid.rows and grid.cols must be greater than zero and grid.cells must not be empty. Keys and values in attributes must not be empty.

Example:

curl -X POST \
  "https://cloud.faceter.cam/integration-api/v1/cameras/<cameraId>/events" \
  -H "X-Integration-Key: YOUR_INTEGRATION_KEY" \
  --form 'eventId=7fa85f64-5717-4562-b3fc-2c963f66afa1' \
  --form 'startDate=2026-04-10T08:00:00Z' \
  --form 'endDate=2026-04-10T08:01:00Z' \
  --form 'eventType=Motion' \
  --form 'instant=false' \
  --form 'grid.rows=3' \
  --form 'grid.cols=3' \
  --form 'grid.cells=1' \
  --form 'grid.cells=0' \
  --form 'grid.cells=0' \
  --form 'grid.cells=1' \
  --form 'grid.cells=1' \
  --form 'grid.cells=0' \
  --form 'grid.cells=0' \
  --form 'grid.cells=0' \
  --form 'grid.cells=1' \
  --form 'attributes[confidence]=0.98' \
  --form 'snapshot=@./event.jpg;type=image/jpeg' \
  --form 'objectSnapshot=@./object.jpg;type=image/jpeg'

Do not set the Content-Type header manually — curl adds the required boundary itself.

Response 204 — the event is accepted, no response body.

Errors:

Code	Reason
400 Bad Request	invalid form fields, an empty file, a file over 5 MB, or invalid event parameters
404 Not Found	camera not found or not available to the integration
429 Too Many Requests	the limit of 10 event-creation requests per second is exceeded; the wait time is returned in the `Retry-After` header

A user sees the event only if its type is enabled in the event filter in the app. If the event is created and returned by GET /v1/cameras/{cameraId}/events but does not appear in the feed, this is almost always the reason — not a failed request.
The Custom type is not displayed by current app versions. Use it for your own processing via the API; for events the user must see, pick another ClientsEventType value.
The event id in the feed differs from the eventId you sent. Your eventId is an idempotency key and is not returned — keep the mapping on your side.
Repeating the request with the same eventId creates no duplicate. For an event that has not finished yet you may send endDate to close it, which also updates grid. Re-sent snapshot and objectSnapshot replace the stored images. The attributes, startDate, eventType and instant fields of an existing event are not changed.
snapshot and objectSnapshot are sent as binary multipart parts. Base64, strings with a data:image/... prefix and URLs are not supported. Both snapshots are optional; if a file is sent it must not be empty and must not exceed 5 MB. Without a snapshot the event card in the feed has no image.
Nested values are not sent as JSON objects — use the grid.rows, grid.cols, repeated grid.cells and attributes[name] fields.
A created event cannot be deleted via the Integration API — it expires together with the archive (camera archiveDays).

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