API Reference

Convert documents programmatically. A Pro plan is required for server-side conversions.

Base URL

https://oneconvertly.com

Authentication

Authorization: Bearer <token>

Get your token from /account after signing in.

Quick start

Shell 
# 1. Convert a DOCX to PDF
curl -X POST https://oneconvertly.com/api/v1/convert \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@document.docx" \
  -F "toolId=docx-to-pdf"

# Response: {"jobId":"b2f3c4d5-...","status":"queued"}

# 2. Poll until complete (repeat every 2s)
curl https://oneconvertly.com/api/v1/job/b2f3c4d5-...

# Response when done: {"status":"completed","downloadUrl":"https://..."}

# 3. Download your file
curl -L "$DOWNLOAD_URL" -o output.pdf

Supported tool IDs

toolId Input Output
docx-to-pdf .docx, .doc .pdf
pdf-to-docx .pdf .docx
xlsx-to-pdf .xlsx, .xls .pdf
pptx-to-pdf .pptx, .ppt .pdf
html-to-pdf .html, .htm .pdf

Endpoints

POST /api/v1/convert Pro

Convert a document

Upload a file and convert it using server-side LibreOffice processing. Returns a job ID for polling.

Auth: Required
Rate limit: 10 requests / 15 min (anonymous) · 100 requests / day (Pro)
Content-Type: multipart/form-data

Request fields

Field Type Required Description
file File yes The file to convert. Max 50 MB.
toolId string yes Conversion type. See tool IDs below.
options JSON string no Tool-specific options object.

Response example

{
  "jobId": "b2f3c4d5-...",
  "status": "queued",
  "expiresAt": "2025-01-01T13:00:00.000Z"
}
GET /api/v1/job/:id

Poll job status

Check the status of a conversion job. Poll every 2 seconds until status is "completed" or "failed".

Auth: Optional
Rate limit: Shared with /convert

Response example

// While processing:
{
  "id": "b2f3c4d5-...",
  "status": "processing",
  "createdAt": "2025-01-01T12:00:00.000Z"
}

// On completion:
{
  "id": "b2f3c4d5-...",
  "status": "completed",
  "downloadUrl": "https://...(signed URL, valid 30 min)",
  "processingMs": 1240,
  "createdAt": "2025-01-01T12:00:00.000Z",
  "completedAt": "2025-01-01T12:00:01.240Z"
}

// On failure:
{
  "id": "b2f3c4d5-...",
  "status": "failed",
  "error": "Unsupported file format"
}
POST /api/v1/auth/register

Register

Create a new account. Returns a JWT token.

Auth: Optional
Rate limit: 5 requests / 15 min per IP
Content-Type: application/json

Request fields

Field Type Required Description
email string yes Valid email address.
password string yes Minimum 8 characters.

Response example

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": "a1b2c3d4-...",
    "email": "user@example.com",
    "plan": "free"
  }
}
POST /api/v1/auth/login

Login

Authenticate and get a JWT token. Tokens expire after 30 days.

Auth: Optional
Rate limit: 10 requests / 15 min per IP
Content-Type: application/json

Request fields

Field Type Required Description
email string yes
password string yes

Response example

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "user": { "id": "...", "email": "...", "plan": "pro" }
}
GET /api/v1/auth/me

Current user

Returns the authenticated user profile and usage stats.

Auth: Required
Rate limit: Standard

Response example

{
  "id": "a1b2c3d4-...",
  "email": "user@example.com",
  "plan": "pro",
  "createdAt": "2025-01-01T00:00:00.000Z",
  "jobsThisMonth": 42
}

Error codes

Status Meaning
400 Bad request — missing or invalid fields
401 Unauthorized — missing or invalid Bearer token
409 Conflict — e.g. email already registered
413 Payload too large — file exceeds 50 MB
415 Unsupported media type — invalid file format
429 Too many requests — rate limit exceeded
500 Internal server error — retry with exponential backoff

Need help?

Questions about the API? Open an issue on GitHub or email api@oneconvertly.com.