API overview

The IC Secure API lets your software read your sites, recorders, cameras and events, grab snapshots, export clips and get events pushed to it with webhooks.

The full reference, with every field and a sample for each endpoint, is at api.icsecure.ai/docs. This page covers what you need before you start.

Create an API key

API keys are managed by account admins.

In IC Secure, open Account and choose the API keys tab.
Select Create key, give it a name you will recognize later (for example, the name of the system that will use it), and choose its access:
- Read only: list and read sites, recorders, cameras and events, and fetch snapshots.
- Read and write: everything above, plus clip exports and managing webhooks.
Copy the key right away. It starts with icsk_ and is shown only once. If you lose it, revoke it and create a new one.

A key acts for the whole account. Revoke a key from the same tab as soon as it is no longer needed; it stops working immediately.

Make a request

Send the key as a bearer token:

curl https://api.icsecure.ai/v1/sites \
  -H "Authorization: Bearer $IC_SECURE_API_KEY"

Endpoint	What it does
`GET /v1/sites`, `GET /v1/sites/{id}`	Your sites
`GET /v1/recorders`, `GET /v1/recorders/{id}`	Recorders and bridges, with online state
`GET /v1/cameras`, `GET /v1/cameras/{id}`	Cameras
`GET /v1/events`	Events, newest first. Filter with `siteId`, `recorderId`, `cameraId`, `type`, `since`, `until`
`GET /v1/cameras/{id}/snapshot`	A current JPEG from the camera
`GET /v1/events/{id}/snapshot`	The picture taken when the event happened
`POST /v1/clips`, `GET /v1/clips/{id}`	Export a clip of recorded footage (read and write keys)
`/v1/webhooks`	Manage webhooks (read and write keys)

Lists and pagination

Lists return up to 50 items by default (?limit= up to 100):

{ "data": [ ... ], "nextCursor": "MjAyNi0xMC0y..." }

When nextCursor is not null, pass it back as ?cursor= to get the next page. Keep the other filters the same while you page.

Rate limits

Each key can make 120 requests a minute. Every answer carries RateLimit-* headers showing what is left. Over the limit you get 429 Too Many Requests with a Retry-After header; wait that many seconds and try again.

For events, webhooks are better than asking every few seconds: they arrive as soon as something happens and do not count against the limit.

Errors

Errors use the HTTP status code and a body like this:

{ "error": { "code": "NOT_FOUND", "message": "Camera not found" } }

The code values are stable, so build your handling on them, not on the message text.

Status	Meaning
`400`	A parameter is missing or wrong. The message says which.
`401`	The key is missing, wrong or revoked.
`403`	The key is read only and the request needs read and write.
`404`	Not found, or not in your account.
`429`	Too many requests. See `Retry-After`.
`503`	The camera or recorder could not be reached right now (for example `CAMERA_UNAVAILABLE` on a snapshot). Try again later.

Clip exports

Export up to 5 minutes of recorded footage from one camera:

curl https://api.icsecure.ai/v1/clips \
  -H "Authorization: Bearer $IC_SECURE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cameraId":"<camera id>","start":"2026-10-26T14:00:00Z","end":"2026-10-26T14:01:00Z"}'

The answer comes back right away with an id and "status": "queued". The clip is then prepared in the background, usually within a minute or two.
The end time must be at least 30 seconds in the past, and the footage must still be on the recorder.
Check GET /v1/clips/{id}, or listen for the clip.ready and clip.failed webhooks. When the status is ready, the answer includes a downloadUrl that works for 1 hour. Ask again for a fresh link.
Exported clips are kept for 7 days, then the status becomes expired.
An account can have up to 10 exports waiting at once.

Exports made through the API do not appear in anyone’s Clips list in the app, and they do not count toward it.