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

# Read as Markdown

> Extract document content as markdown for your agent to read

## Read Document as Markdown

Extract document content as markdown text. Your agent should use this to read documents before editing and verify changes after edits are applied.

### Path Parameters

<ParamField path="doc_id" type="string" required>
  The unique identifier of the document (UUID)
</ParamField>

### Request Body

<ParamField body="readUid" type="string" required>
  Client-provided UUID for idempotency and tracking. Generate a new UUID for
  each read request.
</ParamField>

### Response

<ResponseField name="readUid" type="string" required>
  The UUID of the read operation (same as request)
</ResponseField>

<ResponseField name="markdown" type="string" required>
  Markdown representation of the document content
</ResponseField>

<ResponseField name="timeToGenerate" type="number" required>
  Time taken to generate the markdown in seconds
</ResponseField>

<ResponseField name="documentName" type="string" required>
  Name of the document
</ResponseField>

<ResponseField name="documentId" type="string" required>
  UUID of the document
</ResponseField>

### Code Examples

<CodeGroup>
  ```javascript JavaScript (Fetch) theme={null}
  import { v4 as uuidv4 } from "uuid";

  const docId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";

  const response = await fetch(
    `https://api.agentoffice.dev/v1/documents/${docId}/markdown`,
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        readUid: uuidv4(),
      }),
    }
  );

  const data = await response.json();
  console.log("Markdown content:");
  console.log(data.markdown);
  ```

  ```python Python (Requests) theme={null}
  import requests
  import uuid

  doc_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  url = f'https://api.agentoffice.dev/v1/documents/{doc_id}/markdown'

  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
  }

  payload = {
      'readUid': str(uuid.uuid4())
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()

  print('Markdown content:')
  print(data['markdown'])
  print(f"\nGenerated in {data['timeToGenerate']} seconds")
  ```

  ```python Python SDK theme={null}
  from agent_office import AgentOffice

  client = AgentOffice(api_key="YOUR_API_KEY")

  doc_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  result = client.read(doc_id=doc_id)

  print("Markdown content:")
  print(result.markdown)
  print(f"\nGenerated in {result.time_to_generate} seconds")
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.agentoffice.dev/v1/documents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/markdown' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "readUid": "550e8400-e29b-41d4-a716-446655440000"
    }'
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "readUid": "550e8400-e29b-41d4-a716-446655440000",
  "markdown": "# Q4 Financial Report\n\n## Executive Summary\n\nThis report covers the financial performance for Q4 2024...\n\n## Revenue Analysis\n\n- Total Revenue: $2.5M\n- Growth: 15% YoY\n\n## Conclusion\n\nThe company showed strong performance in Q4.",
  "timeToGenerate": 2.1,
  "documentName": "report.docx",
  "documentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

## Use Cases

<CardGroup cols={2}>
  <Card title="Content Extraction" icon="file-lines">
    Extract document content for search indexing or data processing
  </Card>

  <Card title="AI Integration" icon="brain">
    Feed document content to LLMs for analysis or summarization
  </Card>

  <Card title="Version Control" icon="code-branch">
    Track document changes in markdown-friendly version control systems
  </Card>

  <Card title="Web Display" icon="globe">
    Display document content on websites using markdown renderers
  </Card>
</CardGroup>

## Processing Markdown Content

Here's how to use the markdown output in different scenarios:

<CodeGroup>
  ```javascript Search & Analysis theme={null}
  import { v4 as uuidv4 } from "uuid";

  // Get markdown
  const response = await fetch(
    `https://api.agentoffice.dev/v1/documents/${docId}/markdown`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ readUid: uuidv4() }),
    }
  );

  const { markdown } = await response.json();

  // Search for specific content
  if (markdown.includes("financial report")) {
    console.log("Found financial report content");
  }

  // Extract headers
  const headers = markdown.match(/^#{1,6} .+$/gm);
  console.log("Document headers:", headers);
  ```

  ```python AI Analysis with OpenAI theme={null}
  from agent_office import AgentOffice
  from openai import OpenAI

  # Get document as markdown
  agent_office = AgentOffice(api_key="YOUR_AGENT_OFFICE_KEY")
  result = agent_office.read(doc_id=doc_id)
  markdown = result.markdown

  # Analyze with OpenAI
  openai_client = OpenAI()
  completion = openai_client.chat.completions.create(
      model="gpt-4",
      messages=[
          {
              "role": "user",
              "content": f"Summarize this document:\n\n{markdown}"
          }
      ]
  )

  print(completion.choices[0].message.content)
  ```

  ```javascript Save to File theme={null}
  import fs from "fs";
  import { v4 as uuidv4 } from "uuid";

  const response = await fetch(
    `https://api.agentoffice.dev/v1/documents/${docId}/markdown`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ readUid: uuidv4() }),
    }
  );

  const { markdown, documentName } = await response.json();

  // Save as .md file
  const mdFilename = documentName.replace(/\.[^/.]+$/, ".md");
  fs.writeFileSync(mdFilename, markdown);

  console.log(`Saved to ${mdFilename}`);
  ```
</CodeGroup>

## Markdown Formatting

The markdown output preserves document structure including:

* **Headings**: Converted to markdown headers (# ## ###)
* **Lists**: Bullet points and numbered lists
* **Tables**: Formatted as markdown tables
* **Bold/Italic**: Text formatting preserved
* **Links**: Hyperlinks maintained
* **Images**: Image references with descriptions (if available)

### Example Conversion

<Tabs>
  <Tab title="Original Document">
    A Word document with:

    * Heading: "Financial Report"
    * Bold text: "Q4 Results"
    * Table with revenue data
    * Bulleted list of achievements
  </Tab>

  <Tab title="Markdown Output">
    ```markdown theme={null}
    # Financial Report

    **Q4 Results**

    | Quarter | Revenue | Growth |
    | ------- | ------- | ------ |
    | Q4      | $2.5M   | 15%    |

    - Exceeded revenue targets
    - Expanded to new markets
    - Launched 3 new products

    ```
  </Tab>
</Tabs>

## Alternative: Get Markdown During Upload

You can also request markdown when uploading a document by setting `return_markdown=true`:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const formData = new FormData();
  formData.append("file", file);
  formData.append("return_markdown", "true");

  const response = await fetch("https://api.agentoffice.dev/v1/documents/", {
    method: "POST",
    headers: { Authorization: `Bearer ${API_KEY}` },
    body: formData,
  });

  const { docId, markdown } = await response.json();
  console.log("Markdown:", markdown);
  ```

  ```python Python theme={null}
  files = {'file': open('document.docx', 'rb')}
  data = {'return_markdown': True}

  response = requests.post(
      'https://api.agentoffice.dev/v1/documents/',
      headers={'Authorization': f'Bearer {API_KEY}'},
      files=files,
      data=data
  )

  result = response.json()
  print(result['markdown'])
  ```
</CodeGroup>

## Queue Processing

Like edits, markdown read operations are queued per document to ensure consistency:

```javascript theme={null}
// Multiple read requests to the same document are processed sequentially
const read1 = fetch(
  `https://api.agentoffice.dev/v1/documents/${docId}/markdown`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ readUid: uuidv4() }),
  }
);

const read2 = fetch(
  `https://api.agentoffice.dev/v1/documents/${docId}/markdown`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ readUid: uuidv4() }),
  }
);

// Both will complete, processed in order
const [result1, result2] = await Promise.all([read1, read2]);
```

## Error Responses

<ResponseExample>
  ```json 404 Not Found theme={null}
  {
    "detail": "Document not found or has expired"
  }
  ```

  ```json 408 Timeout theme={null}
  {
    "detail": "Markdown read operation timed out after 5 minutes"
  }
  ```

  ```json 500 Server Error theme={null}
  {
    "detail": "Failed to generate markdown: Unsupported document format"
  }
  ```
</ResponseExample>

<Note>
  Markdown generation typically takes 1-5 seconds depending on document
  complexity.
</Note>