Section Nav

Introduction

Mobile Ready

Convater Pro API Documentation

This page now tracks the current backend structure, with grouped docs for v2 auth and users plus the active v3 platform routes for conversions, points, permissions, dashboards, admin tooling, and deployment.

Current Platformlibrary_booksOverview

Introduction

Convater Pro exposes versioned API groups for authentication, user management, conversions, points, permissions, dashboards, admin workflows, and deployment operations.

Key Notes

arrow_right_altUse v2 for authentication and user lifecycle routes.
arrow_right_altUse v3 for conversion workloads, points, permissions, dashboard views, admin summaries, and deploy automation.
arrow_right_altAll protected routes require a bearer token issued from the v2 auth flow.

verified

Current docs target the active server environment, not localhost-only development usage.

verified

Navigation on this page is section-linked on desktop and mobile.

verified

The docs structure now mirrors the backend router grouping.

Access ControllockOverview

Authentication

The platform uses bearer authentication. Log in with v2 auth routes, refresh access tokens when needed, and pass the access token in the Authorization header for protected endpoints.

Key Notes

arrow_right_altLogin: POST /api/v2/auth/login
arrow_right_altRefresh: POST /api/v2/auth/refresh
arrow_right_altProfile check: GET /api/v2/auth/me
arrow_right_altHeader format: Authorization: Bearer <access_token>

POST /api/v2/auth/login

curl -X POST https://convaterpro.innsightmap.com/api/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"password123"}'

verified

Refresh tokens are exchanged on the dedicated refresh route.

verified

Protected v2 and v3 routes both depend on the issued bearer token.

Routing ModellinkOverview

Base URL And Versioning

Requests should be built against the server environment and then routed into the correct version namespace.

Key Notes

arrow_right_altServer base URL: https://convaterpro.innsightmap.com
arrow_right_altv2 namespace: /api/v2 for auth, users, and legacy authenticated converter flows.
arrow_right_altv3 namespace: /api/v3 for conversions, points, permissions, dashboard, admin, and deploy.
arrow_right_altv1 remains for older conversion compatibility paths but is not the primary current integration surface.

verified

Present integrations as server-hosted, not 127.0.0.1.

verified

Version boundaries are explicit and stable in the router layer.

v2 Routermanage_accountsCore APIs

Auth And User APIs

The v2 router includes authentication, user management, and protected home/converter routes for existing integrations.

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

Accepts login credentials and returns the token pair used across v2 and v3 APIs.

POST/api/v2/auth/refreshMint a new access token

Accepts a refresh token payload and returns a fresh access token response.

GET/api/v2/auth/meInspect the current authenticated user

Returns profile, points, creator metadata, and active API visibility for the signed-in user.

POST/api/v2/usersCreate a user

Used by admin or super user roles to create managed users.

GET/api/v2/usersList users

Returns the current visible user set based on role access.

PATCH/api/v2/users/{user_id}/roleUpdate user role

Restricted role-management route for promoting or changing user access.

verified

v2 remains the entrypoint for authentication and identity lifecycle operations.

verified

The /auth/me response is richer than a minimal identity check and surfaces active API state.

v3 RoutertransformCore APIs

Conversion APIs

The v3 conversions router handles the primary document and image transformations plus download and history-style workflows.

Key Notes

arrow_right_altIdempotency-Key is recommended on v3 POST conversion requests.
arrow_right_altSuccessful jobs return conversion metadata, points charged, and a download URL.
arrow_right_altConversion permissions and role checks can block access before processing begins.

POST/api/v3/conversions/pdf-to-wordConvert PDF to Word document

Multipart upload flow for PDF to DOCX conversion.

POST/api/v3/conversions/pdf-to-excelConvert PDF to Excel spreadsheet

Processes tabular PDF data into spreadsheet output.

POST/api/v3/conversions/docx-to-pdfConvert Word to PDF

Used for DOCX to PDF rendering in the current v3 stack.

POST/api/v3/conversions/excel-to-pdfConvert Excel to PDF

Converts spreadsheet uploads to PDF output.

POST/api/v3/conversions/image-to-pdfConvert image to PDF

Builds PDF output from image uploads.

POST/api/v3/conversions/remove-backgroundRemove image background

Image cleanup flow exposed through the same v3 conversion family.

POST/api/v3/conversions/remove-pages-from-pdfRemove selected PDF pages

Accepts page-removal input and returns a refined PDF output.

GET/api/v3/conversions/{conversion_id}/downloadDownload converted output

Uses the conversion id returned from a successful job result.

v3 RoutertollCore APIs

Points APIs

Points routes cover balance inspection, ledger history, direct top-ups, and top-up request workflows for managed accounts.

GET/api/v3/points/balanceGet current balance

Returns the effective points balance for the authenticated user.

GET/api/v3/points/ledgerRead points ledger history

Paginated view of topups, spending, and refunds.

POST/api/v3/points/topupTop up a user balance

Restricted to admin and super user roles, with ownership checks for admin users.

POST/api/v3/points/topup-requestsCreate a top-up request

Allows a user or manager to request balance approval from an eligible admin.

GET/api/v3/points/topup-requests/mineList my top-up requests

Returns the current user request history with paging metadata.

verified

Points charging is the primary v3 usage model.

verified

Admin user management is scoped to the accounts they are allowed to manage.

v3 Routerverified_userCore APIs

Permissions APIs

Permissions routes expose allowed action metadata, current API visibility, and per-user permission editing for managed access.

Key Notes

arrow_right_altSuper users effectively see all actions as allowed.
arrow_right_altAdmin users cannot modify super user permissions and are scoped to lower-level targets.

GET/api/v3/permissions/actionsList allowed action definitions

Returns the canonical conversion actions used across permissions and dashboards.

GET/api/v3/permissions/my-apiGet the current user API catalog

Returns active APIs, permission state, points cost, and usage insights.

GET/api/v3/permissions/users/{user_id}/permissionsRead a user permission set

Loads the permission matrix for a target managed user.

PUT/api/v3/permissions/users/{user_id}/permissionsReplace a user permission set

Bulk-update route for managed conversion permissions.

PATCH/api/v3/permissions/users/{user_id}/permissions/{action}Patch one permission

Toggles a single action without replacing the entire permission set.

v3 RoutermonitoringCore APIs

Dashboard APIs

Dashboard routes assemble usage summaries, active APIs, performance snapshots, and recent history for the signed-in user.

Key Notes

arrow_right_altDashboard API data is composed from conversions, permission visibility, and points state.
arrow_right_altSuccess rate and last-used values are derived per action from recent conversion history.

GET/api/v3/dashboard/overviewLoad dashboard overview

Returns user-facing summary metrics, per-action performance data, and recent activity snapshots.

v3 Routeradmin_panel_settingsAdmin

Admin APIs

Admin routes provide system summaries, active-user analytics, top-up request handling, managed user inspection, and operational history.

GET/api/v3/admin/dashboard-summaryRead admin summary metrics

Returns system-wide quick stats, recent activity, and top-level operational signals.

GET/api/v3/admin/active-usersList active users

Surfaces user activity visibility for admin and super user workflows.

GET/api/v3/admin/points/topup-requestsReview point top-up requests

Admin tooling for pending, approved, or rejected request queues.

POST/api/v3/admin/points/topup-requests/{request_id}/approveApprove a top-up request

Approves queued point requests within the caller’s allowed management scope.

POST/api/v3/admin/points/topup-requests/{request_id}/rejectReject a top-up request

Rejects queued requests while preserving audit visibility.

verified

Admin routes are role-gated at the router entrypoint.

verified

Some admin behaviors are further restricted by ownership and requested-admin checks.

v3 Routerrocket_launchAdmin

Deploy API

Deploy routes allow super users to trigger backend or frontend deployment scripts and inspect deployment status information.

Key Notes

arrow_right_altDeploy access is restricted to super_user only.
arrow_right_altDeploy log and pid locations are server-side script configuration concerns.

POST/api/v3/live-project-push/backendTrigger backend deployment

Starts the configured backend deploy script and records process metadata.

POST/api/v3/live-project-push/frontendTrigger frontend deployment

Starts the configured frontend deploy script and captures log state.

GET/api/v3/live-project-push/statusRead deployment status

Returns pid, timestamps, and log tail information for current deploy activity.

Access ModelbadgeResources

Roles

Role behavior determines which APIs are visible, which users can be managed, and which actions are allowed across points, permissions, and admin flows.

verified

Super User: full access across conversion, admin, points, permission, and deploy operations.

verified

Admin: manages assigned users, permissions, and point operations within ownership scope.

verified

General User: can use permitted APIs, inspect dashboard data, and request point operations for self.

verified

Demo User: restricted from protected write flows and conversion creation.

Response PatternserrorResources

Error Handling

Common failures are driven by missing auth, permission denial, point exhaustion, validation issues, and backend processing errors.

Status	Typical Cause	Current Meaning
401 Unauthorized	Missing or invalid token	The bearer token was not supplied, expired, or could not be validated.
403 Forbidden	Role or permission block	The caller is authenticated but cannot access the route or action.
404 Not Found	Missing user, request, or deploy resource	Target entities are validated and missing resources return explicit not-found errors.
422 Validation Error	Bad payload or query shape	Input schema, paging values, or upload constraints failed validation.
500 Internal Server Error	Server-side processing or deploy issue	Unexpected backend failures, conversion engine problems, or deploy script problems.

Operational GuidancespeedResources

Rate Limits And Request Safety

The platform currently emphasizes points-based charging, role checks, and safe retry behavior more than a published public throttle matrix.

Scope	Current Note	Behavior
v3 conversions	Points-based cost	Successful requests consume the configured per-request points rule for eligible users.
Retry safety	Idempotency advised	Send Idempotency-Key on conversion POST calls to avoid duplicate processing or duplicate charging.
Admin and deploy	Role-gated access	Administrative reads and deploy operations are protected before execution.