SecureGate Docs

API Reference

Complete endpoint reference for SecureGate — v1 microservice endpoints and legacy-compatible REST API

Authentication

All endpoints require a valid Satschel IAM JWT in the Authorization header:

Authorization: Bearer <IAM JWT>

The gateway extracts X-Org-Id and X-Tenant-Id from the JWT claims and injects them as headers for downstream services. All data queries are scoped to the resolved tenant.

v1 Endpoints (Microservices)

These endpoints are routed by the Go API gateway to the appropriate Python microservice.

POST /v1/faces

Upload an image to detect, align, embed, and store faces.

Service: ingest (:8002) + embed (:8001)

curl -X POST https://api.securegate.dev.satschel.com/v1/faces \
  -H "Authorization: Bearer $TOKEN" \
  -F "image=@photo.jpg" \
  -F "collection=event_12345"

Response:

{
  "faces": [
    {
      "id": "face_abc123",
      "bbox": [120, 80, 280, 310],
      "confidence": 0.9987,
      "quality": {
        "blur": 0.12,
        "yaw": -5.2,
        "pitch": 3.1,
        "face_size": 160
      },
      "embedding_stored": true
    }
  ],
  "image_id": "img_xyz789",
  "faces_detected": 1,
  "faces_stored": 1
}

Quality filtering: Faces are rejected if blur > 0.5, yaw/pitch > 30 degrees, or face size < 80px. Rejected faces are returned with embedding_stored: false and a rejection_reason field.

POST /v1/search

Search for matching faces by image or raw embedding vector.

Service: ingest (:8002) + embed (:8001)

# Search by image
curl -X POST https://api.securegate.dev.satschel.com/v1/search \
  -H "Authorization: Bearer $TOKEN" \
  -F "image=@query.jpg" \
  -F "collection=event_12345" \
  -F "top_k=5" \
  -F "threshold=0.6"

Response:

{
  "query_face": {
    "bbox": [100, 50, 250, 280],
    "confidence": 0.9991
  },
  "matches": [
    {
      "face_id": "face_abc123",
      "similarity": 0.8734,
      "metadata": {
        "name": "John Doe",
        "attendee_id": "att_456"
      }
    }
  ]
}

POST /v1/weapons

Upload an image for weapon/knife/gun detection.

Service: ingest (:8002)

curl -X POST https://api.securegate.dev.satschel.com/v1/weapons \
  -H "Authorization: Bearer $TOKEN" \
  -F "image=@frame.jpg"

Response:

{
  "detections": [
    {
      "class": "Gun",
      "confidence": 0.92,
      "bbox": [340, 200, 420, 310]
    }
  ],
  "weapon_detected": true
}

Classes: Weapon (generic), Knife, Gun.

POST /v1/enhance

Submit an image for async face restoration and background upscaling.

Service: enhance (:8003)

curl -X POST https://api.securegate.dev.satschel.com/v1/enhance \
  -H "Authorization: Bearer $TOKEN" \
  -F "image=@blurry.jpg" \
  -F "fidelity=0.7" \
  -F "upscale=4"

Response:

{
  "job_id": "enh_job_abc123",
  "status": "queued"
}

GET /v1/enhance/{job_id}

Poll the status of an enhancement job.

curl https://api.securegate.dev.satschel.com/v1/enhance/enh_job_abc123 \
  -H "Authorization: Bearer $TOKEN"

Response (completed):

{
  "job_id": "enh_job_abc123",
  "status": "completed",
  "result_url": "https://storage.securegate.dev.satschel.com/enhanced/enh_job_abc123.png",
  "original_size": [640, 480],
  "enhanced_size": [2560, 1920]
}

GET /healthz

Aggregate health check across all services.

{
  "status": "healthy",
  "services": {
    "gateway": "ok",
    "ingest": "ok",
    "embed": "ok",
    "enhance": "ok"
  }
}

Legacy-Compatible Endpoints (Base API)

These endpoints are served directly by the Go API gateway and maintain compatibility with the original Python FastAPI shape.

Events

MethodPathDescription
GET/eventsList events (categorized by upcoming/ongoing/past)
POST/eventsCreate a new event
GET/events/[id]Get event with invite stats
DELETE/events/[id]Soft-delete an event

Create event:

{
  "name": "Annual Security Summit",
  "description": "Corporate security conference",
  "date": "2026-06-15T09:00:00Z",
  "end_date": "2026-06-15T18:00:00Z"
}

Rooms

MethodPathDescription
GET/rooms?event_id=[id]List rooms for an event
POST/roomsCreate a room

Cameras

MethodPathDescription
GET/cameras?room_id=[id]List cameras for a room
POST/camerasCreate a camera

Attendees

MethodPathDescription
GET/attendees/[event_id]List attendees (embeddings stripped from response)
POST/register-attendee/[event_id]Register attendee with face photo

Invites

MethodPathDescription
GET/events/[id]/invitesList invites for an event
POST/events/[id]/invitesCreate an invite
PUT/events/[id]/invitesUpdate invite status

Timeline

MethodPathDescription
GET/timeline?event_id=[id]Presence logs with entry/exit aggregates

Auth / RBAC

MethodPathDescription
GET/permissionsList RBAC permissions
GET/rolesList RBAC roles

Health

MethodPathDescription
GET/healthReturns {"code": 200}

Timeline

Presence tracking — entry/exit logs, room occupancy, dwell time, and peak detection

Models

Complete model inventory — all pre-trained and fine-tuned models used in the SecureGate inference pipeline

On this page

Authenticationv1 Endpoints (Microservices)POST /v1/facesPOST /v1/searchPOST /v1/weaponsPOST /v1/enhanceGET /v1/enhance/{job_id}GET /healthzLegacy-Compatible Endpoints (Base API)EventsRoomsCamerasAttendeesInvitesTimelineAuth / RBACHealth