Argus

Integrating

These endpoints make it easy for a client — a photo manager, a home server, a camera script — to correlate its own records with Argus and stay in sync. All are generic: Argus never interprets your identifiers or assumes anything about the calling system.

external_ref — attach your own id

Every detect and enroll call accepts an optional opaque external_ref string. It's stored on the source image (and, for enroll, the identity), echoed back in responses, and queryable. Set it at creation and you never have to match by name afterwards.

# Tag the image with your own id at detect time
curl -X POST -H "X-API-Key: argus_..." \
  -F "file=@photo.jpg" -F "external_ref=my-app-image-42" \
  http://localhost:8100/api/detect/all

# Resolve your id back to Argus's source_image_id
curl -H "X-API-Key: argus_..." \
  "http://localhost:8100/api/images?external_ref=my-app-image-42"

Works the same for identities:

# Create an identity with a ref
curl -X POST -H "X-API-Key: argus_..." -H "Content-Type: application/json" \
  -d '{"label": "Noah", "type": "face", "external_ref": "my-app-person-7"}' \
  http://localhost:8100/api/identities

# Look it up by your ref
curl -H "X-API-Key: argus_..." \
  "http://localhost:8100/api/identities?external_ref=my-app-person-7"

# Backfill a ref onto an existing identity
curl -X PUT -H "X-API-Key: argus_..." -H "Content-Type: application/json" \
  -d '{"external_ref": "my-app-person-7"}' \
  http://localhost:8100/api/identities/12/external_ref

Change feed — sync deltas without re-scanning

Poll /api/changes?since=<cursor> to learn what changed — identities and detections created, relabeled, or deleted. The returned next_cursor is the value to pass as since next time. Detection events carry the source image's external_ref so you know which of your records to update.

curl -H "X-API-Key: argus_..." "http://localhost:8100/api/changes?since=0&limit=100"
# → {"changes": [{"id": 1, "entity_type": "detection", "entity_id": 42,
#                 "action": "relabeled", "external_ref": "my-app-image-42", ...}],
#    "next_cursor": 1, "has_more": false}

Start with since=0 on first run, then store and forward next_cursor each time.

Capabilities — discover what this instance can do

GET /api/capabilities reports which detection types are usable right now, active models, supported formats, pagination limits, and which integration features the build exposes. Call it before integrating so a client can adapt instead of hardcoding.

curl http://localhost:8100/api/capabilities

No API key required.

Batch operations

Relabel or read many detections in one round-trip.

# Batch relabel — per-item results, one bad item never fails the others
curl -X POST -H "X-API-Key: argus_..." -H "Content-Type: application/json" \
  -d '{"items": [{"detection_id": 1, "label": "park bench"},
                 {"detection_id": 2, "identity_id": 5}]}' \
  http://localhost:8100/api/detections/label

# Batch read — current state of many detections (unknown ids simply absent)
curl -X POST -H "X-API-Key: argus_..." -H "Content-Type: application/json" \
  -d '{"detection_ids": [1, 2, 3]}' \
  http://localhost:8100/api/detections/query

Webhooks

Configure a webhook URL in settings and Argus will POST a JSON payload to it whenever something changes. Register it under Settings → Webhook URL.

All events share the same envelope:

{ "event": "<name>", "data": { ... } }

Identity events

Event	When	Key data fields
`identity.created`	New identity saved (face enrollment, manual create)	`identity_id`, `label`, `type` (`face`/`object`), `external_ref`
`identity.updated`	Rename, thumbnail change, embedding added/removed, detection added	`identity_id`, `action` (`renamed`, `thumbnail_updated`, `embedding_added`, `embedding_removed`, `detection_added`), plus action-specific fields
`identity.merged`	Two identities merged	`identity_id` (source, now deleted), `merged_into` (surviving id)
`identity.deleted`	Identity removed	`identity_id`

Detection events

Event	When	Key data fields
`detection.created`	New detection row written	`detection_id`, `type`, `identity_id` (nullable), `external_ref` (source image's ref)
`detection.labeled`	Detection assigned or reassigned to an identity	`detection_id`, `type`, `identity_id` (null = rejected)
`detection.deleted`	One or more detections removed	`detection_ids` (array)

Enrollment via Argus UI and webhook-driven sync

When a face is enrolled directly in the Argus UI (not via a client's scan), Argus fires identity.created followed by identity.updated (action: "embedding_added") for each enrolled detection. The identity.created payload includes the identity's external_ref if one was already set.

A client that stored its own photo IDs as external_ref on source images at detect time can use this to reconcile without a full resync: on receiving identity.created, fetch GET /api/identities/{identity_id}/gallery and match each item's source_external_ref (the original photo id) to your own records.

Example integration pattern

A photo manager that wants to show face tags alongside its own photo view can integrate with Argus like this:

At import time, POST each photo to /api/detect/all with external_ref set to your own photo id. Store the returned source_image_id.
Listen for detection.labeled and identity.created webhooks (or poll /api/changes?since=<cursor>) to learn when faces are confirmed or relabeled. Detection events carry the source image's external_ref so you know which photo to update. On identity.created, walk the identity's gallery to link any existing photos.
Fetch current face data for a photo via GET /api/images/{source_image_id}/faces when displaying the detail view. Bbox coordinates are stored relative to the original image dimensions.
To check whether Argus has already seen a photo, query by external_ref before submitting — avoids double-ingestion without your app needing to track source_image_ids.