As developers increasingly build AI-powered applications, one challenge consistently emerges: how to feed documents to Large Language Models (LLMs) in a way that preserves structure and meaning. Today, we’re excited to introduce Box’s new markdown representation feature that solves this exact problem.
Why markdown matters for AI applications
When you extract text from a PDF or document, you typically get a flat string of text that loses all formatting, headers, tables, and structural information. This makes it harder for LLMs to understand the document’s organization and context.
Markdown representations preserve this crucial structure:
- Headers remain hierarchical (
# Title,## Section,### Subsection) - Tables maintain their columnar format
- Lists keep their organization
- Emphasis and formatting cues are preserved
This structured format helps LLMs better understand document context, leading to more accurate analysis, summarization, and Q&A responses.
How Box Markdown representations work
Box representations are alternative assets for files stored in your Box account. While we’ve always supported PDFs, thumbnails, and text extractions, the new markdown representation takes document processing a step further.
Getting started
First, request the available representations for your file. In this example were are checking the availability for markdown:
curl --location 'https://api.box.com/2.0/files/1993799099215?fields=id%2Cname%2Crepresentations' \
--header 'x-rep-hints: [markdown]' \
--header 'Authorization: ••••••'This returns information about the requested representations:
{
"type": "file",
"id": "1993799099215",
"etag": "1",
"name": "test.docx",
"representations": {
"entries": [
{
"representation": "markdown",
"properties": {},
"info": {
"url": "https://api.box.com/2.0/internal_files/1993799099215/versions/2200612360399/representations/markdown"
},
"status": {
"state": "none"
},
"content": {
"url_template": "https://dl.boxcloud.com/api/2.0/internal_files/1993799099215/versions/2200612360399/representations/markdown/content/{+asset_path}"
}
}
]
}
}Triggering Markdown generation
If the status shows "state": "none", the markdown representation hasn't been generated yet. Request it using the info URL:
{
"representation": "markdown",
"properties": {},
"info": {
"url": "https://api.box.com/2.0/internal_files/1993799099215/versions/2200612360399/representations/markdown"
},
"status": {
"state": "pending"
},
"content": {
"url_template": "https://dl.boxcloud.com/api/2.0/internal_files/1993799099215/versions/2200612360399/representations/markdown/content/{+asset_path}"
}
}Downloading the Markdown
Once processing completes (status changes to "success"), download the markdown content:
curl --location 'https://dl.boxcloud.com/api/2.0/internal_files/1993799099215/versions/2200612360399/representations/markdown/content/' \
--header 'Authorization: ••••••'For example:
AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation
Qingyun Wu , Gagan Bansal , Jieyu Zhang, Yiran Wu, Beibin Li, Erkang ...
# Abstract
AutoGen is an open-source framework that allows developers to build LLM ...
## Introduction
Large language models (LLMs) are becoming a crucial building block in ...
## Scope
In light of the intuition and early evidence of promise, it is ...
Our insight is to use multi-agent conversations to achieve it. There...
Here is a random UUID in the middle of the paragraph! 314b0a30-5b04- ...
* How can we design individual agents that are capable, reusable, ...
* How can we develop a straightforward, unified interface that can ...
In practice, applications of varying complexities may need distinct ...
Here is a random table for .docx parsing test purposes:
| | | | | | |
| --- | --- | --- | --- | --- | --- |
| 1 | 2 | 3 | 4 | 5 | 6 |
| 7 | 8 | 9 | 10 | 11 | 12 |
| 13 | 14 | ABC | 15 | 16 | 17 |
| 18 | 19 | 20 | 21 | 22 | 23 |
| 24 | 25 | 26 | 27 | 28 | 29 |Try it now with Box MCP Server
While we’re working on adding markdown representations to our official SDKs, you can experience this feature today through our Box MCP (Model Context Protocol) Server. This community edition tool integrates directly with Claude and other AI assistants, making it perfect for testing and prototyping.
Claude example: Analyzing a test document
Here is a sample document that I uploaded to my Box account:
Let’s ask Claude to read this file and inquire about it’s formatting:
Now let’s ask it to display the file:
When you use Box MCP Server with markdown representations, you’ll notice:
- Preserved document structure: Headers, sections, and formatting remain intact
- Better AI analysis: Claude can understand document hierarchy and provide more accurate summaries
- Interactive exploration: Ask questions about specific sections, and the AI can reference the exact part of the document
- Structured Outputs: Generate reports, extract data, or create summaries that respect the original document organization
The read file tool present in the community edition of the Box MCP server, will always try to get the markdown representation of the file, and fallback to text if it errors or is not available. Not all files can be converted to markdown or even text.
Supported file types
Markdown representations work with a wide range of document formats:
- Microsoft Office: Word (.docx), PowerPoint (.pptx), Excel (.xls, .xlsx, .xlsm)
- Google Workspace: Google Docs (.gdoc), Google Slides (.gslide, .gslides), Google Sheets (.gsheet)
- PDF files (.pdf)
Performance considerations
- Generation time: Markdown conversion depends on file size and content, and we’ve seen 200 milliseconds for a 3 page Microsoft Word document. Depending on your use case a proper polling mechanism is recommended.
- Caching: Generated representations are cached by Box for subsequent requests
Getting started today
Although the SDKs have not been updated yet, since the representations are parameter driven you can start to use them today. For example:
class RepresentationType(Enum):
MARKDOWN = "markdown"
EXTRACTED_TEXT = "extracted_text"
def box_file_text_extract(client: BoxClient, file_id: str) -> Dict[str, Any]:
"""
Extracts text from a file in Box. The result can be markdown or plain text.
If a markdown representation is available, it will be preferred.
Args:
client (BoxClient): An authenticated Box client.
file_id (str): The ID of the file to extract text from.
Returns:
Dict[str, Any]: The extracted text.
"""
# First we check if file representation markdown is available
representation = _process_file_representation(
client, RepresentationType.MARKDOWN, file_id
)
if (
representation.get("status") != FileRepresentationStatus.IMPOSSIBLE.value
and representation.get("status") != FileRepresentationStatus.ERROR.value
and representation.get("status") != FileRepresentationStatus.UNKNOWN.value
):
return representation
representation = _process_file_representation(
client, RepresentationType.EXTRACTED_TEXT, file_id
)
return representationYou can check the complete read file tool implementation in our community GitHub repo.
What’s next?
Box markdown representations are available now for all Box API users.
Have questions or want to share how you’re using markdown representations? Join the discussion in our Developer Community or check out our API documentation for complete implementation details.
Ready to build smarter AI applications? Start experimenting with Box markdown representations today and see how structured document content can transform your LLM integrations.
