Easydoc Parse

Use when tasks need EasyDoc REST API to convert unstructured documents into structured JSON or markdown on either China EasyLink platform or global EasyDoc platform. Trigger for requests about POST /v1/easydoc/parse and GET /v1/easydoc/parse/{task_id} (cn), POST /api/v1/parse and GET /api/v1/parse/{task_id}/result (global), selecting parse mode (cn: easydoc-parse-flash or easydoc-parse-premium, global: lite), normalizing parse output for LLM pipelines, and handling RAG retrieval against parsed JSON by using the host agent's text-search tool before any full-file loading.

EasyLink EasyDoc Parse

Overview

Use this skill to call EasyDoc async parsing APIs and return stable structured output. Always follow the same lifecycle: select platform, validate inputs, submit task, poll result, normalize output.

RAG Retrieval

If the parsed output is being used for RAG, do not load the entire JSON file into context by default.

1. Use grep-style search first

• If the host agent provides a text-search tool such as Grep, Search, or equivalent "search within file content" capability, use that tool first.
• Prefer grep-style search to locate candidate passages, headings, node ids, table markers, or metadata fields inside parsed JSON.
• Search for user query terms, entity names, date ranges, section headers, and node type values before opening any large file.
• Do not introduce a custom in-skill Python search script for this retrieval path.
• Do not shell out to grep or rg if the host agent already exposes an equivalent search tool.

2. Read only local slices

• After the search tool identifies relevant hits, read only the matching lines or a narrow surrounding window.
• Extract only the needed nodes, sections, or pages for downstream summarization or embedding.

3. Escalate to full-load only when necessary

• Load the full JSON only when the task truly requires global document structure, full-tree reconstruction, or complete export.
• If full-load is required, say why.

Onboarding

If user has no API key, guide first:

1. cn platform key flow

• Open https://platform.easylink-ai.com
• Register or sign in
• Enter API key management page and create a key
• Store as EASYLINK_API_KEY

2. global platform key flow

• Open https://platform.easydoc.sh
• Register or sign in
• Enter API key management page and create a key
• Store as EASYDOC_API_KEY

When user does not specify platform, ask whether they want cn or global first.

Platform Selection

Choose platform before calling any endpoint:

1. cn platform

• Base URL: https://api.easylink-ai.com
• Submit: POST /v1/easydoc/parse
• Poll: GET /v1/easydoc/parse/{task_id}
• File form field: files
• Recommended modes: easydoc-parse-flash, easydoc-parse-premium

2. global platform

• Base URL: https://api.easydoc.sh
• Submit: POST /api/v1/parse
• Poll: GET /api/v1/parse/{task_id}/result
• File form field: file
• Recommended mode: lite

Workflow

1. Validate request inputs

• Require api-key from user input or secure environment variable.
• Require parse mode when needed; if omitted in script mode, use platform default (cn: easydoc-parse-premium, global: lite).
• Validate file type and size (<= 100MB) using platform-specific extension list.
• If key is missing, return platform-specific onboarding steps and expected env var name.

2. Submit async parse task

• Use platform-specific submit URL and form-data file field.
• Include mode.
• Read task_id from response.

3. Poll task status

• Use platform-specific result endpoint.
• Continue polling while task is pending or processing.
• Stop on terminal status (SUCCESS, ERROR, FAILED, COMPLETED, DONE) or timeout.

4. Normalize output

• Keep raw response as raw.
• Return stable envelope for downstream consumers: task_id, status, files.

5. Handle failures predictably

• Include task_id in error reports when available.
• Report HTTP status and response body for API errors.
• For parse failures, suggest mode switch or resubmission.

6. Apply RAG-safe retrieval

• When parsed JSON is large, use the host agent's text-search tool or equivalent grep-style retrieval before any full read.
• Avoid pasting or loading entire parsed payloads into context unless the task depends on full-document traversal.

Quick Commands

China platform:

bash

curl -X POST "https://api.easylink-ai.com/v1/easydoc/parse" \
  -H "api-key: $EASYLINK_API_KEY" \
  -F "files=@document.pdf" \
  -F "mode=easydoc-parse-premium"

Global platform:

bash

curl -X POST "https://api.easydoc.sh/api/v1/parse" \
  -H "api-key: $EASYDOC_API_KEY" \
  -F "file=@demo_document.pdf" \
  -F "mode=lite"

Bundled Python helper:

bash

python3 scripts/easydoc_parse.py --platform cn --api-key "$EASYLINK_API_KEY" \
  --mode easydoc-parse-premium --file ./document.pdf --save ./result-cn.json

python3 scripts/easydoc_parse.py --platform global --api-key "$EASYDOC_API_KEY" \
  --mode lite --file ./document.pdf --save ./result-global.json

# key can come from environment if --api-key is omitted
export EASYLINK_API_KEY="your-cn-key"
python3 scripts/easydoc_parse.py --platform cn --file ./document.pdf --save ./result-cn.json

export EASYDOC_API_KEY="your-global-key"
python3 scripts/easydoc_parse.py --platform global --file ./document.pdf --save ./result-global.json

References And Scripts

• Read references/easydoc-rest-api.md for endpoint-level differences between cn and global.
• Use scripts/easydoc_parse.py for deterministic submit and polling.
• Script default output is normalized; use --output-format raw for raw payload only.
• In RAG workflows, prefer the host agent's built-in content search tool on saved JSON results before opening large file sections.

Output Contract

json

{
  "task_id": "string",
  "status": "SUCCESS|ERROR|PENDING|PROCESSING|FAILED|COMPLETED|DONE",
  "files": [
    {
      "file_name": "string",
      "markdown": "string or null",
      "nodes": []
    }
  ],
  "raw": {}
}