Your first API call

This page walks through one full request — minting a key, sending a biofrq.detect call, and reading the response. End-to-end in under five minutes.

1. Mint a key

From the dashboard, open the command palette (⌘K / Ctrl+K) and pick API Keys → Create a new key. Give it a label, an optional expiry, and let the project default to your active project.

The dashboard reveals the full key string once. Copy it before you close the dialog.

2. Pick an image

biofrq.detect takes a single image and returns face bounding boxes plus confidence scores. Any frontal-ish photo works for a first call — a passport-style selfie, a phone snap, or a sample from your test set.

Images go on the wire as base64-encoded bytes inside an ImageItem object under params.images[]. You also tell the API the content type (image/jpeg or image/png). The same envelope is used by every other action that takes an image. See Envelope → Image inputs for the full shape.

3. Send the request

Replace bfq_live_… with the key you minted in step 1, and <base64> with the base64-encoded bytes of your image (no data: URL prefix).

curl -X POST https://api.biofrq.com/v1/face/execute \
  -H "X-Api-Key: bfq_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "biofrq.detect",
    "params": {
      "images": [
        {
          "kind": "image",
          "bytes": "<base64>",
          "contentType": "image/jpeg"
        }
      ]
    }
  }'

4. Read the response

A successful biofrq.detect looks like:

{
  "ok": true,
  "requestId": "2c3f8b1a-9ed3-7c4a-8a1b-...",
  "action": "biofrq.detect",
  "data": {
    "results": [
      {
        "index": 0,
        "correlationId": "auto-0",
        "ok": true,
        "value": {
          "faces": [
            {
              "faceBox": { "x": 142, "y": 87, "w": 218, "h": 218 },
              "confidence": 0.992
            }
          ]
        }
      }
    ]
  },
  "errors": []
}

Three fields matter:

• ok — top-level success flag. true means the action ran cleanly; branch on this, not on the HTTP status (envelope failures still come back as 200 with ok: false).
• requestId — the join key against the dashboard's RequestLog and Money Audit.
• data.results[0].value — the per-action payload. For detect, an array of faces (which may be empty — still a success, still billed).

5. What's next

The other eight actions follow the same envelope — swap action and params, the rest of the request shape is identical:

• biofrq.liveness — live / spoof verdict for one face.
• biofrq.verify — 1:1 match between two images, or one image and an enrolled subjectId.
• biofrq.identify — 1:N search across the project's gallery.
• biofrq.enroll — add a face template to the gallery.
• biofrq.update — mutate subject metadata + group membership.
• biofrq.deleteSubject — destructive removal.
• biofrq.analyze — detect + liveness + attributes in one call.
• biofrq.attributes — attribute predictions without liveness.

Each action has its own page in the API reference section. Start there once you've got the envelope feel.