GET /document

The GET /document endpoint returns the document payload associated with a Brookmimir identifier. Provide a valid API key and document ID to receive the canonical record. The call consumes one credit after the headers pass validation and falls back to a StatusMessage when the resource cannot be returned.

Request

• Method: GET
• Path: /document
• Authentication: Required (x-api-key header)
• Headers:
  • x-api-key: Required 64-character hexadecimal token tied to your account.
  • bmm-doc-id: Required identifier for the document you want to retrieve.
  • Optional accept: application/json

curl -s "https://api.brookmimir.com/document" \
        -H "x-api-key: 1234" \
        -H "bmm-doc-id: 5678abc" | jq

Header reference

Header	Type	Required	Description
x-api-key	string	Yes	Grants access to account-scoped resources.
bmm-doc-id	string	Yes	Unique Brookmimir document identifier to retrieve.

Tip: Store bmm-doc-id values in your downstream systems to enable rapid retrieval via this route.

Calling /document deducts one credit after the headers pass validation. Requests with zero balance return HTTP 402 before the record is accessed.

Successful response

• HTTP status: 200 OK
• Body schema: EsResponse or StatusMessage

When the document exists and is accessible, the response contains an EsResponse object with the raw payload in body.

If the document cannot be found or another informational condition occurs, you will receive a `StatusMessage` instead.

```json
{
  "status": 404,
  "message": "Document not found"
}

Error handling

Status	Scenario	Response schema	Guidance
400	Missing or malformed headers.	StatusMessage	Ensure x-api-key and bmm-doc-id are present and properly formatted.
401/403	Authentication failure.	StatusMessage	Verify the key is active and applied to the request over HTTPS.
402	Credit balance depleted.	StatusMessage	Refill credits or pause billable calls before retrying.
404	Document or token not found.	StatusMessage	Confirm the identifier and regenerate credentials if necessary.
5xx	Temporary platform issue.	StatusMessage	Retry with exponential backoff and capture request metadata.

Sample 422 response

{
  "status": 400,
  "message": "Header 'bmm-doc-id' is required."
}

Best practices

1. Cache identifiers: Persist bmm-doc-id values returned from /query to enable quick document retrieval later.
2. Protect secrets: Mask API keys in logs and rotate them regularly.
3. Watch credits: Call /credits before bulk /document requests to avoid unexpected 402 responses.
4. Log context: Record status, message, and bmm-doc-id values to streamline support investigations.
5. Alert on failures: Surface repeated 4xx/5xx responses so operators can intervene quickly.