Skip to main content

Argus API overview

Every Argus site node has an HTTP API. The dashboard uses the same API, so anything you can do in the dashboard you can also script. Use it to pull alerts into your own tools, triage alerts, ask the Copilot questions and manage cameras and rules.

Base URL​

The API is served over HTTPS at the same address as the dashboard, for example https://argus.example.com/. The site's HTTPS entrypoint passes API requests to the site node, so there is no separate API host or port, and no cloud endpoint. Your scripts must be able to reach the site on your network.

The examples on these pages use a shell variable for the address:

export ARGUS_URL="https://argus.example.com"

Replace it with your site's host name or IP address.

If the site uses its own internal certificate authority (the default when no public domain or certificate is set), install the site's root certificate as trusted on the machine that runs your scripts, or point your client at it, for example curl --cacert argus-root-ca.crt or requests with verify="argus-root-ca.crt". See Install. Don't turn certificate checks off.

Authentication​

The API uses the same email and password sign-in as the dashboard, with a session cookie:

  1. Send POST /login with your email and password.
  2. Keep the session cookie it sets.
  3. Send that cookie with every other request.
# Sign in and save the session cookie
curl -s -c argus.cookies \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "password": "'"$ARGUS_PASSWORD"'"}' \
"$ARGUS_URL/login"

# Use the cookie on later requests
curl -s -b argus.cookies "$ARGUS_URL/alerts?status=open&limit=10"

Use a dedicated account for scripts. Give it the operator role unless the script needs to change cameras, rules or settings. See Roles.

Some endpoints need the admin role. Each page says which.

The session cookie is marked Secure, so clients only send it over HTTPS. Sessions end after a period without requests, a maximum age, or when you sign out. Sign in again when you get 401. See Sessions.

Requests and responses​

  • Send request bodies as JSON with Content-Type: application/json.
  • Responses are JSON, except clips (an MP4 video), snapshots (a JPEG image) and camera streams (MJPEG).
  • Times are ISO 8601 strings with a time zone, for example 2026-10-05T09:14:03.512000+00:00.
  • IDs are integers.

Errors​

Errors return an HTTP status code and a JSON body with a detail field:

{ "detail": "Admin role required" }
StatusMeaning
400The request can't be done, for example deleting the default detection profile.
401You are not signed in, or the email or password is wrong.
403You are signed in but your role can't do this.
404The item doesn't exist.
409It clashes with existing data or the item's current state, for example a camera name that is taken or resolving an alert that is already closed.
422A field is missing or invalid. For body validation errors, detail is a list of the fields at fault.
429Too many failed sign-ins. Wait for the number of seconds in the Retry-After header.
500Something failed on the site node.
502Something outside the site node failed, for example a camera that can't be read or a notification destination that refused a test message.

Endpoints​

AreaEndpoints
Sign-in and users/setup, /login, /logout, /me, /me/password, /users
Alerts/alerts, /alerts/{alert_id}/..., /alerts/bulk-...
Events and clips/events, /clips/{event_id}
Copilot/copilot/chat
Cameras and edge nodes/cameras, /cameras/{camera_id}/zones, /zones, /organizations, /edge-nodes
Detection profiles/detection-profiles
Workflows and event types/workflows, /workflow-runs, /event-types
Notification channels/notification-channels
Audit log/audit-log
Settings/settings/retention, /system/health

Health check​

GET /health returns {"status": "ok"} when the API is up. It needs no sign-in, so you can use it from a load balancer or monitoring tool.

Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Argus for your site? We can help.Book a site assessment →