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

# SoMark API

> Use the shortest path to complete auth, sync parsing, and async parsing with the SoMark API.

Best for teams that want direct HTTP control over request parameters, backend flow, and result handling. If you are still comparing integration paths, start with the [get started overview](/en/documentation/get-started-overview); if you need auth, limits, and endpoint coverage, also check the [API overview](/en/api-reference/index).

<Steps>
  <Step title="Get your API key and run the preflight check">
    Visit [somark.tech/workbench/apikey](https://somark.tech/workbench/apikey) to get an API key in the `sk-***` format.

    Before calling the API, check three things:

    * `api_key` is included
    * the file is not empty and is supported
    * `output_formats` only uses `markdown`, `json`, or `zip`

    <Note>
      See [Free tier rules](/en/documentation/free-tier-rules) for quota details.
    </Note>
  </Step>

  <Step title="Complete one sync parsing request first">
    Start with `POST /parse/sync` for small files. The result comes back in the same response.

    <CodeGroup>
      ```bash cURL theme={null}
      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"
      ```

      ```python Python theme={null}
      import requests

      with open("document.pdf", "rb") as file_obj:
          response = requests.post(
              "https://somark.tech/api/v1/parse/sync",
              files={"file": file_obj},
              data=[
                  ("output_formats", "markdown"),
                  ("output_formats", "json"),
                  ("api_key", "sk-your-api-key"),
              ],
              timeout=120,
          )

      payload = response.json()
      print(payload["data"]["result"]["outputs"]["markdown"])
      ```
    </CodeGroup>
  </Step>

  <Step title="Use async submit and check for large files">
    Large files, batch jobs, and background workflows should use async mode: call `POST /parse/async` first, then poll `POST /parse/async_check` with the returned `task_id`.

    ```bash theme={null}
    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"

    curl -X POST https://somark.tech/api/v1/parse/async_check \
      -F "task_id=your-task-id" \
      -F "api_key=sk-your-api-key"
    ```

    <Tip>
      Keep polling intervals around 3 to 5 seconds.
    </Tip>
  </Step>

  <Step title="Open the detailed endpoint docs when needed">
    * [Sync parsing endpoint](/en/api-reference/endpoint/sync)
    * [Async submit endpoint](/en/api-reference/endpoint/async-submit)
    * [Async check endpoint](/en/api-reference/endpoint/async-check)
    * [Error reference](/en/api-reference/errors)
  </Step>
</Steps>