Documentation / API overview

Parse

Read a document into its full data representation.

What you get

Parse reads the document as a whole, including its text, tables, and structure. The result gives your application or agent a data representation to work with rather than an editable document file.

When to use Parse

• Read a PDF’s contents for downstream processing.
• Work with document text and tables in your application.
• Provide document content to an agent for further analysis.

Request and response

Proposed API contract

Parse returns the document’s contents grouped by page and represented as typed blocks. This example shows a heading, paragraph, and table from a single-page report.

curl https://api.moda.app/v1/documents/parse \
  -H "Authorization: Bearer $MODA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "file_ref": "file_report_pdf"
}'

The request starts a job. Poll the returned poll_url until the status is completed or failed. See the shared job lifecycle.

{
  "id": "job_parse_example",
  "status": "completed",
  "result": {
    "pages": [
      {
        "number": 1,
        "blocks": [
          {
            "type": "heading",
            "text": "Quarterly report"
          },
          {
            "type": "paragraph",
            "text": "Revenue increased by 12%."
          },
          {
            "type": "table",
            "columns": [
              "Quarter",
              "Revenue"
            ],
            "rows": [
              [
                "Q1",
                42000
              ],
              [
                "Q2",
                47040
              ]
            ]
          }
        ]
      }
    ],
    "warnings": []
  }
}

Fields

file_ref

The uploaded document to parse.

result.pages

The parsed pages, identified by one-based page numbers.

pages[].blocks

Typed content blocks in document order.

result.warnings

Parsing issues or content that requires review.

Example workflow

1. Start with a quarterly report PDF.
2. Parse the document’s text, tables, and structure.
3. Use that representation in your application’s report analysis workflow.

Parse or Extract?

Choose Parse when you need the full document representation. Choose Extract when you know which data you need, for example, vendor names and invoice totals across a set of files. Use Index when the work spans a whole archive rather than one document, or Convert to produce an editable document instead.