v3 Current

ConvertPro API Documentation

Welcome to the ConvertPro API. This page covers authentication, endpoints, conversion routes, user management, permissions, points, dashboard, and admin APIs.

Backend Base URL

http://127.0.0.1:8000

Versioning

v3 is the current platform API for conversions, points, permissions, dashboard, and admin workflows. v2 handles auth, users, and legacy authenticated converters. v1 remains available for older conversion integrations.

Authentication

The ConvertPro API uses bearer tokens. Login on /api/v2/auth/login, refresh on /api/v2/auth/refresh, and pass the access token in the Authorization header for protected endpoints.

POST /api/v2/auth/login

curl -X POST http://127.0.0.1:8000/api/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123"}'

Success Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Auth Endpoints

POST/api/v2/auth/loginIssue access and refresh tokens

Request body: email, password.

POST/api/v2/auth/refreshRefresh an access token

Request body: refresh_token.

GET/api/v2/auth/meGet current authenticated user

Requires Authorization: Bearer <token>.

User Roles

shield_person

Super User

Full access to conversions, billing, admin checks, user role changes, and permission management.

manage_accounts

Admin

Manage general and demo users, top up points, and inspect user activity and permissions.

person

General

Can perform allowed conversions, read dashboard data, check points, and view own history.

visibility

Demo

Read-only mode for protected write actions. Demo users cannot create conversion jobs.

Conversion Endpoints

POST/api/v3/conversions/pdf-to-wordConvert PDF to DOCX

fileREQUIRED

Upload PDF file as multipart form data.

UploadFile

Idempotency-Key

Optional request header recommended for safe retries on v3 conversion POST calls.

header

points_charged

Successful conversions charge the flat per-request points rule for non-super users.

integer

Available v3 Conversion Routes

POST /api/v3/conversions/pdf-to-wordPOST /api/v3/conversions/pdf-to-excelPOST /api/v3/conversions/docx-to-pdfPOST /api/v3/conversions/excel-to-pdfPOST /api/v3/conversions/image-to-pdfPOST /api/v3/conversions/remove-pages-from-pdfPOST /api/v3/conversions/remove-background

User, Points, Permissions And Admin Endpoints

POST/api/v2/usersCreate user

Admin or super user only.

GET/api/v2/usersList users

Returns an array of UserOut.

PATCH/api/v2/users/<user_id>/roleUpdate user role

Super user only.

GET/api/v3/points/balanceGet points balance

Other points routes: /api/v3/points/ledger, /topup, /rules, /my-point.

Error Handling

warning

401 Unauthorized

Invalid or missing bearer token.

block

403 Forbidden

Conversion not permitted, role blocked, or insufficient role privileges.

hourglass_top

402 Payment Required

Raised when the user has insufficient points for a conversion request.

rule

422 Validation Error

Input payload, file upload, or query parameter validation failed.

Rate Limits

Scope	Current Docs Note	Behavior
v3 Conversions	Point-based charging	Each successful request uses the flat cost returned by /api/v3/points/rules.
Retry Safety	Idempotency supported	Use Idempotency-Key on v3 POST conversions to prevent duplicate charges.
Admin Reads	Role-gated	Admin and super user access depends on backend role checks.