Quickstart

Prerequisites

• An active Brookmimir account and a valid API key (64-character hexadecimal token).
• A command-line HTTP tool (curl, HTTPie) or the official Python SDK.
• Basic JSON familiarity.

1. Confirm connectivity and API version.
2. Inspect your credit balance.
3. Run a safe search (/query) or fetch a known document (/document).
4. Use /face/search only after validating credits and payload sizing.

---

Verify service and version

Check the service quickly with /version (no credits consumed).

GET https://api.brookmimir.com/version
Accept: application/json

Expected response:

{
  "status": 200,
  "version": "1.3.0"
}

Use this call in CI or health checks to detect environment drift.

Tip

Because /version is unauthenticated, it is safe to include in publicly accessible monitoring dashboards.

---

Inspect credits (always do this before billable calls)

The /credits endpoint returns your remaining balance and does not deduct credits.

GET https://api.brookmimir.com/credits
x-api-key: YOUR_64_CHAR_HEX_KEY
Accept: application/json

Successful response example:

{
  "status": 200,
  "message": "Credits retrieved",
  "current_balance": 4287
}

If current_balance is 0, the API will return HTTP 402 for billable endpoints until credits are replenished.

---

Fetch a document (billable)

GET /document retrieves a canonical document by its Brookmimir identifier. This endpoint consumes one credit after header validation succeeds.

Headers required:

• x-api-key — your 64-character token
• bmm-doc-id — the Brookmimir document identifier

GET https://api.brookmimir.com/document
x-api-key: YOUR_64_CHAR_HEX_KEY
bmm-doc-id: DOC-123456
Accept: application/json

On success you receive a document payload. On insufficient credits you will get HTTP 402; on a missing document you will get a StatusMessage describing the issue.

---

Run a search query (billable)

POST /query accepts JSON search bodies. The call deducts one credit after validation.

Example request:

POST https://api.brookmimir.com/query
x-api-key: YOUR_64_CHAR_HEX_KEY
Content-Type: application/json
Accept: application/json

{
  "query": "forensic accountant profile",
  "top_k": 5,
  "filters": { "jurisdiction": ["US"] }
}

A 200 response contains the search results. If credits are exhausted, expect HTTP 402.

Caution

Avoid issuing bulk queries without first checking /credits. Each validated query consumes a credit.

---

Face search (billable, higher cost)

POST /face/search proxies biometric payloads to Brookmimir’s face search service and consumes one credit per validated request.

Supported payloads:

• probe_image_b64 — base64-encoded image (preferred when hosting images is not possible)
• probe_image_url — HTTPS image URL
• top_k — optional result limit

Example:

POST https://api.brookmimir.com/face/search
x-api-key: YOUR_64_CHAR_HEX_KEY
Content-Type: application/json

{
  "probe_image_b64": "BASE64_STRING",
  "top_k": 3
}

Errors:

• 400 for malformed payloads
• 402 for insufficient credits
• 502 for upstream failures from the biometric service

---

Lightweight connectivity probe

Use /nettest or / as a fast pre-flight check from your infrastructure to verify network reachability before running workflows that might consume credits.

GET https://api.brookmimir.com/nettest
Accept: application/json

---

Examples: python SDK (recommended)

Use the official Python SDK for thread-safe, validated requests and automatic header management.

Basic synchronous example:

from odins_eye import OdinsEyeClient, OdinsEyeAPIError

client = OdinsEyeClient(
    api_key="0123...abcd"      # 64 hex characters
)

# Check credits first
credits = client.credits()
if credits.get("current_balance", 0) == 0:
    raise SystemExit("No credits — refill before continuing")

# Search
try:
    resp = client.query({"query": "forensic accountant profile", "top_k": 5})
    documents = resp.get("resp", {}).get("body", {}).get("hits", {}).get("documents", [])
    for hit in documents:
        print(hit["doc_id"], hit.get("confidence"))
except OdinsEyeAPIError as e:
    print("API error:", e.status_code, e.message)

Async example:

from odins_eye import AsyncOdinsEyeClient
import asyncio

async def run():
    async with AsyncOdinsEyeClient(api_key="0123...abcd") as client:
        credits = await client.credits()
        print("balance:", credits.get("current_balance"))

asyncio.run(run())

---

Best practices

• Always call /credits before running billable endpoints (/document, /query, /face/search).
• Keep API keys secret and rotate them regularly.
• Implement exponential backoff and a retry policy for transient 5xx/429 responses.
• Persist bmm-doc-id values returned from searches to avoid repeated lookups.
• Log request status and message fields to accelerate troubleshooting.

Troubleshooting Checklist

1. 400 responses: confirm headers and JSON validity.
2. 402 responses: top up credits or gate operations behind balance checks.
3. 404 responses: validate bmm-doc-id and API key.
4. 5xx responses: retry with backoff and surface request_id to support.

---

Where to go next

• Read the Reference section for endpoint-specific schemas and example payloads.
• Use the Python SDK to handle retries, validation, and response parsing for you.
• Integrate /nettest into your monitoring runbooks as a pre-flight indicator.