POST /face/search

The POST /face/search endpoint forwards image payloads to Brookmimir’s facial recognition service. Each validated request deducts one credit before the proxy forwards the payload.

Request

• Method: POST
• Path: /face/search
• Authentication: Required (x-api-key header)
• Headers:
  • x-api-key — Required. Your Brookmimir credential.
  • Content-Type: application/json
  • Optional accept: application/json

set BASE64 $(cat ./image.b64)
  curl -X POST http://api.brookmimir.com/face/search \
        -H "Content-Type: application/json" \
         -H "x-api-key: 1234567890" \
        -d "{\"image_base64\":\"$BASE64\",\"top_k\":5}"

Request body

The request body is a JSON object whose structure depends on your biometric workflow. Brookmimir permits additional keys and nested objects so you can tailor the payload to the downstream recognition engine.

Field	Type	Required	Description
image_b64	string	Yes	Base64-encoded image data
x-api-key	string	Yes	x-api-key
top_k	integer	No	Number of top results to return. Limit is 10

Successful response

• HTTP status: 200 OK

{
  "status": 200,
  "matches": [
    {
      "doc_id": "DOC-4411992",
      "confidence": 0.91,
      "face_file": "https://assets.brookmimir.com/matches/4411992.jpg",
      "attributes": {
        "
      }
    },
    {
      "doc_id": "DOC-3378510",
      "confidence": 0.84,
      "face_file": "https://assets.brookmimir.com/matches/3378510.jpg"
    }
  ],
}

Error handling

Status	Scenario	Response schema	Guidance
400	Missing headers or malformed body.	StatusMessage	Ensure the JSON payload and required fields are present before retrying.
401/403	Authentication failure.	StatusMessage	Verify credentials, transmit over TLS, and rotate keys regularly.
402	Credit balance depleted.	StatusMessage	Refill credits or pause billable calls before retrying.
404	Token or resource not found.	StatusMessage	Confirm the API key is active and the requested resource exists.
5xx	Downstream engine or platform disruption.	StatusMessage	Retry with exponential backoff, capture request identifiers, and alert Brookmimir support.

Sample 422 response

{
  "status": 400,
  "message": "Body must include 'image_b64'."
}

Best practices

1. Secure image transport: Host probe images on HTTPS endpoints or use image_b64 to avoid unauthorized interception.
2. Tune thresholds: Start with the service default, then adjust threshold and max_results based on match quality and false-positive tolerance.
3. Log audits: Record request metadata (excluding sensitive image data) and response confidences to satisfy governance requirements.
4. Pair with /credits: Large-scale biometric searches may consume more credits; monitor balance before launching batch operations.
5. Fallback logic: Gracefully handle empty matches arrays by triggering manual review or alternate identification workflows.

By following these guidelines, you can embed Brookmimir’s biometric intelligence into investigative pipelines while maintaining observability, compliance, and user trust.