Skip to main content

​
What you’ll achieve

  • Get an API key and authenticate requests
  • Send one sync parsing request and get the md result
  • Understand the async task submission and polling workflow
  • Learn quick troubleshooting methods for common errors
1

Get your API key

Get an API key from the SoMark workbench in the format sk-***.
No purchase is required. You can start using the API as soon as you get an API key. See Free tier rules for free usage details. It is recommended to validate request parameters with a test document before integrating into production.
2

Choose the right mode

ModeEndpointBest for
Sync parsingPOST /parse/syncSmall files and immediate results
Async submitPOST /parse/asyncLarge files and batch jobs
Async checkPOST /parse/async_checkPoll status and fetch completed results
3

Call sync parsing (fastest path)

The following examples request both md and json outputs.
curl -X POST https://somark.tech/api/v1/parse/sync \
  -F "file=@document.pdf" \
  -F "output_formats=markdown" \
  -F "output_formats=json" \
  -F "api_key=sk-your-api-key"
4

Read the response

{
  "code": 0,
  "message": "Task success",
  "data": {
    "task_id": "a1b2c3d4e5f6",
    "error": null,
    "metadata": {
      "page_num": 10,
      "file_type": ".pdf"
    },
    "result": {
      "file_name": "document.pdf",
      "imgs": ["https://example.com/img_0.jpg"],
      "outputs": {
        "markdown": "# Chapter 1 Introduction\n\nThis document describes...",
        "json": {
          "pages": [
            {
              "page_num": 0,
              "blocks": [
                {
                  "idx": 0,
                  "type": "title",
                  "bbox": [72, 50, 540, 80],
                  "content": "Chapter 1 Introduction",
                  "format": "text",
                  "captions": [],
                  "img_url": "",
                  "title_level": 1
                },
                {
                  "idx": 1,
                  "type": "text",
                  "bbox": [72, 100, 540, 200],
                  "content": "This document describes...",
                  "format": "text",
                  "captions": [],
                  "img_url": ""
                }
              ],
              "page_size": { "h": 1684, "w": 1190 },
              "merge_content_from_pre_page": false
            }
          ]
        }
      }
    }
  }
}
If code is not 0, first check whether api_key is valid, whether output_formats uses markdown/json/somarkdown/docx, and whether the uploaded file is empty.
5

Async flow (for large files)

  1. Call POST /parse/async to submit the file and get task_id.
  2. Call POST /parse/async_check every 3~5 seconds to query the task status.
  3. Read data.result.outputs when the status becomes success.
curl -X POST https://somark.tech/api/v1/parse/async \
  -F "file=@large.pdf" \
  -F "output_formats=markdown" \
  -F "api_key=sk-your-api-key"

​
Next

Sync parsing endpoint

View complete request parameters, defaults, and response fields.

Async parsing endpoint

Learn task submission, status polling, and failure retry strategies.