biofrq

biofrq.identify

1:N search. Returns up to topK candidates by similarity, scoped to the API key's project. An optional predicate narrows the search by group, attributes, or date range.

Params

FieldTypeRequiredDefaultNotes
images[0]ImageItemyes—Probe image. See Envelope → Image inputs.
topKintnoserver defaultMax candidates returned. Must be > 0.
thresholdfloatnotenant default0–1. Candidates below this score are dropped.
predicateobjectno—Closed-set, AND-only filter. See below.

predicate shape

Any field set to null is skipped.

json
{
  "groupNames":         ["VipCustomers"],
  "subjectIds":         null,
  "externalIds":        null,
  "attributesContains": { "client": "alpha" },
  "createdAfter":       null,
  "createdBefore":      null
}
  • groupNames — OR-list. A subject matches if any listed group overlaps its Groups array.
  • subjectIds, externalIds — IN-list (max 1000 entries each).
  • attributesContains — JSONB @> superset match against the subject's attributes map.
  • createdAfter / createdBefore — ISO-8601 UTC, exclusive bounds.
  • Empty arrays are rejected with INVALID_REQUEST — use null to skip the filter.

tenantId is never in the predicate; it's derived from your API key.

Request

json
{
  "action": "biofrq.identify",
  "params": {
    "images": [
      { "kind": "image", "bytes": "<base64>", "contentType": "image/jpeg" }
    ],
    "predicate": {
      "groupNames": ["VipCustomers"],
      "subjectIds":  null,
      "externalIds": null,
      "attributesContains": null,
      "createdAfter":  null,
      "createdBefore": null
    },
    "topK": 5,
    "threshold": 0.5
  }
}

Response

json
{
  "ok": true,
  "requestId": "...",
  "action": "biofrq.identify",
  "data": {
    "results": [
      {
        "index": 0,
        "correlationId": "auto-0",
        "ok": true,
        "value": {
          "candidates": [
            {
              "subjectId": "8a1c...",
              "externalId": "emp-4421",
              "groups": ["staff"],
              "score": 0.91
            }
          ]
        }
      }
    ]
  },
  "errors": []
}

Empty candidates = no match above threshold. Still a successful response, still billed.

Common errors

  • INVALID_REQUEST — no face in the probe; topK ≤ 0; malformed predicate; empty array in any predicate IN-list.

Scope

The gallery searched is the gallery of the project the API key belongs to. Cross-project search is not supported in a single call.

Open in playgroundbiofrq.identify