GraphQL API

The GraphQL API is the data surface of Face Matcher. Where the REST API issues commands, GraphQL lets you ask for exactly the fields you need from the stored faces, tracklets, frames, pedestrians, match results and streams, and it lets you subscribe to events as they happen. It is the API Station uses for its event history and live views, and the one to use for reporting, attendance-style queries and event-driven integrations.

Where the client runs	Endpoint
On the host or elsewhere on the network	http://localhost:8097/graphql
In a container on face-matcher-network	http://graphql-api:8080/graphql

The schema is available as SDL at http://localhost:8097/graphql?sdl for code generation. Authentication is off by default; with Authentication__* enabled, send a bearer token on every request and on the subscription connection, see the Authentication guide.

Queries

A query is a request-response call over HTTP POST. Every collection supports where filters, order, and paging with take and skip; the result wraps the rows in items next to totalCount and pageInfo.

query {
  matchResults(take: 100, order: { createdAt: DESC }) {
    items {
      createdAt
      watchlistMemberFullName
      watchlistMemberDisplayName
      watchlistFullName
      watchlistDisplayName
      score
    }
  }
}

A single response returns at most 1000 items. Page through larger result sets with take: 1000 and an increasing skip, or narrow the time range in where. Images are not embedded in query results; a face or frame carries an imageDataId, which you resolve through the REST Image endpoint or directly from S3 storage.

Subscriptions

A subscription keeps a connection open and the server pushes an event each time something matching your selection happens. Subscriptions run over WebSocket on the same /graphql path; any GraphQL client library that supports subscriptions can consume them.

subscription {
  matchResult {
    watchlistFullName
    watchlistMemberFullName
    streamId
    spoofCheck {
      performed
      passed
      distantLivenessSpoofCheck {
        performed
        passed
        score
      }
    }
    cropImage
  }
}

The main subscription topics are matchResult and noMatchResult (a face matched, or did not match, a watchlist member), faceProcessed, pedestrianProcessed and objectProcessed (direct notifications for every detection), identificationEvent and frameProcessed (one event per processed frame with all objects and their identification results), and the database-backed faceCreated, faceExtracted, matchResultInsert, trackletCompleted and pedestrianInserted. Event notifications include the extracted face template because the deployment sets Notifications__IncludeTemplates=true; stacks built on top, such as Smart Corridor, rely on this. The same events are also available on the message broker, see RabbitMQ notifications, which also explains the difference between direct and database notifications.

Working with the API

For ad-hoc queries and debugging, open http://localhost:8097/graphql in a browser: the built-in GraphQL IDE lets you write and run queries and subscriptions, browse the schema and inspect responses without installing anything.

For saved requests, environments and automated testing, use a full-featured client such as Insomnia or Postman; both understand GraphQL and subscriptions and can hold the bearer token when authentication is on.

In your own application, send queries as an HTTP POST with a JSON body { "query": "...", "variables": { ... } }, or use a GraphQL client library for your language; subscriptions require a library with WebSocket support. Ready-to-adapt queries and subscriptions are collected in GraphQL samples.