Connect with KovaPDF

Overview

• Connect with KovaPDF is standard OAuth: the person sees your app's name, its domain and what it may do, and chooses Allow or Cancel. You get an access token for their account.
• Files and jobs run the tools: upload a file, start a job, and download the result from a short-lived link. They work with that access token, or with an API key.
• The MCP server gives AI assistants the same tools, with the same connection.

Files and results are deleted within an hour. Every file gets the same virus scan and safety checks as a file uploaded on the website.

Connect with KovaPDF

The authorization code flow with PKCE (S256), nothing else: no client secrets, no implicit flow, no password flow. Your app finds every address in the metadata at https://api.kovapdf.com/.well-known/oauth-authorization-server.

1. Identify your app. Best: use an https address that serves a Client ID Metadata Document as your client_id (it names your app and its redirect addresses, and shows your domain as verified). Or register with POST /oauth/register and keep the client_id you get.
2. Send the person to /oauth/authorize with response_type=code, your client_id, a redirect_uri you registered (it must match exactly), a code_challenge with code_challenge_method=S256, a state, and the scope you need.
3. They sign in if needed, see the request and choose Allow. They come back to your redirect_uri with a code, your state and iss.
4. Within two minutes, exchange the code at POST /oauth/token with your code_verifier. A code works once.

curl https://api.kovapdf.com/oauth/token \
  -d grant_type=authorization_code \
  -d client_id="$CLIENT_ID" \
  -d code="$CODE" \
  -d redirect_uri="https://yourapp.example/callback" \
  -d code_verifier="$VERIFIER"

The answer has an access_token (one hour) and a refresh_token. A refresh token works once: each refresh returns a new pair, so always keep the newest. Using an old refresh token again ends the connection, as it may have been copied. Revoke a token at POST /oauth/revoke. The person can remove your app at any time in Dashboard, Connected apps; its tokens stop at once.

What an app may do

Ask only for what you need. The consent page lists each one in plain words.

• tools:run: Compress, merge, split, organize, convert, read text from scans, redact and convert Bangla or Hindi text, within your account's usual limits.
• verify: Check the digital signatures in a PDF and read the report.
• sign:read: List your signature requests and see who has signed.
• sign:write: Prepare signature requests and send them after you confirm.

Files

Upload a file once and use its id in jobs. It is kept for one hour.

curl https://api.kovapdf.com/api/v1/files \
  -H "Authorization: Bearer $TOKEN" \
  -F file=@report.pdf

Small files can also be sent as JSON { "name": "a.pdf", "contentBase64": "..." }, and a file on the web as { "url": "https://..." }. An address is downloaded once, over https, from public addresses only.

Jobs

curl https://api.kovapdf.com/api/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tool": "compress", "inputs": ["FILE_ID"], "options": { "level": "strong" } }'

The answer is the job, queued. Ask for GET /jobs/ID until its state is done or failed; while it runs, the Retry-After header says how many seconds to wait. When it is done, result.files has download links that work for 15 minutes (ask again for fresh ones) and result.report has what the tool found.

Tools

The list, with what each tool needs, is also at GET /tools. The OpenAPI file describes every call.

MCP server

AI assistants that support remote MCP servers can add KovaPDF at https://api.kovapdf.com/mcp (Streamable HTTP). The assistant connects with Connect with KovaPDF, then offers the tools above with the person's own limits. Files can be given as a file id, an https link, small base64, or a file attached in the chat. Results come back as download links.

Add it in one click: Add to Cursor (or the web link), Add to VS Code (or the web link). Other assistants take the address https://mcp.kovapdf.com.

Every result says it was done with KovaPDF. Text read from a file comes back marked as file content, so an assistant treats it as data and never as instructions.

Signature requests are always two steps: the assistant prepares a draft, shows it to the person, and sends it only after they confirm.

Without an account, an assistant can do a few small jobs a day with the lighter tools (check signatures, compress, merge, and Bangla or Hindi text). Every such answer says that a free account can be connected for more.

Errors and limits

Every error is JSON { error, code }. The codes to act on:

• limit_reached (429): the account's allowance is used up for now, the same as on the website. Retry-After says when, and nextFreeAt when known.
• too_many_jobs (429): this account already has the most jobs waiting. Wait for one to finish.
• busy (503): KovaPDF is busy. Try again after Retry-After seconds. Integrations have their own lane, so they never slow down people on the website.
• too_big (413): the file is too big for this way of sending it.
• insufficient_scope (403): the token or key may not do this. invalid_token (401): connect again.
• file_expired, link_expired (410): upload the file again, or ask for the job again for a fresh link.

See also every error code and the API limits.