Authentication

Send either Authorization: Bearer YOUR_TOKEN or X-API-Key: YOUR_TOKEN. Create tokens under Dashboard → API Tokens and enable tools:execute. Alternatively, exchange email and password for a token: POST https://toolversa.com/api/auth/token (JSON body: email, password, optional device_name, abilities[], expires_at).

Required request headers

Accept: application/json
Content-Type: multipart/form-data
User-Agent: your-app-name/1.0
Authorization: Bearer YOUR_TOKEN
# or:
X-API-Key: YOUR_TOKEN

Optional hardening: request signing can be enabled by ops via API_SIGNATURE_ENABLED=true.

Synchronous execution

POST https://toolversa.com/api/tools/pdf-security
Accept: application/json
Authorization: Bearer YOUR_TOKEN
Content-Type: multipart/form-data

Parameters

Operation Payload Guide (PDF Tools)

Most PDF operations use multipart/form-data with one required operation field.

operation=pdf-to-jpg
pdf=@input.pdf

operation=pdf-translate
pdf=@input.pdf
target_language=Spanish

operation=watermark-pdf
pdf=@input.pdf
watermark_text=CONFIDENTIAL
watermark_position=diagonal
watermark_opacity=30

File uploads

Use multipart/form-data. For each file field, send the part as a file (same field names as in the form). For multiple files, repeat the field or use name[] as in the HTML form.

curl -X POST "https://toolversa.com/api/tools/pdf-security" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -F "operation=example_value" \
  -F "pdf=@/path/to/file" \
  -F "password=example_value"

Response

JSON envelope:

{
  "success": true,
  "data": {
    "tool": { "id": 166, "name": "...", "slug": "pdf-security" },
    "output": { /* tool-specific result */ },
    "duration_ms": 0,
    "status": "success",
    "response_token": "short_lived_integrity_token"
  },
  "message": "Tool executed successfully."
}

Error status map: 401 unauthorized/signature, 403 plan/access/captcha, 409 replay detected, 413 payload too large, 415 content-type rejected, 422 validation/execution, 429 rate/abuse limits.