Developer guide

Paginta

A Belumind product · PDF to Word · EN / VI / FR

Turns long reports, multi-column pages and financial statements into a Word file where every table is a real table you can click into and edit. Works best in English, Vietnamese and French, accents intact. It never rewrites or summarises — what was on the page is what lands in the document — and every conversion comes with a check report: how many pages and tables, which garbled text was fixed, and how many table cells match the original.

Address for your software (API)

https://api.belumind.com/paginta

Address for AI assistants (MCP)

https://mcp.belumind.com/paginta/mcp

Table cells matched: 1,753 / 1,753
Tables kept intact: 44 / 45
Normal page: ~1–5 s / page
Scanned page: ~5 s / page

Access keys

Every request sends two things: an API key for this product, made in the dashboard under API keys, and the access token of the signed-in user who owns it. The token lasts 15 minutes, so refresh it and send the new one. A key made for another product gets a 403 error. That means you can give an AI assistant a key that reaches exactly one tool and nothing else.

AI assistants send the same two headers when they connect to the address above.

documents:convert

How the keys are sent

X-API-Key: bm_live_7f3c…
Authorization: Bearer eyJhbGciOi…
Content-Type: application/json

POST/v1/documentsdocuments:convert

Send a PDF to convert

Checks the file straight away — size, number of pages, your plan and monthly allowance — so a problem (error 413, 402 or 429) is reported at once instead of after the conversion. Then it starts the job and immediately gives you its id. Check `GET /v1/documents/{doc_id}` for the result. If you would rather get the Word file in one step, `POST /convert` takes the same file and sends back the .docx itself; its `X-Font-Garbled` and `X-Repaired-Cells` headers report quality. Through MCP, a file on the user's machine is first uploaded to `https://mcp.belumind.com/paginta/uploads`, and the returned `upload_id` is passed to `convert_pdf`; the `service_status` tool says whether the service is up and how busy it is.

AI assistant toolconvert_pdf

What to send

filefilerequired: The PDF file. Empty or damaged files give error 400; a scanned PDF needs text recognition, which is only on the Pro plan (402); files over your plan's size or page limit give 413.

What you get back

202 AcceptedReceived — it is in line to be processed.
400 Bad RequestSomething in what you sent was wrong or missing. The answer says which part.
401 UnauthorizedThe API key or access token is missing, mistyped or no longer valid. Access tokens expire after 15 minutes — refresh it and send the new one.
403 ForbiddenThe key works, but it was made for another product.
402 Payment RequiredThe account is out of credits. Buy more in the dashboard, or turn on automatic top-up.
429 Too Many RequestsToo many requests in a short time, or the key has reached the monthly limit set on it. Wait the number of seconds given in `Retry-After`, then try again.
500 Internal Server ErrorSomething went wrong on our side. It is safe to send the same request again.
503 Service UnavailableThe queue is full, or the dashboard that checks keys could not be reached. Try again a little later.

What you send

curl -X POST https://api.belumind.com/paginta/v1/documents \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN" \
  -F "file=@annual-report-2024.pdf"

What you get back

application/json202 Accepted

{
  "job_id": "6s_4aek7-1792405943",
  "status": "queued"
}

Try it

Example mode

API keyAccess tokenWhat to send

POST https://api.belumind.com/paginta/v1/documents

The platform is in early access, so this box shows the example answer instead of contacting the live service. Ask us for a key and the same box will send real requests.

GET/v1/documents/{doc_id}documents:convert

Check a conversion and its report

Shows whether a job is finished and, once it is, its check report: pages, tables, time taken, scanned pages, text fixed and — when measured against the original — how many table cells match exactly, how many were lost (this should be 0) and how many tables kept their shape. When `downloadable` is true, `GET /v1/documents/{doc_id}/download` gives a short-lived link to download the .docx.

AI assistant toolget_document

Settings in the address

doc_idstring · pathrequired: The id you got when you sent the PDF, or from the list (`GET /v1/documents`).

What you get back

200 OKIt worked. You get back what the example shows.
400 Bad RequestSomething in what you sent was wrong or missing. The answer says which part.
401 UnauthorizedThe API key or access token is missing, mistyped or no longer valid. Access tokens expire after 15 minutes — refresh it and send the new one.
403 ForbiddenThe key works, but it was made for another product.
402 Payment RequiredThe account is out of credits. Buy more in the dashboard, or turn on automatic top-up.
429 Too Many RequestsToo many requests in a short time, or the key has reached the monthly limit set on it. Wait the number of seconds given in `Retry-After`, then try again.
500 Internal Server ErrorSomething went wrong on our side. It is safe to send the same request again.
503 Service UnavailableThe queue is full, or the dashboard that checks keys could not be reached. Try again a little later.

What you send

curl -X GET https://api.belumind.com/paginta/v1/documents/{doc_id} \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN"

What you get back

application/json200 OK

{
  "job_id": "6s_4aek7-1792405943",
  "status": "done",
  "name": "annual-report-2024.pdf",
  "pages": 93,
  "tables": 45,
  "bytes": 4182337,
  "ms": 88400,
  "error": null,
  "error_code": null,
  "downloadable": true,
  "verification": {
    "font_garbled": false,
    "repaired_cells": 12,
    "scanned": false,
    "cells_src": 1753,
    "cell_exact": 1753,
    "cell_lost": 0,
    "shape_ok": 44,
    "shape_total": 45,
    "text_recall": 1,
    "level": "per_cell",
    "detail": null
  }
}

Try it

Example mode

API keyAccess token

doc_id

GET https://api.belumind.com/paginta/v1/documents/

The platform is in early access, so this box shows the example answer instead of contacting the live service. Ask us for a key and the same box will send real requests.

GET/v1/documentsdocuments:convert

See past conversions and plan limits

Your conversions, newest first, each with the same details as a single document — plus your plan and its limits: pages per file, documents per month, largest upload and whether scanned pages are supported. `limit` sets how many to show; the default is 200.

AI assistant toollist_documents

Settings in the address

limitinteger · queryoptional: How many conversions to show. Defaults to 200.

What you get back

200 OKIt worked. You get back what the example shows.
400 Bad RequestSomething in what you sent was wrong or missing. The answer says which part.
401 UnauthorizedThe API key or access token is missing, mistyped or no longer valid. Access tokens expire after 15 minutes — refresh it and send the new one.
403 ForbiddenThe key works, but it was made for another product.
402 Payment RequiredThe account is out of credits. Buy more in the dashboard, or turn on automatic top-up.
429 Too Many RequestsToo many requests in a short time, or the key has reached the monthly limit set on it. Wait the number of seconds given in `Retry-After`, then try again.
500 Internal Server ErrorSomething went wrong on our side. It is safe to send the same request again.
503 Service UnavailableThe queue is full, or the dashboard that checks keys could not be reached. Try again a little later.

What you send

curl -X GET https://api.belumind.com/paginta/v1/documents \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN"

What you get back

application/json200 OK

{
  "documents": [
    {
      "doc_id": "6s_4aek7-1792405943",
      "name": "annual-report-2024.pdf",
      "status": "done",
      "pages": 93,
      "tables": 45,
      "downloadable": true
    }
  ],
  "count": 1,
  "plan": "pro",
  "limits": {
    "pages_per_file": 20,
    "documents_per_month": 1000000,
    "max_upload_mb": 25,
    "ocr": true
  }
}

Try it

Example mode

API keyAccess token

GET https://api.belumind.com/paginta/v1/documents

The platform is in early access, so this box shows the example answer instead of contacting the live service. Ask us for a key and the same box will send real requests.

Use with an AI assistant

Connected to an AI assistant, Paginta can take a PDF a user shares in the chat and give back an editable Word file — then use the check report to say which tables, if any, deserve a second look before the document is sent on. Paginta cannot open files on the user's computer, so a file is uploaded first; a PDF that is already online is shared by its link.

You ask

“Turn this audited bank report into Word so I can edit the tables.”

The assistant

01Uploads the file, then asks Paginta to convert it
02Gives the user a short-lived download link for the Word file
03Reads the check report and points out any table that did not come through exactly

Settings to paste into your AI assistant

{
  "mcpServers": {
    "paginta": {
      "url": "https://mcp.belumind.com/paginta/mcp",
      "headers": {
        "X-API-Key": "bm_live_7f3c…",
        "Authorization": "Bearer eyJhbGciOi…"
      }
    }
  }
}

When something goes wrong

When a request fails, you get a standard error number and a short code that your software can act on, next to a plain message for people to read. Each request can carry an Idempotency-Key, so sending it again after a problem on our side is safe — it won't be done twice.

What an error looks like4xx / 5xx

{
  "error": {
    "code": "invalid_parameter",
    "message": "`url` must be a reachable http(s) URL.",
    "param": "url",
    "request_id": "req_4d91c0b7"
  }
}

Ready to use it for real?

While the platform is in early access, the "Try it" box shows example answers. Tell us what you are building and we will get you a key.