Sample Guide for Programmatically Using ConvertX API

[codexvn]

I wanted to share some guidance on programmatically integrating with ConvertX, especially for developers who need to automate file format conversions. ConvertX doesn’t provide an official public API, but its web interface can be leveraged via HTTP requests. Below is a summary based on recent testing.

---

Background

ConvertX is primarily a web-based file conversion tool. To use it programmatically, you need to handle authentication cookies, file uploads, conversion selection, and result retrieval.

The main challenge is that the web interface uses JWT authentication and task-specific cookies (auth and jobId) to track conversion jobs. You can either:

1. Use the login endpoint to get the cookies, or
2. Use the unauthenticated mode (if ALLOW_UNAUTHENTICATED is enabled in your deployment) to directly get a JWT and job ID.

---

1️⃣ Login / Get Cookies

Authenticated login:

curl --location --request POST 'http://127.0.0.1:4523/login' \
--data-urlencode 'email=YOUR_EMAIL' \
--data-urlencode 'password=YOUR_PASSWORD'

Response includes set-cookie headers:

auth=...; Max-Age=86400; HttpOnly; SameSite=Strict
jobId=1; Max-Age=86400; HttpOnly; SameSite=Strict

Unauthenticated mode:

curl --location --request GET 'http://127.0.0.1:4523/'

This will return a new JWT and job ID in cookies.

---

2️⃣ Upload File

curl --location --request POST 'http://127.0.0.1:4523/upload' \
--form 'file=@"PATH_TO_YOUR_FILE"'

---

3️⃣ Get Available Conversion Strategies

curl --location --request POST 'http://127.0.0.1:4523/conversions' \
--header 'Content-Type: application/json' \
--data-raw '{
    "fileType": "docx"
}'

• Output: HTML page listing available conversion strategies.
• You can extract the strategies using regex:

(?<=data-value=")[^"]+  OR  (?<=option value=")[^"]+

• Example parsed list (format: target_format,tool):

azw3,calibre
docx,calibre
epub,calibre
fb2,calibre
html,calibre
htmlz,calibre

---

4️⃣ Start Conversion

curl --location --request POST 'http://127.0.0.1:4523/convert' \
--data-urlencode 'file_names=["YOUR_FILE_NAME"]' \
--data-urlencode 'convert_to=pdf,calibre'

---

5️⃣ Track Progress & Get Result

• Poll progress endpoint using task ID from cookie:

curl --location --request POST 'http://127.0.0.1:4523/progress/{jobId}'

• Extract final download link with regex:

(?<=href=")/download/[^"]+(?="\s+download=)

---

6️⃣ Download Converted File

curl --location --request GET 'http://127.0.0.1:4523/{download_path}' \
--cookie 'auth=YOUR_AUTH_COOKIE; jobId=YOUR_JOBID'

---

7️⃣ Java OkHttp Example: Cookie Management

public static class InMemoryCookieJar implements CookieJar {
    private final Map<String, List<Cookie>> cookieStore = new HashMap<>();

    @Override
    public void saveFromResponse(HttpUrl url, List<Cookie> cookies) {
        cookieStore.put(url.host(), cookies);
    }

    @Override
    public List<Cookie> loadForRequest(HttpUrl url) {
        return cookieStore.getOrDefault(url.host(), new ArrayList<>());
    }
}

OkHttpClient client = new OkHttpClient.Builder()
        .cookieJar(new InMemoryCookieJar())
        .build();

• Use this client to automatically handle auth and jobId cookies when making requests.

---

This should help developers quickly automate ConvertX workflows. If anyone has improvements or additional tips, please share!