Connect the Seller API & MCP

1. Create a Seller API key

Sign in with an active Seller pass. Open the API keys section under Batches and create a key. The full key is shown once. Store it securely in the HARUDOWN_API_KEY environment variable, away from browser code and public repositories. Replace the share link, YOUR_BATCH_ID and YOUR_RESULT_ID below with your own values. If a key is exposed, revoke it from the same section and create a new one.

2. Submit a batch

Send a links array and requestId to POST /api/batches. Seller supports 1–500 authorized Xiaohongshu or Douyin share links per batch. Use 8–120 letters, numbers, underscores or hyphens for requestId. The response is HTTP 202 with a batch id, not an immediate file download. Retry the same operation with the same requestId and links array; use a new requestId for a new operation.

curl 'https://harudown.com/api/batches' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "links": ["PASTE_YOUR_PUBLIC_SHARE_LINK"],
    "requestId": "my-batch-20261105-001"
  }'

3. Check progress and export CSV

GET /api/batches lists your latest 100 batches. GET /api/batches/{id} returns the batch status and items. queued means waiting, processing means running, and completed means processing ended. A completed batch can contain failed items; check each status, error and result_id. Poll every few seconds and stop once processing ends. GET /api/batches/{id}/export returns CSV with authenticated download links, rather than original media URLs.

curl 'https://harudown.com/api/batches/YOUR_BATCH_ID' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY"

curl 'https://harudown.com/api/batches/YOUR_BATCH_ID/export' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY" \
  --output results.csv

4. Retrieve the original media address

Send the successful item’s result_id to GET /api/download?id={result_id}. The HTTP 307 Location header contains the original media address. The example prints response headers. Validate the destination host, then fetch the file separately without the Authorization header. Never forward your Bearer key to the source server. For photo results, use image=0 for the first photo and increment the index for others. API and MCP results have no retention time limit; source files and address expiry remain controlled by the original server.

curl --get 'https://harudown.com/api/download' \
  --data-urlencode 'id=YOUR_RESULT_ID' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY" \
  --dump-header - --output /dev/null

5. Connect an MCP client

Configure /api/mcp in a client that supports remote HTTP POST and Bearer authentication. The endpoint returns JSON-RPC responses to POST requests; GET/SSE connections are not available. Call initialize, then tools/list, then tools/call. Available tools are create_batch(links, requestId), list_batches, get_batch(id), and retry_batch_payment(id). The last tool resumes batches held for account or legacy payment issues; it does not reanalyze failed individual links. Tool content contains a JSON string. Business errors return isError: true.

curl 'https://harudown.com/api/mcp' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'

curl 'https://harudown.com/api/mcp' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

curl 'https://harudown.com/api/mcp' \
  -H "Authorization: Bearer $HARUDOWN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_batch","arguments":{"id":"YOUR_BATCH_ID"}}}'

Resolve authentication or request errors

For 401, check for a missing, malformed or revoked key and an expired Seller pass. For INVALID_LINK, copy a fresh public share link. For INVALID_REQUEST_ID, check the request ID format. REQUEST_CONFLICT means the same requestId was reused with different links. Accepted jobs continue after a pass expires, but new API requests, API lookups and CSV exports require active Seller access.