Brookmimir API Reference

Authentication & credits

• Provide a 64-character hexadecimal token in the x-api-key header for any request that reads protected data.
• Billable endpoints (/document, /query, /face/search) deduct one credit after validation but before the payload is processed.
• When the balance reaches zero, the API returns HTTP 402 and instructs the caller to purchase more credits.
• Use /credits to inspect balances without consuming credits.

Required headers

Header	Description	Required
x-api-key	64-character token used for authentication and credit accounting	Yes, except /, /profile, /version, /nettest
bmm-doc-id	Document identifier used by /document	Yes, for /document

All JSON request bodies must declare Content-Type: application/json.

Standard response envelope

Most responses follow the same envelope with endpoint-specific fields added as needed.

{
  "status": 200,
  "message": "optional explanation",
  "...": "endpoint-specific payload"
}

Errors use the same structure with a non-200 status and descriptive message.

Error handling

Status	Meaning	Typical causes
400	Invalid request	Missing headers, malformed body, key format violation
402	Not enough credits	Credit balance is zero
404	Resource not found	Unknown token, missing document
500	Internal error	Unexpected exception
502	Upstream dependency failure	Downstream services unavailable

All server-side exceptions are logged with structured metadata so incidents can be traced quickly.

Endpoint summary

Method	Path	Auth	Credits	Description
GET	/	No	No	Health-style greeting message
GET	/version	No	No	Returns API version metadata (1.0.0)
GET	/profile	No	No	Static demo profile payload
GET	/credits	Yes	No	Retrieves remaining credit balance
GET	/document	Yes	Yes	Fetches a document payload by identifier
POST	/query	Yes	Yes	Executes a search query and returns matches
POST	/face/search	Yes	Yes	Proxies to the configured face search service
GET	/nettest	No	No	Connectivity diagnostic request

Endpoint details

GET /

Returns a simple status message useful for availability checks.

{
  "status": 200,
  "message": "please choose an endpoint"
}

GET /version

Exposes the deployed semantic version. The current release returns 1.0.0 even though the underlying application may use a higher tag.

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

GET /profile

Delivers a placeholder profile document that can be used to confirm the account context.

{
  "status": 200,
  "message": "User Profile",
  "user": {
    "name": "John Doe",
    "age": 30
  }
}

GET /credits

Checks the remaining credit balance without deducting from it.

curl -X GET "$BASE_URL/credits" \
  -H "x-api-key: $API_KEY"

Responses include current_balance on success, HTTP 402 when the balance is zero, and HTTP 404 if the token is unknown.

GET /document

Retrieves a single document by its Brookmimir identifier.

• Required headers: x-api-key, bmm-doc-id.

curl -X GET "$BASE_URL/document" \
  -H "x-api-key: $API_KEY" \
  -H "bmm-doc-id: $DOC_ID"

Successful calls return a payload similar to:

{
  "statusCode": 200,
  "body": {
    "...": "document fields"
  }
}

If the identifier is unknown, the service responds with a StatusMessage describing the issue.

POST /query

Executes a search query and returns the result set inside a resp object.

curl -X POST "$BASE_URL/query" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "query": { "match": { "field": "value" } }
      }'

A 200 response includes the structured matches while a depleted credit balance produces HTTP 402.

POST /face/search

Forwards biometric lookup requests to the configured face search service after deducting one credit.

curl -X POST "$BASE_URL/face/search" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "image_base64": "BASE64_STRING",
        "top_k": 3
      }'

The response mirrors the downstream service output. Validation issues return HTTP 400, and upstream failures result in HTTP 502.

GET /nettest

Performs a lightweight connectivity diagnostic (for example, verifying access to https://example.com) without requiring authentication.

Usage tips

• Call /nettest or / before launching workflows that would consume credits.
• Cache document identifiers returned from /query so that repeated /document lookups are quick.
• Log response status codes and message values to streamline incident triage.
• Rotate API keys regularly and monitor /credits to avoid unexpected 402 responses.

By following these guidelines and the standard envelope, you can integrate quickly with the Brookmimir Odin’s Eye API while maintaining a predictable credit management experience.