POST /query

The POST /query endpoint is your primary interface for searching the Brookmimir Odin’s Eye corpus. Submit a JSON payload that captures your search intent—keywords, filters, or scoring instructions—and receive a QueryResponse containing a JSON result set. Each validated request deducts one credit before the search executes, so monitor balances closely. This route is ideal for investigative discovery, entity surfacing, and workflow automation.

Request

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

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

{ “query”: “forensic accountant profile”, “top_k”: 5, “filters”: { “jurisdiction”: [“US”, “CA”] } }

### Request body

The request body is a flexible JSON object. Brookmimir accepts additional custom fields to tune search behavior.

| Field      | Type             | Required | Description                                                                                |
|------------|------------------|---------- |--------------------------------------------------------------------------------------------|
| `query`    | string           | Yes       | Primary search text or semantic prompt.                                                   |
| `x-api-key`  | String           | Yes       | API Key                                                                                   |

> **Tip:** Coordinate with your Brookmimir solutions engineer to align on advanced filter names and contextual parameters available to your tenant.

## Successful response

- **HTTP status:** `200 OK`
- **Body schema:** `QueryResponse`
  - `status` (integer) — Numeric outcome indicator (typically `200`).
  - `resp` (`EsResponse`) — Contains the raw search results.

```json
{
  "status": 200,
  "resp": {
    "statusCode": 200,
    "body": {
      "hits": {
        "total": 38,
        "documents": [
          {
            "doc_id": "DOC-8899001",
            "title": "Forensic Accountant Profile: North America",
            "confidence": 0.93
          },
          {
            "doc_id": "DOC-7765003",
            "title": "AML Specialist Profile",
            "confidence": 0.89
          }
        ]
      }
    }
  }
}

Error handling

Status	Scenario	Response schema	Guidance
400	Missing headers or malformed body.	StatusMessage	Confirm the x-api-key header and JSON payload meet requirements.
401/403	Authentication failure.	StatusMessage	Verify the key and transmit requests over HTTPS.
402	Credit balance depleted.	StatusMessage	Replenish credits or pause billable searches before retrying.
404	Token or resource not found.	StatusMessage	Ensure the key is active and the referenced resource exists.
5xx	Service-side or downstream issue.	StatusMessage	Retry with exponential backoff; capture request IDs for support review.

Sample 422 response

{
  "status": 400,
  "message": "Request body must include a 'query' field."
}

Best practices

1. Throttle intelligently: Space high-volume queries to respect rate limits and avoid unnecessary credit consumption.
2. Log context: Record payload metadata (excluding sensitive values) alongside returned doc_id and confidence scores for auditing.
3. Combine with /credits: Since each /query call consumes a credit, verify balances before broad searches to prevent unexpected 402 responses.
4. Secure inputs: Sanitize and validate user-generated search terms before forwarding them to Brookmimir to prevent injection-style abuse.