> ## Documentation Index
> Fetch the complete documentation index at: https://agenticbanking.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

> Endpoints, fields, formats, limits, and error codes for the optical character recognition (OCR) API and the Document Retrieval Model Context Protocol (MCP) server.

This page lists endpoints, fields, limits, and error codes for the optical character recognition (OCR) API and the Document Retrieval Model Context Protocol (MCP) server.

## Base URLs

The following table lists the base URLs for document processing. Replace `{baseURL}` with your installation's API gateway URL, `https://api.<runtime>.<installation>.gcservices.io`.

| API | URL | Transport |
| :- | :- | :- |
| OCR API | `{baseURL}/ocr/v0` | REST over HTTPS |
| Document Retrieval MCP API | `{baseURL}/document-retrieval-mcp/v0/mcp` | MCP over Streamable HTTP |

Both APIs require a subscription key in the `api-key` header. You can also pass the key as the `api-key` query parameter.

## Supported operations

The OCR API supports the following operations.

### Convert a file to markdown

POST `{baseURL}/ocr/v0/convert`

Converts a PDF or image to markdown. MCP tool: `convert_file_to_markdown`.

The following table describes the request body fields.

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| `file_url` | string (URI, 1 to 2083 characters) | Yes | URL of the PDF or image to convert |
| `mode` | string: `default` or `premium` | No | OCR mode. Defaults to `default` |

The following table describes the response body fields.

| Field | Type | Description |
| :- | :- | :- |
| `content` | string | Markdown for the whole document. Each page or chunk starts with a marker such as `========== Page 1 ==========` or `========== Pages 1-20 ==========` |
| `metadata.mode` | string | Mode that produced the result. Differs from the requested mode when the service falls back |
| `metadata.model` | string | OCR model that produced the result |
| `metadata.page_count` | integer | Number of pages in the document. Images count as one page |
| `metadata.chunk_count` | integer | Number of chunks the service splits the document into for OCR |
| `metadata.output_chars` | integer | Length of `content` in characters |

### Fetch text content

POST `{baseURL}/ocr/v0/text`

Returns the content of a text file without OCR. MCP tool: `fetch_text_content`.

The request body uses the same fields as [Convert a file to markdown](#convert-a-file-to-markdown). The service ignores `mode`.

The following table describes the response body fields.

| Field | Type | Description |
| :- | :- | :- |
| `content` | string | File content, decoded as UTF-8 |
| `metadata` | null | Always `null` for text files |

### Check service health

GET `{baseURL}/ocr/v0/health`

Returns the status of the OCR service. This operation isn't available as an MCP tool.

The following table describes the response body fields.

| Field | Type | Description |
| :- | :- | :- |
| `status` | string | `healthy` when the service is running |
| `uptime_seconds` | number | Time since the service started |
| `timestamp` | string | Current server time in ISO 8601 format |

## MCP tools

The following table lists the tools that the Document Retrieval MCP server exposes. Each tool takes the same arguments as the matching REST request body and returns the same JSON as the REST response, as text content.

| Tool | REST operation | Arguments |
| :- | :- | :- |
| `convert_file_to_markdown` | `POST /convert` | `file_url` (required), `mode` (optional) |
| `fetch_text_content` | `POST /text` | `file_url` (required) |

## Supported file formats

The following table lists the file formats that each operation accepts. Extensions are case-insensitive.

| Format | Extensions | Operation |
| :- | :- | :- |
| PDF | `.pdf` | Convert |
| Image | `.jpg`, `.jpeg`, `.png`, `.tiff` | Convert |
| Text | `.txt`, `.json`, `.csv`, `.md`, `.xml` | Fetch text |

For HTTPS URLs without a file extension, the service treats the file as a PDF when the URL path contains a `pdf` segment, for example `https://arxiv.org/pdf/1706.03762`.

## Document sources

The following table shows how the service downloads files, based on the URL.

| Source | URL pattern | How the service reads the file |
| :- | :- | :- |
| Allowed Azure Blob Storage containers | `https://<account>.blob.core.windows.net/<container>/<blob>`, where your installation allows the account and container | Reads the blob with the platform's managed identity. You don't need a shared access signature (SAS) token |
| Other Azure Blob Storage containers | A SAS URL, `https://<account>.blob.core.windows.net/<container>/<blob>?<sas-token>` | Downloads the file over HTTPS with the SAS token |
| HTTPS URLs | Any other `https://` URL | Downloads the file over HTTPS. The URL must be reachable without authentication |

## OCR modes and models

The following table lists the OCR modes and the models behind them.

| Mode | Model | Best for |
| :- | :- | :- |
| `default` | Mistral OCR (`mistral-ocr-4-0`) | Standard documents. Fast and cost-effective |
| `premium` | Claude (`claude-sonnet-5`) | Complex layouts, charts, tables, and documents that need reasoning |

If the selected mode fails or returns no text, the service retries the document with the other mode. The `metadata.mode` and `metadata.model` fields show which mode and model produced the result. The request fails only when both modes fail.

## Limits

The following table lists the service limits.

| Limit | Value |
| :- | :- |
| Maximum file size | 50 MB |
| Pages per OCR chunk | 20. The service splits longer PDFs into chunks and processes them in order. |
| `file_url` length | 2083 characters |
| OCR model timeout | 1200 seconds per chunk |
| MCP server timeout | 300 seconds per tool call |
| Rate limit | 100 calls per 60 seconds per subscription |

## Error codes

The following table lists the HTTP status codes that the APIs return.

| Status code | Description |
| :- | :- |
| `200` | Success |
| `400` | The file type isn't supported by the operation, or the URL has no file extension. `POST /text` also returns 400 when the blob container isn't allowed and the URL has no SAS token. `POST /convert` downloads that blob over HTTPS. A failed download returns 500. |
| `401` | The subscription key is missing or invalid |
| `404` | The path doesn't exist. Check that the path includes the version segment, for example `/v0` |
| `413` | The file exceeds the maximum file size |
| `422` | The request body is invalid, for example `file_url` is missing or isn't a valid URL |
| `429` | The subscription exceeded its rate limit |
| `500` | The service couldn't download the file, or both OCR modes failed. On `POST /convert`, a blob outside the allowlist returns 500 when the HTTPS download fails. |

MCP clients surface these failures as tool errors.

## Service configuration

Backbase manages the service configuration. To change a setting, for example to allow another Azure Blob Storage container, contact your Backbase support team.

The following table lists the settings that affect how the OCR service behaves.

| Environment variable | Default | Description |
| :- | :- | :- |
| `AZURE_BLOB_ACCOUNT_NAME` | Set by your installation | Storage account that the service reads with its managed identity |
| `AZURE_BLOB_ALLOWED_CONTAINERS` | Set by your installation | Containers in that account that the service can read. Must be a JSON list |
| `MAX_DOCUMENT_SIZE_MB` | `50` | Maximum file size in megabytes |
| `OCR_MAX_PAGES_PER_REQUEST` | `20` | Maximum pages in each OCR chunk |
| `OCR_TIMEOUT` | `1200` | Timeout in seconds for each OCR model call |

The Document Retrieval MCP server has one setting, `DOCUMENT_RETRIEVAL_API_URL`, which points to the OCR service. The server loads the OpenAPI specification for the OCR API from this URL at startup.