# PaperOffice AI API

> AI-powered document automation: OCR, IDP, PDF, e-signatures, translation, voice, workflows. Comprehensive REST API with native MCP server support — organized by category below.

## Quick Start

- **Base URL:** `https://api.paperoffice.ai/latest`
- **Auth:** `Authorization: Bearer po_sk_xxx` (System Key) or `Bearer po_ut_xxx` (User Token)
- **Landing page:** https://paperoffice.ai/developer/llms (marketing + examples)
- **Postman Collection:** [https://api.paperoffice.ai/latest/docs/postman](https://api.paperoffice.ai/latest/docs/postman) (for Postman / Insomnia / Bruno apps)
- **MCP Server:** `https://mcp.paperoffice.ai/mcp` (Streamable HTTP, same Bearer Token)
- **Get a token:** https://paperoffice.ai

## Authentication

All endpoints (except a few VISITOR-mode ones like `/health`, `/ip2location/*`, `/currencyexchange/*`) require a Bearer Token in the `Authorization` header.

```http
Authorization: Bearer po_sk_EXAMPLE_TOKEN_REPLACE_WITH_YOUR_KEY
```

| Prefix | Type | Scope |
|--------|------|-------|
| `po_sk_` | System Key | Server-to-server, full access |
| `po_ut_` | User Token | User-scoped, tier-limited |

## Job Workflow (Sync vs Async)

Every job endpoint accepts a `priority` parameter:

| Priority | Mode | SLA | Use Case |
|----------|------|-----|----------|
| `>= 900` | **SYNC** | ~20s | Dev / testing — result returned inline |
| `500-899` | **ASYNC** | 1-30 min | Production — returns `job_id`, poll `/job/get/{job_id}` |
| `< 500` | **ASYNC** | 2h-72h | Batch / background |

**Async workflow:**
1. `POST /job/add/{pipeline}` → returns `{ "job_id": "abc123" }`
2. `GET /job/get/{job_id}` → poll every 5-10s until `status="completed"`
3. `GET /job/download/{download_token}` → download result

## Response Format

All responses are JSON. Success:

```json
{
  "status": "success",
  "data": { ... },
  "processing_time": "123.45ms"
}
```

Error:

```json
{
  "status": "error",
  "code": "AUTH_REQUIRED",
  "message": "Authentication required. Please provide a valid Bearer token."
}
```

## Standard Error Codes

| HTTP | Code | Meaning |
|------|------|---------|
| 400 | `INVALID_REQUEST` | Missing/invalid parameters |
| 400 | `INPUT_TOO_LARGE` | Input exceeds endpoint limit (e.g. 15k chars for /translate/text) |
| 401 | `AUTH_REQUIRED` / `INVALID_TOKEN` | No or invalid Bearer token |
| 402 | `INSUFFICIENT_CREDITS` | Not enough credits |
| 404 | `NOT_FOUND` | Endpoint or resource not found |
| 408 | — | Sync job > 45s proxy limit (poll with `job_id`) |
| 429 | `RATE_LIMIT_EXCEEDED` | Retry after `Retry-After` header |
| 500 | `INTERNAL_ERROR` | Retry with exponential backoff |
| 500 | `TRANSLATION_FAILED` | LLM pipeline failure (endpoint-specific, e.g. /translate/text) |

## Rate Limits

Per-token (authenticated) or per-IP (visitor). Minimum limits (all tiers): 5/sec, 30/min, 100/hr, 500/day. Paid tiers get higher limits. Check `RateLimit-*` and `X-RateLimit-*` response headers.

## API Endpoints (Full Reference)

---

## Account — Messaging

### Check Notification Delivery

`POST https://api.paperoffice.ai/latest/message_center/delivery_status`

Check the delivery status of a notification. Shows which channels were successful and which failed.

**Tool-ID:** `po_notifications_check_delivery` • **Cost:** Free • **MCP:** `po_notifications_check_delivery` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `notification_uuid` | string | Yes | UUID of the Notification |

### Send Notification

`POST https://api.paperoffice.ai/latest/message_center/send`

Send a notification to a user across all configured channels (In-App, Web Push, Email, Telegram, SMS, Voice). The NotificationDispatcher selects the optimal channels based on priority and user preferences.

**Tool-ID:** `po_notifications_send` • **Cost:** Free • **MCP:** `po_notifications_send` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `target_user_id` | string | Yes | recipient User-ID |
| `category` | string | No | (allowed: workflow, document, system, billing, security, ai, connector, agent) (default: "workflow") |
| `priority` | string | No | Notification priority. `critical` bypasses quiet-hours, `urgent` routes via fastest channel, lower levels respect user channel preferences. (allowed: low, normal, high, urgent, critical) (default: "normal") |
| `title` | string | Yes | Notification title |
| `message` | string | Yes | Notification message |
| `action_url` | string | No | Deep-Link URL |
| `action_label` | string | No | button text for the action link |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "channels_sent": {
        "in_app": false
    },
    "notification": {
        "id": "60",
        "uuid": "00000000-0000-0000-0000-000000000001"
    },
    "processing_time": "147.18ms",
    "status": "success"
}
```

### Update Notification Preferences

`POST https://api.paperoffice.ai/latest/message_center/preferences`

Updates a user's notification settings: enabled channels per category, quiet hours, and AI features.

**Tool-ID:** `po_notifications_update_preferences` • **Cost:** Free • **MCP:** `po_notifications_update_preferences` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `channels_enabled` | object | No | channels per category: {"workflow": ["in_app", "email"], .} |
| `quiet_hours_enabled` | boolean | No |  |
| `quiet_hours_start` | string | No | Start-time HH:MM |
| `quiet_hours_end` | string | No | End-time HH:MM |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "updated": true,
    "updated_at": "2026-04-16T10:00:00Z"
}
```

---

## Account — Pricing & Plans

### List pricing plans and tiers

`GET https://api.paperoffice.ai/latest/billing/pricing/tiers`

Lists all available PaperOffice pricing plans (tiers) with prices, credits, features and details. Ideal for price comparisons and recommendations.

**Tool-ID:** `po_billing_plans` • **Cost:** 10 credits • **MCP:** `po_billing_plans` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `group` | string | No | tier group filter: app_tier, api_tier, sla_tier (optional, Standard: all) (allowed: app_tier, api_tier, sla_tier) |

**Example Response:**

```json
{
    "processing_time": "5.38ms",
    "refill_options": [
        25,
        50,
        75,
        100
    ],
    "source": "mariadb_sot",
    "status": "success",
    "tiers": {
        "APP-T1": {
            "name": "Starter",
            "description": "Perfekt for beginners and small projects",
            "credits_monthly": 15000,
            "overage_factor": 6,
            "is_paid": true,
            "default_priority": 0,
            "identification_method": "bearertoken",
            "vpn_allowed": true,
            "price_yearly": 180,
            "price_billed_monthly": 20,
            "included_storage_pages": 10000,
            "stripe_product_id": "prod_U2spo5pdQjPU3l",
            "tab": "enduser",
            "tab_position": 1,
            "support": "helpdesk_l1l2",
            "sla": "best_effor",
            "resources": {
                "workspaces": {
                    "included": 2,
                    "allow_additional": false,
                    "cost_per_additional_credits": 0,
                    "included_type": "basic",
                    "available_types": [
                        "basic",
                        "premium",
                        "ultra"
                    ]
                },
                "user_accounts": {
                    "included": 2,
                    "allow_additional": false,
                    "cost_per_additional_credits": 0
                },
                "workers": {
                    "included": 1,
                    "allow_additional": false
                },
                "storage_mounts": {
                    "included": 1,
                    "allow_additional": false,
                    "cost_per_additional_credits": 0
                }
            },
            "features": {
                "all_ai_functions": true,
                "api_access": false,
                "webhooks": false,
                "custom_integrations": false,
                "trust_center": false,
                "sso_saml": false,
                "audit_logs": false
            },
            "rate_limits": {
                "requests_per_second": 5,
                "requests_per_minute": 60,
                "requests_per_hour": 300,
                "requests_per_day": 1000
            },
            "queue_limits": {
                "max_concurrent_jobs": 1,
                "max_queued_jobs": 3,
                "max_queued_credits": 50,
                "queue_timeout_minutes": 60
            },
            "crawler": {
                "storage_mounts": {
                    "included": 1,
                    "allow_additional": false
                },
                "storage_modes": {
                    "import": true,
                    "crawl": false,
                    "user_storage": false
                },
                "connector_types": {
                    "sftp": true
                },
                "rate_limits": {
                    "files_per_day": 100
                },
                "polling": {
                    "min_interval_seconds": 3600
                },
                "after_import": [
                    "keep"
                ],
                "file_pattern": false,
                "recursive": true,
                "primary_secondary_redundancy": false
            }
        },
        "APP-T2": {
            "name": "Plus",
            "description": "for freelancer and growing Teams",
            "credits_monthly": 50000,
            "overage_factor": 5,
            "is_paid": true,
            "default_priority": 50,
            "identification_method": "bearertoken",
            "vpn_allowed": true,
            "price_yearly": 600,
            "price_billed_monthly": 70,
            "included_storage_pages": 50000,
            "stripe_product_id": "prod_U2QG6XE634DcFp",
            "tab": "enduser",
            "tab_position": 2,
            "badge": "BELIEBTESTE WAHL",
            "support": "helpdesk_l1l2",
            "sla": "99%",
            "resources": {
                "workspaces": {
                    "included": 3,
                    "allow_additional": true,
                    "base_cost_eur": 5,
                    "cost_eur_with_discount": 5,
                    "included_type": "basic",
                    "available_types": [
                        "basic",
                        "premium",
                        "ultra"
                    ]
                },
                "user_accounts": {
                    "included": 5,
                    "allow_additional": true,
                    "base_cost_eur": 5,
                    "cost_eur_with_discount": 5
                },
                "workers": {
                    "included": 2,
                    "allow_additional": false
                },
                "storage_mounts": {
                    "included": 2,
                    "allow_additional": true,
                    "base_cost_eur": 10,
                    "cost_eur_with_discount": 10
                }
            },
            "features": {
                "all_ai_functions": true,
                "api_access": true,
                "webhooks": false,
                "custom_integrations": false,
                "trust_center": false,
                "sso_saml": false,
                "audit_logs": false
            },
            "rate_limits": {
                "requests_per_second": 5,
                "requests_per_minute": 100,
                "requests_per_hour": 1000,
                "requests_per_day": 10000
            },
            "queue_limits": {
                "max_concurrent_jobs": 2,
                "max_queued_jobs": 5,
                "max_queued_credits": 50,
                "queue_timeout_minutes": 60
            },
            "crawler": {
                "storage_mounts": {
                    "included": 2,
                    "allow_additional": true,
                    "cost_per_additional_credits": 10000
                },
                "storage_modes": {
                    "import": true,
                    "crawl": true,
                    "user_storage": false
                },
                "connector_types": {
                    "sftp": true
                },
                "rate_limits": {
                    "files_per_day": 2000
                },
                "polling": {
                    "min_interval_seconds": 300
                },
                "after_import": [
                    "keep",
                    "move"
                ],
                "file_pattern": true,
                "recursive": true,
                "primary_secondary_redundancy": false
            }
        },
        "APP-T3": {
            "name": "Professional",
            "description": "for Business teams with professional requirements",
            "credits_monthly": 200000,
            "overage_factor": 4,
            "is_paid": true,
            "default_priority": 100,
            "identification_method": "bearertoken",
            "vpn_allowed": true,
            "price_yearly": 2400,
            "price_billed_monthly": 270,
            "included_storage_pages": 100000,
            "stripe_product_id": "prod_U2tBw2pa2UxZKy",
            "tab": "enduser",
            "tab_position": 3,
            "support": "helpdesk_l1l2",
            "sla": "99.5%",
            "resources": {
                "workspaces": {
                    "included": 10,
                    "allow_additional": true,
                    "base_cost_eur": 5,
                    "cost_eur_with_discount": 4,
                    "included_type": "basic",
                    "available_types": [
                        "basic",
                        "premium",
                        "ultra"
                    ]
                },
                "user_accounts": {
                    "included": 10,
                    "allow_additional": true,
                    "base_cost_eur": 5,
                    "cost_eur_with_discount": 4
                },
                "workers": {
                    "included": 5,
                    "allow_additional": false
                },
                "storage_mounts": {
                    "included": 3,
                    "allow_additional": true,
                    "base_cost_eur": 10,
                    "cost_eur_with_discount": 8
                }
            },
            "features": {
                "all_ai_functions": true,
                "api_access": true,
                "webhooks": true,
                "custom_integrations": false,
                "trust_center": false,
                "sso_saml": false,
                "audit_logs": false
            },
            "rate_limits": {
                "requests_per_second": 10,
                "requests_per_minute": 300,
                "requests_per_hour": 5000,
                "requests_per_day": 50000
            },
            "queue_limits": {
                "max_concurrent_jobs": 5,
                "max_queued_jobs": 15,
                "max_queued_credits": 500,
                "queue_timeout_minutes": 120
            },
            "crawler": {
                "storage_mounts": {
                    "included": 3,
                    "allow_additional": true,
                    "cost_per_additional_credits": 10000
                },
                "storage_modes": {
                    "import": true,
                    "crawl": true,
                    "user_storage": true
                },
                "connector_types": {
                    "sftp": true
                },
                "rate_limits": {
                    "files_per_day": 10000
                },
                "polling": {
                    "min_interval_seconds": 60
                },
                "after_import": [
                    "keep",
                    "move",
                    "delete",
                    "archive"
                ],
                "file_pattern": true,
                "recursive": true,
                "primary_secondary_redundancy": true
            }
        },
        "APP-T4": {
            "name": "Corporate",
            "description": "For large enterprises with high requirements",
            "credits_monthly": 500000,
            "overage_factor": 3,
            "is_paid": true,
            "default_priority": 125,
            "identification_method": "bearertoken",
            "vpn_allowed": true,
            "price_billed_monthly": 500,
            "included_storage_pages": 1000000,
            "extra_discount_percent": 40,
            "tab": "business",
            "tab_position": 1,
            "support": "phone_meet",
            "sla": "99.9%",
            "resources": {
                "workspaces": {
                    "included": 25,
                    "allow_additional": true,
                    "base_cost_eur": 5,
                    "cost_eur_with_discount": 3,
                    "included_type": "basic",
                    "available_types": [
                        "basic",
                        "premium",
                        "ultra"
                    ]
                },
                "user_accounts": {
                    "included": 25,
                    "allow_additional": true,
                    "base_cost_eur": 5,
                    "cost_eur_with_discount": 3
                },
                "workers": {
                    "included": 10,
                    "allow_additional": false
                },
                "storage_mounts": {
                    "included": 5,
                    "allow_additional": true,
                    "base_cost_eur": 10,
                    "cost_eur_with_discount": 6
                }
            },
            "features": {
                "all_ai_functions": true,
                "api_access": true,
                "webhooks": true,
                "custom_integrations": true,
                "trust_center": true,
                "sso_saml": false,
                "audit_logs": true
            },
            "rate_limits": {
                "requests_per_second": 20,
                "requests_per_minute": 600,
                "requests_per_hour": 15000,
                "requests_per_day": 150000
            },
            "queue_limits": {
                "max_concurrent_jobs": 10,
                "max_queued_jobs": 50,
                "max_queued_credits": 5000,
                "queue_timeout_minutes": 180
            },
            "crawler": {
                "storage_mounts": {
                    "included": 5,
                    "allow_additional": true,
                    "cost_per_additional_credits": 10000
                },
                "storage_modes": {
                    "import": true,
                    "crawl": true,
                    "user_storage": true
                },
                "connector_types": {
                    "sftp": true
                },
                "rate_limits": {
                    "files_per_day": 50000
                },
                "polling": {
                    "min_interval_seconds": 30
                },
                "after_import": [
                    "keep",
                    "move",
                    "delete",
                    "archive"
                ],
                "file_pattern": true,
                "recursive": true,
                "primary_secondary_redundancy": true,
                "realtime_webhooks": true
            }
        },
        "APP-T5": {
            "name": "Enterprise",
            "description": "maximum Performance - no Limits, Dedicated TAM",
            "credits_monthly": 5000000,
            "overage_factor": 2,
            "is_paid": true,
            "default_priority": 150,
            "identification_method": "bearertoken",
            "vpn_allowed": true,
            "price_billed_monthly": 5000,
            "included_storage_pages": 10000000,
            "extra_discount_percent": 60,
            "stripe_product_id": "prod_UDdTdgBPppTZw2",
            "tab": "business",
            "tab_position": 2,
            "badge": "ENTERPRISE",
            "support": "phone_meet_dse",
            "sla": "99.95%",
            "resources": {
                "workspaces": {
                    "included": 100,
                    "allow_additional": true,
                    "base_cost_eur": 5,
                    "cost_eur_with_discount": 2,
                    "included_type": "basic",
                    "available_types": [
                        "basic",
                        "premium",
                        "ultra"
                    ]
                },
                "user_accounts": {
                    "included": 100,
                    "allow_additional": true,
                    "base_cost_eur": 5,
                    "cost_eur_with_discount": 2
                },
                "workers": {
                    "included": 25,
                    "allow_additional": false
                },
                "storage_mounts": {
                    "included": 10,
                    "allow_additional": true,
                    "base_cost_eur": 10,
                    "cost_eur_with_discount": 4
                }
            },
            "features": {
                "all_ai_functions": true,
                "api_access": true,
                "webhooks": true,
                "custom_integrations": true,
                "trust_center": true,
                "sso_saml": true,
                "audit_logs": true,
                "custom_contracts": true,
                "data_residency": false
            },
            "rate_limits": {
                "requests_per_second": 50,
                "requests_per_minute": 2000,
                "requests_per_hour": 50000,
                "requests_per_day": 500000
            },
            "queue_limits": {
                "max_concurrent_jobs": 25,
                "max_queued_jobs": 200,
                "max_queued_credits": 50000,
                "queue_timeout_minutes": 240
            },
            "crawler": {
                "storage_mounts": {
                    "included": 10,
                    "allow_additional": true,
                    "cost_per_additional_credits": 10000
                },
                "storage_modes": {
                    "import": true,
                    "crawl": true,
                    "user_storage": true
                },
                "connector_types": {
                    "sftp": true
                },
                "rate_limits": {
                    "files_per_day": 200000
                },
                "polling": {
                    "min_interval_seconds": 10
                },
                "after_import": [
                    "keep",
                    "move",
                    "delete",
                    "archive"
                ],
                "file_pattern": true,
                "recursive": true,
                "primary_secondary_redundancy": true,
                "realtime_webhooks": true
            }
        },
        "APP-T6": {
            "name": "Unlimited",
            "description": "maximum Performance - no Limits, Dedicated TAM",
            "credits_monthly": 15000000,
            "overage_factor": 1,
            "is_paid": true,
            "default_priority": 200,
            "identification_method": "bearertoken",
            "vpn_allowed": true,
            "price_billed_monthly": 15000,
            "included_storage_pages": 30000000,
            "extra_discount_percent": 80,
            "stripe_product_id": "prod_UGAvvHhA3N6eVI",
            "tab": "business",
            "tab_position": 3,
            "badge": "UNLIMITED",
            "support": "phone_meet_dtam",
            "sla": "99.99%",
            "resources": {
                "workspaces": {
                    "included": 500,
                    "allow_additional": true,
                    "base_cost_eur": 5,
                    "cost_eur_with_discount": 1,
                    "included_type": "basic",
                    "available_types": [
                        "basic",
                        "premium",
                        "ultra"
                    ]
                },
                "user_accounts": {
                    "included": 500,
                    "allow_additional": true,
                    "base_cost_eur": 5,
                    "cost_eur_with_discount": 1
                },
                "workers": {
                    "included": 50,
                    "allow_additional": false
                },
                "storage_mounts": {
                    "included": 25,
                    "allow_additional": true,
                    "base_cost_eur": 10,
                    "cost_eur_with_discount": 2
                }
            },
            "features": {
                "all_ai_functions": true,
                "api_access": true,
                "webhooks": true,
                "custom_integrations": true,
                "trust_center": true,
                "sso_saml": true,
                "audit_logs": true,
                "custom_contracts": true,
                "data_residency": true,
                "dedicated_tam": true,
                "white_glove_onboarding": true,
                "quarterly_business_reviews": true
            },
            "rate_limits": {
                "requests_per_second": 200,
                "requests_per_minute": 10000,
                "requests_per_hour": 500000,
                "requests_per_day": 5000000
            },
            "queue_limits": {
                "max_concurrent_jobs": 50,
                "max_queued_jobs": 1000,
                "max_queued_credits": 150000,
                "queue_timeout_minutes": 360
            },
            "crawler": {
                "storage_mounts": {
                    "included": 25,
                    "allow_additional": true,
                    "cost_per_additional_credits": 0
                },
                "storage_modes": {
                    "import": true,
                    "crawl": true,
                    "user_storage": true
                },
                "connector_types": {
                    "sftp": true
                },
                "rate_limits": {
                    "files_per_day": 1000000
                },
                "polling": {
                    "min_interval_seconds": 5
                },
                "after_import": [
                    "keep",
                    "move",
                    "delete",
                    "archive"
                ],
                "file_pattern": true,
                "recursive": true,
                "primary_secondary_redundancy": true,
                "realtime_webhooks": true
            }
        },
        "API-T1": {
            "name": "API Starter",
            "description": "for first API-integrations and tests",
            "credits_monthly": 25000,
            "overage_factor": 5,
            "is_paid": true,
            "default_priority": 50,
            "identification_method": "bearertoken",
            "vpn_allowed": true,
            "rate_limits": {
                "requests_per_second": 30,
                "requests_per_minute": 500,
                "requests_per_hour": 5000,
                "requests_per_day": 25000
            },
            "queue_limits": {
                "max_concurrent_jobs": 3,
                "max_queued_jobs": 10,
                "max_queued_credits": 250,
                "queue_timeout_minutes": 60
            }
        },
        "API-T2": {
            "name": "API Professional",
            "description": "for productive API-usage",
            "credits_monthly": 100000,
            "overage_factor": 4,
            "is_paid": true,
            "default_priority": 100,
            "identification_method": "bearertoken",
            "vpn_allowed": true,
            "badge": "BELIEBT",
            "rate_limits": {
                "requests_per_second": 50,
                "requests_per_minute": 1000,
                "requests_per_hour": 10000,
                "requests_per_day": 100000
            },
            "queue_limits": {
                "max_concurrent_jobs": 5,
                "max_queued_jobs": 30,
                "max_queued_credits": 1000,
                "queue_timeout_minutes": 120
            }
        },
        "API-T3": {
            "name": "API Business",
            "description": "for high API-volumes",
            "credits_monthly": 500000,
            "overage_factor": 3,
            "is_paid": true,
            "default_priority": 125,
            "identification_method": "bearertoken",
            "vpn_allowed": true,
            "rate_limits": {
                "requests_per_second": 100,
                "requests_per_minute": 2000,
                "requests_per_hour": 50000,
                "requests_per_day": 500000
            },
            "queue_limits": {
                "max_concurrent_jobs": 10,
                "max_queued_jobs": 100,
                "max_queued_credits": 5000,
                "queue_timeout_minutes": 180
            }
        },
        "API-T4": {
            "name": "API Enterprise",
            "description": "Enterprise-Grade API-access",
            "credits_monthly": 1500000,
            "overage_factor": 2,
            "is_paid": true,
            "default_priority": 150,
            "identification_method": "bearertoken",
            "vpn_allowed": true,
            "badge": "ENTERPRISE",
            "rate_limits": {
                "requests_per_second": 200,
                "requests_per_minute": 5000,
                "requests_per_hour": 150000,
                "requests_per_day": 1500000
            },
            "queue_limits": {
                "max_concurrent_jobs": 20,
                "max_queued_jobs": 300,
                "max_queued_credits": 15000,
                "queue_timeout_minutes": 240
            }
        },
        "API-T5": {
            "name": "API Ultimate",
            "description": "Maximale API-Performance",
            "credits_monthly": 5000000,
            "overage_factor": 1,
            "is_paid": true,
            "default_priority": 200,
            "identification_method": "bearertoken",
            "vpn_allowed": true,
            "badge": "UNLIMITED",
            "rate_limits": {
                "requests_per_second": 500,
                "requests_per_minute": 10000,
                "requests_per_hour": 500000,
                "requests_per_day": 5000000
            },
            "queue_limits": {
                "max_concurrent_jobs": 50,
                "max_queued_jobs": 1000,
                "max_queued_credits": 50000,
                "queue_timeout_minutes": 360
            }
        },
        "SLA-T1": {
            "name": "Basic Support",
            "description": "Personal Support - access only about ticketystem",
            "credits_monthly": 0,
            "overage_factor": 0,
            "is_paid": true,
            "default_priority": 100,
            "identification_method": "bearertoken",
            "vpn_allowed": false,
            "availability": "Mo-Fr 11:00 - 14:00 Uhr",
            "availability_hours": {
                "start": "11:00",
                "end": "14:00",
                "days": [
                    "Mo",
                    "Di",
                    "Mi",
                    "Do",
                    "Fr"
                ],
                "timezone": "Europe/Berlin"
            },
            "direct_access": {
                "direct_email": false,
                "direct_phone": false,
                "ticket_system": true
            },
            "channels": [
                "google_meet",
                "anydesk",
                "phone"
            ],
            "support_level": 1,
            "support_level_name": "Junior",
            "dedicated_manager": false
        },
        "SLA-T2": {
            "name": "Priority Support",
            "description": "Personal Support - Direkte Email to the support team",
            "credits_monthly": 0,
            "overage_factor": 0,
            "is_paid": true,
            "default_priority": 100,
            "identification_method": "bearertoken",
            "vpn_allowed": false,
            "availability": "Mo-Fr 10:00 - 14:00 Uhr",
            "availability_hours": {
                "start": "10:00",
                "end": "14:00",
                "days": [
                    "Mo",
                    "Di",
                    "Mi",
                    "Do",
                    "Fr"
                ],
                "timezone": "Europe/Berlin"
            },
            "direct_access": {
                "direct_email": true,
                "direct_phone": false,
                "ticket_system": true
            },
            "channels": [
                "google_meet",
                "anydesk",
                "phone",
                "direct_email"
            ],
            "support_level": 2,
            "support_level_name": "Mid-Level",
            "dedicated_manager": false,
            "uptime_sla": "99.5%",
            "incident_reports": "monthly"
        },
        "SLA-T3": {
            "name": "Dedicated Support",
            "description": "Personal Support - Dedicated TAM with direct Email + phone extension",
            "credits_monthly": 0,
            "overage_factor": 0,
            "is_paid": true,
            "default_priority": 100,
            "identification_method": "bearertoken",
            "vpn_allowed": false,
            "availability": "Mo-Fr 09:00 - 18:00 Uhr",
            "availability_hours": {
                "start": "09:00",
                "end": "18:00",
                "days": [
                    "Mo",
                    "Di",
                    "Mi",
                    "Do",
                    "Fr"
                ],
                "timezone": "Europe/Berlin"
            },
            "direct_access": {
                "direct_email": true,
                "direct_phone": true,
                "ticket_system": true
            },
            "channels": [
                "google_meet",
                "anydesk",
                "phone",
                "direct_email",
                "direct_phone"
            ],
            "support_level": 3,
            "support_level_name": "Senior",
            "dedicated_manager": true,
            "dedicated_manager_type": "TAM",
            "uptime_sla": "99.9%",
            "incident_reports": "weekly"
        }
    },
    "sample_note": "Sample shows paid tiers only (free tiers VPN, VISITOR, APP-LITE, APP-FREE are omitted for brevity but DO exist in the live response)."
}
```

### Calculate pricing (full)

`GET https://api.paperoffice.ai/latest/billing/pricing/all`

Returns all pricing data: tiers, job costs, overage system, storage pricing, priority system, support levels, and feature matrix.

**Tool-ID:** `po_billing_calculator` • **Cost:** 10 credits • **MCP:** `po_billing_calculator` via `mcp.paperoffice.ai`

### List API job costs per service

`GET https://api.paperoffice.ai/latest/billing/pricing/jobs`

Shows credit costs for each individual API service (OCR, LLM, Voice, Import, etc.) with optional category filter.

**Tool-ID:** `po_billing_jobs` • **Cost:** 10 credits • **MCP:** `po_billing_jobs` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `category` | string | No | Service-category filter (optional). Beispiele: llm, voice, ocr, import, documents, billing, ip2location, paprooffice_account, paprooffice_agent, onboarding |

---

## Account — Webhooks

### Create Webhook Subscription

`POST https://api.paperoffice.ai/latest/webhooks/subscribe`

Create a new webhook Subscription. payloads are signed with HMAC-SHA256.

**Tool-ID:** `po_webhooks_subscribe` • **Cost:** Free • **MCP:** `po_webhooks_subscribe` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Name the Subscription (Required) |
| `url` | string | Yes | Webhook-target-URL (https empfohlen) |
| `events` | array | Yes | Array of event types or [*] for all |
| `secret` | string | No | HMAC-Secret (is auto-generates if empty) |
| `filters` | object | No | Optional Filter (e.g. workspace_id, pofid) |
| `headers` | object | No | Additional HTTP headers as key-value pairs |
| `retry_policy` | string | No | Retry-Strategie (default: exponential) (allowed: none, linear, exponential) |
| `max_retries` | integer | No | Max. Retries (0-10, default: 5) |
| `timeout_ms` | integer | No | Timeout in ms (1000-30000, default: 10000) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Delete Webhook Subscription

`POST https://api.paperoffice.ai/latest/webhooks/delete`

Delete a webhook Subscription. The delivery log is preserved.

**Tool-ID:** `po_webhooks_delete` • **Cost:** Free • **MCP:** `po_webhooks_delete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `subscription_id` | integer | Yes | ID of the Subscription to delete |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "deleted": true,
    "deleted_at": "2026-04-16T10:00:00Z"
}
```

### Get webhook system info

`GET https://api.paperoffice.ai/latest/webhooks/info`

Webhook system overview: available events, endpoints, and signature information.

**Tool-ID:** `po_webhooks_info` • **Cost:** Free • **MCP:** `po_webhooks_info` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "webhooks___info",
        "app": "webhooks",
        "action": "info",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.17ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List Job Subscriptions

`GET https://api.paperoffice.ai/latest/webhooks/job-subscriptions`

List all job subscriptions for the account.

**Tool-ID:** `po_webhooks_job_subscriptions` • **Cost:** Free • **MCP:** `po_webhooks_job_subscriptions` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `active_only` | string | No | Only active (not consumed) display (default: 1) (allowed: 0, 1) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "webhooks___job-subscriptions",
        "app": "webhooks",
        "action": "job-subscriptions",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.38ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List webhook deliveries

`GET https://api.paperoffice.ai/latest/webhooks/deliveries`

Webhook-Delivery-Log retrieve (delivery history).

**Tool-ID:** `po_webhooks_deliveries` • **Cost:** Free • **MCP:** `po_webhooks_deliveries` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `subscription_id` | integer | No | Optional: Only Deliveries for these Subscription |
| `event_type` | string | No | Optional: Filter by event type |
| `limit` | integer | No | Max. results (1-100, default: 50) |
| `offset` | integer | No | Offset for Pagination (default: 0) |
| `success_only` | boolean | No | true=only successful, false=only failed |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "webhooks___deliveries",
        "app": "webhooks",
        "action": "deliveries",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.29ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List Webhook Subscriptions

`GET https://api.paperoffice.ai/latest/webhooks/list`

List all webhook subscriptions of the account.

**Tool-ID:** `po_webhooks_list` • **Cost:** Free • **MCP:** `po_webhooks_list` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "webhooks___list",
        "app": "webhooks",
        "action": "list",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.16ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Subscribe to Job

`POST https://api.paperoffice.ai/latest/webhooks/subscribe-job`

Create a one-time webhook Subscription for a specific job ID.

**Tool-ID:** `po_webhooks_subscribe_job` • **Cost:** Free • **MCP:** `po_webhooks_subscribe_job` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | string | Yes | Job-ID (Required, alphanumerisch, max 128 characters) |
| `url` | string | Yes | Webhook-target-URL |
| `secret` | string | No | HMAC-Secret (is auto-generates if empty) |
| `events` | array | No | Events (default: [job.completed, job.failed]) |
| `headers` | object | No | Additional HTTP-Header |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Test webhook

`POST https://api.paperoffice.ai/latest/webhooks/test`

Send a test event to a webhook Subscription to verify delivery.

**Tool-ID:** `po_webhooks_test` • **Cost:** Free • **MCP:** `po_webhooks_test` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `subscription_id` | integer | Yes | ID of the Subscription (Required) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Update Webhook Subscription

`POST https://api.paperoffice.ai/latest/webhooks/update`

existing Webhook-Subscription update.

**Tool-ID:** `po_webhooks_update` • **Cost:** Free • **MCP:** `po_webhooks_update` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `subscription_id` | integer | Yes | ID of the Subscription (Required) |
| `name` | string | No | New name |
| `url` | string | No | new URL |
| `events` | array | No | new Event-list |
| `secret` | string | No | new Secret |
| `filters` | object | No | new Filter |
| `headers` | object | No | new Header |
| `is_active` | boolean | No | Aktiv/Inaktiv setzen |
| `retry_policy` | string | No | new Retry-Strategie (allowed: none, linear, exponential) |
| `max_retries` | integer | No | new max. Retries |
| `timeout_ms` | integer | No | new Timeout |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "updated": true,
    "updated_at": "2026-04-16T10:00:00Z"
}
```

---

## Agents AI — AI Features

### Create or update agent

`POST https://api.paperoffice.ai/latest/agents_v2/create`

Create or Update AI Agent Attach AI agent configuration to a document. Use case: - Custom extraction fields beyond standard IDP

**Tool-ID:** `po_agents_createupdate` • **Cost:** Free • **MCP:** `po_agents_createupdate` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `uuid` | string | No | UUID of the Agents (only at Update) |
| `name` | string | No | Name of the Agents (Required at recreation) |
| `system_prompt` | string | No | System-Prompt of the Agents (Required at recreation) |
| `description` | string | No | Description of the Agents |
| `llm_tier` | string | No | LLM-quality level (allowed: basic, premium, ultra) (default: "basic") |
| `channels` | array | No | communication channels (chat, phone, email, widget) |
| `voice_id` | string | No | Voice-ID for Telefonie-channel |
| `language` | string | No | language of the Agents (ISO-Code) (default: "de") |
| `category` | string | No | category of the Agents |
| `tags` | array | No | Tags for Search and filtering |
| `is_active` | boolean | No | Agent aktiv schalten (default: true) |
| `max_turns` | integer | No | Max. Gespraechsrunden (default: 10) |
| `temproature` | number | No | LLM-Temproatur (0.0-2.0) (default: 0.7) |
| `knowledge_workspace_ids` | array | No | Workspace IDs for RAG-access |
| `tools` | array | No | Agent-Tools (MCP-Tool-IDs) |
| `sub_agents` | array | No | Sub-Agent-UUIDs for Delegation |
| `escalation_config` | object | No | Eskalations-configuration (an Mensch, Helpdesk, etc.) |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "agent_id": "example",
            "status": "success"
        }
    },
    "job_type": "example",
    "model": "example",
    "current_step": "example"
}
```

### Delete agent

`POST https://api.paperoffice.ai/latest/agents_v2/delete`

Delete AI Agent Remove agent configuration from a document.

**Tool-ID:** `po_agents_delete` • **Cost:** 10 credits • **MCP:** `po_agents_delete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `uuid` | string | Yes | UUID of the zu deleteden Agents |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "deleted": true
        }
    }
}
```

### Generate meeting prep briefing

`POST https://api.paperoffice.ai/latest/document_intelligence/meeting_prep`

AI Meeting Prep Generate AI briefing for upcoming meeting.

**Tool-ID:** `po_ai_features_meeting_prep` • **Cost:** Free • **MCP:** `po_ai_features_meeting_prep` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `event_id` | integer | Yes | Event-ID for meeting preparation to be created |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "preparation": "example",
            "key_documents": [
                []
            ],
            "action_items": [
                "example"
            ]
        }
    },
    "job_type": "example",
    "model": "example",
    "current_step": "example"
}
```

### Get agent

`POST https://api.paperoffice.ai/latest/agents_v2/get`

Get AI Agent Retrieve agent configuration and extracted data.

**Tool-ID:** `po_agents_get` • **Cost:** 10 credits • **MCP:** `po_agents_get` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `uuid` | string | Yes | UUID of the abzurufenden Agents |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "agent_id": "example",
            "name": "Example",
            "type": "example",
            "status": "success",
            "config": []
        }
    },
    "job_type": "example",
    "model": "example",
    "current_step": "example"
}
```

### List agents

`POST https://api.paperoffice.ai/latest/agents_v2/list`

List All AI Agents Get all AI agents for the authenticated account.

**Tool-ID:** `po_agents_list` • **Cost:** 10 credits • **MCP:** `po_agents_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `locale` | string | No | Response language: de_DE, en_US, es_ES, fr_FR, it_IT, pt_PT |

**Example Response:**

```json
{
    "data": {
        "agents": [],
        "total": 0,
        "limit": 50,
        "offset": 0
    },
    "processing_time": "33.88ms",
    "status": "success"
}
```

### Predict no-show risk

`POST https://api.paperoffice.ai/latest/document_intelligence/noshow_risk`

AI No-Show Risk Predict no-show probability for a meeting.

**Tool-ID:** `po_ai_features_noshow_risk` • **Cost:** Free • **MCP:** `po_ai_features_noshow_risk` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `event_id` | integer | No | Event-ID for risk assessment |
| `guest_email` | string | No | Guest email for historical analysis |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "risk_score": 1,
            "risk_factors": [
                "example"
            ],
            "recommendation": "example"
        }
    },
    "job_type": "example",
    "model": "example",
    "current_step": "example"
}
```

### Suggest smart appointment slots

`POST https://api.paperoffice.ai/latest/document_intelligence/smart_slots`

AI Smart Slots Get AI-optimized slot suggestions based on your patterns.

**Tool-ID:** `po_ai_features_smart_slots` • **Cost:** Free • **MCP:** `po_ai_features_smart_slots` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `guest_email` | string | No | Guest email for prosonalisierte suggestions |
| `meeting_type_id` | integer | No | meeting type ID for duration and buffer calculation |
| `preferred_times` | array | No | Bevorzugte Zeiten of the Gastes (e.g. morgens, nachmittags) |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "suggested_slots": [
                []
            ],
            "optimal_time": "2026-04-16T10:00:00Z"
        }
    },
    "job_type": "example",
    "model": "example",
    "current_step": "example"
}
```

---

## Analytics AI

### Get document topics and clustering

`GET https://api.paperoffice.ai/latest/document_intelligence/topics`

Displays the topic clusters of the documents. The Harvester automatically groups documents into topic clusters (e.g., invoices, contracts, correspondence). Also shows which documents belong to which topic.

**Tool-ID:** `po_intelligence_topics` • **Cost:** 10 credits • **MCP:** `po_intelligence_topics` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_id` | string | No | Optional: Only Topics for theses Document |
| `limit` | integer | No | Max. Topics (default: 20) |
| `include_documents` | boolean | No | Document-list per Topic (default: false) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 4950
    },
    "job": {
        "api_job_name": "document_intelligence___topics",
        "app": "document_intelligence",
        "action": "topics",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.75ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get knowledge graph document entities

`GET https://api.paperoffice.ai/latest/document_intelligence/entities/{document_id}`

Get all extracted entities from a document. Entity Types: - company, person, amount, date, location, iban, product, custom Tier: PREMIUM+ 3 credits

**Tool-ID:** `po_knowledge_graph_document_entities_get` • **Cost:** 10 credits • **MCP:** `po_knowledge_graph_document_entities_get` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `include_relations` | string | No | Include entity-entity relations |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 4950
    },
    "job": {
        "api_job_name": "document_intelligence___entities",
        "app": "document_intelligence",
        "action": "entities",
        "option": "{document_id}",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "10.08ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get knowledge graph document relations

`GET https://api.paperoffice.ai/latest/document_intelligence/relations/{document_id}`

Get a list of document relations not graph format. relation Types: - references, supersedes, attachment_of, response_to - invoice_for, payment_for, contract_with, order_for, delivery_for Tier: PREMIUM+ 3 credits

**Tool-ID:** `po_knowledge_graph_document_relations_get` • **Cost:** 10 credits • **MCP:** `po_knowledge_graph_document_relations_get` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `direction` | string | No | outgoing, incoming, or both |
| `limit` | string | No | Max relations (max: 100) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 4950
    },
    "job": {
        "api_job_name": "document_intelligence___relations",
        "app": "document_intelligence",
        "action": "relations",
        "option": "{document_id}",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.74ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get knowledge graph for document

`GET https://api.paperoffice.ai/latest/document_intelligence/knowledge_graph/{document_id}`

Get a vi.js compatible graph centered on a specific document. Returns: - nodes - Array of vis.js node objects - edges - Array of vis.js edge objects - groups - Node group styling definitions - options - vis.js physics and interaction options Tier: PREMIUM+ 5 credits

**Tool-ID:** `po_knowledge_graph_document_graph_get` • **Cost:** 10 credits • **MCP:** `po_knowledge_graph_document_graph_get` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `depth` | string | No | Hop depth 1-3 (3 requires ULTRA) |
| `include_entities` | string | No | Include entity nodes (companies, prosons, etc.) |
| `max_nodes` | string | No | Maximum nodes to return (max: 200) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 4950
    },
    "job": {
        "api_job_name": "document_intelligence___knowledge_graph",
        "app": "document_intelligence",
        "action": "knowledge_graph",
        "option": "{document_id}",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "12.59ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get knowledge graph statistics

`GET https://api.paperoffice.ai/latest/knowledge_graph/stats`

Get knowledge graph statistics. Returns: - Total documents, relations, entities - relation type counts - Entity type counts - Available tier features Tier: ALL 0 credits

**Tool-ID:** `po_knowledge_graph_stats_get` • **Cost:** 10 credits • **MCP:** `po_knowledge_graph_stats_get` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | string | No | Optional: Filter by workspace |

**Example Response:**

```json
{
    "available_views": {
        "partners": "business partner-overview",
        "workspace": "Workspace-documents",
        "document": "document-relationships",
        "business_case": "business transaction",
        "timeline": "Zeitachse",
        "references": "Referenznummern"
    },
    "processing_time": "21.99ms",
    "stats": {
        "total_documents": 1,
        "documents_with_partner": 0,
        "unique_partners": 0,
        "documents_with_references": 0,
        "type_distribution": [
            {
                "type": "Notiz",
                "count": 1
            },
            {
                "type": "other",
                "count": 1
            }
        ]
    },
    "status": "success",
    "tier": "APP-T2",
    "workspace_id": null
}
```

### Get workspace knowledge graph

`GET https://api.paperoffice.ai/latest/document_intelligence/knowledge_graph/{workspace_id}`

Get a vi.js compatible graph for an entire workspace. Returns: Same structure as Document Graph but includes all workspace documents. Tier: PREMIUM+ 10 credits

**Tool-ID:** `po_knowledge_graph_workspace_graph_get` • **Cost:** 10 credits • **MCP:** `po_knowledge_graph_workspace_graph_get` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `include_entities` | string | No | Include entity nodes |
| `max_nodes` | string | No | Maximum nodes (max: 500) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 4900
    },
    "job": {
        "api_job_name": "document_intelligence___knowledge_graph",
        "app": "document_intelligence",
        "action": "knowledge_graph",
        "option": "{workspace_id}",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.62ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List knowledge graph business partners

`GET https://api.paperoffice.ai/latest/knowledge_graph/partners`

Displays all of the user's business partners as a network graph. Based on the knowledge graph automatically extracted from documents by the Harvester. Shows relationships between companies, individuals, and documents.

**Tool-ID:** `po_knowledge_graph_partners` • **Cost:** 10 credits • **MCP:** `po_knowledge_graph_partners` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | No | Max. number of partners (default: 50) |
| `sort_by` | string | No | sorting (allowed: document_count, total_amount, name) |
| `entity_type` | string | No | Filter after type (allowed: company, proson, all) |
| `workspace_id` | integer | Yes | Workspace id |
| `query` | string | Yes | Query |

**Example Response:**

```json
{
    "partners": [],
    "processing_time": "19.74ms",
    "query": "test",
    "sort_by": "document_count",
    "status": "success",
    "tier": "APP-T2",
    "total": 0,
    "workspace_id": 1
}
```

### Search entities across documents

`GET https://api.paperoffice.ai/latest/document_intelligence/entities/search`

Search for entities (companies, persons, IBANs, amounts, etc.) across all documents. Utilizes the entity index automatically created by the Harvester.

**Tool-ID:** `po_intelligence_entities_search` • **Cost:** 10 credits • **MCP:** `po_intelligence_entities_search` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | Search term (company name, Person, IBAN, etc.) |
| `entity_type` | string | No | Filter after Entity-type (allowed: company, proson, iban, amount, reference, address, email, phone, date, all) |
| `limit` | integer | No | Max. results (default: 20) |
| `type` | string | No | Type |
| `workspace_id` | integer | Yes | Workspace id |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 4950
    },
    "job": {
        "api_job_name": "document_intelligence___entities",
        "app": "document_intelligence",
        "action": "entities",
        "option": "search",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.34ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Generate report

`GET https://api.paperoffice.ai/latest/bi/bi-document-stats`

Generate Report Generate a new business report.

**Tool-ID:** `po_bi_generate_report` • **Cost:** 100 credits • **MCP:** `po_bi_generate_report` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `report_type` | string | No | type the Berichts (allowed: usage, documents, workflows, storage, comprehensive) |
| `proiod` | string | No | time proiod (allowed: 7d, 30d, 90d, 1y) (default: "30d") |
| `workspace_id` | integer | No | Workspace ID for workspace-specific reports |
| `metrics` | array | No | Gewuenschte Metriken |
| `format` | string | No | Output format (allowed: json, pdf, xlsx) (default: "json") |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 4900
    },
    "job": {
        "api_job_name": "bi___bi-document-stats",
        "app": "bi",
        "action": "bi-document-stats",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.54ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get dashboard

`GET https://api.paperoffice.ai/latest/bi/bi-dashboard`

Get BI Dashboard Retrieve business intelligence dashboard data.

**Tool-ID:** `po_bi_get_dashboard` • **Cost:** 10 credits • **MCP:** `po_bi_get_dashboard` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `proiod` | string | No | time proiod for Dashboard data (allowed: 7d, 30d, 90d, 1y) (default: "30d") |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 4900
    },
    "job": {
        "api_job_name": "bi___bi-dashboard",
        "app": "bi",
        "action": "bi-dashboard",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.66ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get reports

`GET https://api.paperoffice.ai/latest/bi/bi-trends`

Get BI Reports List available business reports.

**Tool-ID:** `po_bi_get_reports` • **Cost:** 10 credits • **MCP:** `po_bi_get_reports` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | No | Max. number of reports (default: 20) |
| `offset` | integer | No | Pagination-Offset (default: 0) |
| `report_type` | string | No | Filter after Berichtstyp |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 4900
    },
    "job": {
        "api_job_name": "bi___bi-trends",
        "app": "bi",
        "action": "bi-trends",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.41ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

---

## Data AI — Currency Exchange

### Convert currency

`POST https://api.paperoffice.ai/latest/currency_exchange/get_rates`

Convert Currency Convert an amount from one currency to another. Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | from | string | ✅ Yes | Source currency code EUR, USD, GBP, etc. | | to | string | ✅ Yes | Target currency code | | amount .

**Tool-ID:** `po_currency_convert_currency` • **Cost:** 10 credits • **MCP:** `po_currency_convert_currency` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | No | Source currency code (ISO 4217) |
| `to` | string | No | Target currency code (ISO 4217) |
| `amount` | string | No | Amount to convert (default: 1) |

**Example Response:**

```json
{
    "amount": 1,
    "base": "EUR",
    "currencies_count": 172,
    "processing_time": "45.32ms",
    "rates": {
        "AED": 4.250462,
        "AFN": 74.070929,
        "ALL": 96.3481,
        "AMD": 436.515853,
        "ANG": 2.071821,
        "AOA": 1061.293403,
        "ARS": 1600.052522,
        "AUD": 1.67369,
        "AWG": 2.084641,
        "AZN": 1.967762,
        "BAM": 1.974336,
        "BBD": 2.32986,
        "BDT": 141.935344,
        "BGN": 1.978216,
        "BHD": 0.436987,
        "BIF": 3430.292908,
        "BMD": 1.157389,
        "BND": 1.493451,
        "BOB": 7.993361,
        "BRL": 6.011876,
        "BSD": 1.156776,
        "BTC": 1.7e-5,
        "BTN": 110.079825,
        "BWP": 15.957976,
        "BYN": 3.440065,
        "BYR": 22683.448379,
        "BZD": 2.326488,
        "CAD": 1.608943,
        "CDF": 2644.526446,
        "CHF": 0.92241,
        "CLF": 0.02716,
        "CLP": 1072.383008,
        "CNY": 7.970014,
        "CNH": 7.969425,
        "COP": 4263.289526,
        "CRC": 537.873354,
        "CUC": 1.157366,
        "CUP": 30.668948,
        "CVE": 110.963501,
        "CZK": 24.546694,
        "DJF": 205.678414,
        "DKK": 7.472293,
        "DOP": 69.554163,
        "DZD": 154.209262,
        "EGP": 63.165184,
        "ERN": 17.36065,
        "ETB": 181.766685,
        "EUR": 1,
        "FJD": 2.612529,
        "FKP": 0.877319,
        "GBP": 0.873024,
        "GEL": 3.112729,
        "GGP": 0.877293,
        "GHS": 12.730783,
        "GIP": 0.877293,
        "GMD": 85.642871,
        "GNF": 10155.777594,
        "GTQ": 8.851046,
        "GYD": 242.093486,
        "HKD": 9.071701,
        "HNL": 30.785127,
        "HRK": 7.537035,
        "HTG": 151.825382,
        "HUF": 384.121633,
        "IDR": 19670.97046,
        "ILS": 3.63372,
        "IMP": 0.877301,
        "INR": 108.483763,
        "IQD": 1516.163428,
        "IRR": 1522963.015607,
        "ISK": 143.408005,
        "JEP": 0.87731,
        "JMD": 183.017286,
        "JOD": 0.820524,
        "JPY": 183.802888,
        "KES": 150.451414,
        "KGS": 101.208215,
        "KHR": 4640.894625,
        "KMF": 495.929322,
        "KPW": 1041.58885,
        "KRW": 1743.756137,
        "KWD": 0.358364,
        "KYD": 0.963988,
        "KZT": 551.134215,
        "LAK": 25403.909189,
        "LBP": 103596.785226,
        "LKR": 364.931278,
        "LRD": 212.576925,
        "LSL": 19.755604,
        "LTL": 3.417467,
        "LVL": 0.700092,
        "LYD": 7.412895,
        "MAD": 10.812789,
        "MDL": 20.486742,
        "MGA": 4835.277645,
        "MKD": 61.635089,
        "MMK": 2429.788592,
        "MNT": 4133.043654,
        "MOP": 9.340538,
        "MRU": 46.421107,
        "MUR": 54.153807,
        "MVR": 17.903858,
        "MWK": 2010.282363,
        "MXN": 20.704254,
        "MYR": 4.672909,
        "MZN": 74.014038,
        "NAD": 19.756443,
        "NGN": 1601.844185,
        "NIO": 42.508789,
        "NOK": 11.194325,
        "NPR": 176.120473,
        "NZD": 2.014032,
        "OMR": 0.444992,
        "PAB": 1.156783,
        "PEN": 4.045982,
        "PGK": 5.080638,
        "PHP": 69.813353,
        "PKR": 323.132924,
        "PLN": 4.287121,
        "PYG": 7493.34984,
        "QAR": 4.217547,
        "RON": 5.097855,
        "RSD": 117.414742,
        "RUB": 94.094853,
        "RWF": 1689.75303,
        "SAR": 4.343964,
        "SBD": 9.307666,
        "SCR": 17.111984,
        "SDG": 695.548022,
        "SEK": 10.928986,
        "SGD": 1.487773,
        "SHP": 0.868332,
        "SLE": 28.412382,
        "SLL": 24269.865145,
        "SOS": 661.408866,
        "SRD": 43.254526,
        "STD": 23955.120632,
        "STN": 25.143002,
        "SVC": 10.122579,
        "SYP": 127.955121,
        "SZL": 19.755877,
        "THB": 37.821353,
        "TJS": 11.087704,
        "TMT": 4.062311,
        "TND": 3.391112,
        "TOP": 2.786545,
        "TRY": 51.486888,
        "TTD": 7.859208,
        "TWD": 36.928831,
        "TZS": 2998.514229,
        "UAH": 50.819727,
        "UGX": 4354.991073,
        "USD": 1.157331,
        "UYU": 46.930129,
        "UZS": 14114.496967,
        "VES": 547.766216,
        "VND": 30484.081903,
        "VUV": 139.275614,
        "WST": 3.204964,
        "XAF": 662.180309,
        "XAG": 0.015511,
        "XAU": 0.000247,
        "XCD": 3.127742,
        "XCG": 2.084751,
        "XDR": 0.822823,
        "XOF": 660.279678,
        "XPF": 119.332935,
        "YER": 276.205693,
        "ZAR": 19.54026,
        "ZMK": 10417.255409,
        "ZMW": 22.111591,
        "ZWL": 372.65618
    },
    "status": "success",
    "timestamp": 1775654315
}
```

### Get currency exchange rates

`GET https://api.paperoffice.ai/latest/currency_exchange/get_rates`

Get Exchange Rates Get exchange rates for all 150+ currencies based on a source currency. Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | from | string | ✅ Yes | Base currency code EUR, USD, GBP, etc. | | amount | float | No | Base amount.

**Tool-ID:** `po_currency_get_exchange_rates` • **Cost:** 10 credits • **MCP:** `po_currency_get_exchange_rates` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | No | Base currency code (ISO 4217) |
| `amount` | string | No | Base amount (default: 1) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 4850
    },
    "job": {
        "api_job_name": "currency_exchange___get_rates",
        "app": "currency_exchange",
        "action": "get_rates",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "6.05ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

---

## Data AI — IP Geolocation

### Autocomplete geocoding query

`POST https://api.paperoffice.ai/latest/geocoding/forward`

Address Autocomplete Suggestions Get address suggestions as the user types. Fast response times for real-time autocomplete. Parameters form-data | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | q | string | ✅ | Partial address/search term | | lang | stri.

**Tool-ID:** `po_geocoding_autocomplete` • **Cost:** 10 credits • **MCP:** `po_geocoding_autocomplete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `q` | string | No | Partial address/search term (default: "\u041c\u043e\u0441\u043a\u0432\u0430") |
| `lang` | string | No | Response language default: de (default: "ru") |
| `limit` | number | No | Max results 1-20 default: 10 (default: "5") |

**Example Response:**

```json
{
    "success": false,
    "error": "MISSING_ADDRESS",
    "message": "Parameter \"address\" is required",
    "example": {
        "address": "東京都渋谷区",
        "lang": "ja"
    }
}
```

### Forward geocoding

`POST https://api.paperoffice.ai/latest/geocoding/forward`

Convert Address to Coordinates Translate any address worldwide into GPS coordinates latitude/longitude. Parameters form-data | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | address | string | ✅ | Full or partial address in any language/script | | la.

**Tool-ID:** `po_geocoding_forward` • **Cost:** 10 credits • **MCP:** `po_geocoding_forward` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `address` | string | No | Full or partial address in any language/script (default: "\u6771\u4eac\u90fd\u6e0b\u8c37\u533a") |
| `lang` | string | No | Response language de, en, ja, ru, ar, zh, etc. (default: "ja") |

**Example Response:**

```json
{
    "success": false,
    "error": "MISSING_ADDRESS",
    "message": "Parameter \"address\" is required",
    "example": {
        "address": "東京都渋谷区",
        "lang": "ja"
    }
}
```

### Get geocoding service status

`GET https://api.paperoffice.ai/latest/geocoding/status`

Service Health Check Public Check if geocoding service is available. No authentication required. Response json { "success": true, "status": "operational", "endpoints": { "forward": "/geocoding/forward", "reverse": "/geocoding/reverse", "autocomplete": "/geocoding/autocomplete", "batch": "/geocodi.

**Tool-ID:** `po_geocoding_service_status` • **Cost:** Free • **MCP:** `po_geocoding_service_status` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "success": true,
    "status": "operational",
    "endpoints": {
        "forward": "/geocoding/forward",
        "reverse": "/geocoding/reverse",
        "autocomplete": "/geocoding/autocomplete",
        "batch": "/geocoding/batch"
    },
    "pricing": {
        "credits_per_request": 5,
        "credits_per_batch_item": 1,
        "batch_max_items": 1000
    },
    "cache": {
        "enabled": true,
        "ttl": "24 hours"
    },
    "supported_languages": [
        "de",
        "en",
        "es",
        "fr",
        "it",
        "ja",
        "ru",
        "ar",
        "zh",
        "ko",
        "pt",
        "nl",
        "pl",
        "tr"
    ]
}
```

### Reverse-geocode coordinates

`POST https://api.paperoffice.ai/latest/geocoding/reverse`

Convert Coordinates to Address Translate GPS coordinates latitude/longitude into a human-readable address. Parameters form-data | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | lat | float | ✅ | Latitude -90 to 90 | | lng | float | ✅ | Longitude -1.

**Tool-ID:** `po_geocoding_reverse` • **Cost:** 10 credits • **MCP:** `po_geocoding_reverse` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `lat` | number | No | Latitude -90 to 90 (default: 35.6762) |
| `lng` | number | No | Longitude -180 to 180 (default: 139.6503) |
| `lang` | string | No | Response language default: de (default: "en") |

**Example Response:**

```json
{
    "success": false,
    "error": "MISSING_COORDINATES",
    "message": "Parameters \"lat\" and \"lng\" are required",
    "example": {
        "lat": 35.6762,
        "lng": 139.6503,
        "lang": "ja"
    }
}
```

### Get IP country details

`POST https://api.paperoffice.ai/latest/ip2location/countrylist`

Full country intelligence for an IP address. Returns comprehensive country data: - VAT rates, B2B reverse charge rules - Economic zones EU, SEPA, Schengen - Legal system, GDPR status - Address/postal formats - IBAN/SWIFT bank details - Emergency phone numbers - National & regional holidays - Docu.

**Tool-ID:** `po_ip_geolocation_country_details` • **Cost:** 10 credits • **MCP:** `po_ip_geolocation_country_details` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | No | Query parameter: ip |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "ip2location___countrylist",
        "app": "ip2location",
        "action": "countrylist",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "5.87ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get IP device fingerprint

`POST https://api.paperoffice.ai/latest/ip2location/device`

Get device fingerprint information. Returns: - device_id - Unique device hash - confidence_score - Fingerprint confidence 0-100 - trust_score - Trust level 0-100 - total_visits - Visit count - first_seen / last_seen - Visit history - known_device - Previously seen device Use for: - Return visitor.

**Tool-ID:** `po_ip_geolocation_device_fingerprint` • **Cost:** 10 credits • **MCP:** `po_ip_geolocation_device_fingerprint` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | No | IP address to analyze for device fingerprint |

**Example Response:**

```json
{
    "device": {
        "browser": "Unknown browser",
        "browser_engine": "",
        "browser_major": "",
        "browser_version": "",
        "crawler": false,
        "device_brand": "",
        "device_model": "",
        "device_type": "desktop",
        "ismobiledevice": false,
        "istablet": false,
        "platform": "Unknown system",
        "platform_family": "",
        "platform_version": ""
    },
    "fingerprint": {
        "device_id": "44256a8eadf880a0660a905910f03b4d",
        "confidence_score": 30,
        "trust_score": 100,
        "ip_location_used_by": "1 user",
        "total_visits": 1,
        "first_seen": "2 months ago",
        "last_seen": "just now",
        "known_device": true
    },
    "ip": {
        "ip": "203.0.113.42",
        "location": {
            "timezone": {
                "name": "Europe/Madrid",
                "offsethours": 1
            },
            "geo_lat": 40.4167,
            "geo_lon": -3.70329,
            "city": {
                "name": "Madrid",
                "zip": "28070",
                "district": ""
            },
            "region": {
                "code": "MD",
                "name": "Madrid"
            },
            "continent": {
                "name": "Europe",
                "code": "EU"
            },
            "country": {
                "name": "Spain",
                "code": "ES",
                "currency": "EUR",
                "primary_language": "es",
                "spoken_languages": [
                    "es",
                    "eu",
                    "ca",
                    "gl"
                ],
                "capital": "Madrid",
                "callingcode": "+34",
                "vat": {
                    "standard_rate": 21,
                    "reduced_rates": [
                        10,
                        4
                    ],
                    "prefix": "ES",
                    "regex": "^ES[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                    "digital_services_rate": 21,
                    "b2b_reverse_charge": true,
                    "tax_free_threshold": 0
                },
                "economy": {
                    "currency_details": {
                        "code": "EUR",
                        "symbol": "€",
                        "position": "after",
                        "decimal": ",",
                        "thousand": ".",
                        "decimals": 2
                    },
                    "economic_zones": [
                        "EU",
                        "EEA",
                        "SEPA",
                        "Schengen"
                    ],
                    "risk_rating": "A",
                    "gdp_per_capita": 28905.45
                },
                "legal": {
                    "legal_system": "Civil Law",
                    "data_protection": "GDPR",
                    "business_registration_required": true,
                    "electronic_signature": "eIDAS",
                    "age_of_majority": 18,
                    "vat_registration_required": true
                },
                "address": {
                    "postal_code_regex": "^[0-9]{5}$",
                    "format": "{{recipient}}\n{{street}} {{house}}\n{{postal}} {{city}}",
                    "required_fields": [
                        "street",
                        "postal",
                        "city"
                    ],
                    "state_required": true,
                    "phone": {
                        "mobile_prefix": [
                            "6",
                            "7"
                        ],
                        "area_code_required": true,
                        "example": "+34 600 123 456",
                        "regex": "^\\+34[6-7][0-9]{8}$"
                    }
                },
                "business": {
                    "working_days": [
                        "mon",
                        "tue",
                        "wed",
                        "thu",
                        "fri"
                    ],
                    "usual_hours": "09:00-18:00",
                    "bank_details": {
                        "iban_prefix": "ES",
                        "iban_length": 24,
                        "swift_format": "^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}[A-Z0-9]{11}$",
                        "local_format": "BBBBBBBBCCCCCCCCCCCC"
                    },
                    "payment_methods": {
                        "popular": [
                            "sepa",
                            "bizum",
                            "cards",
                            "paypal"
                        ],
                        "local": [
                            "bizum"
                        ]
                    }
                },
                "demographics": {
                    "population": 47351567,
                    "capital_population": 3233527,
                    "urbanization": 80.3,
                    "median_age": 45.3,
                    "languages": {
                        "official": [
                            "es"
                        ],
                        "business": [
                            "es",
                            "en"
                        ]
                    }
                },
                "geography": {
                    "neighbors": [
                        "PT",
                        "FR",
                        "AD",
                        "GI"
                    ],
                    "has_coast": true,
                    "climate_zone": "Mediterranean",
                    "timezone": {
                        "winter": "UTC+1",
                        "summer": "UTC+2",
                        "dst_start": "last Sunday March",
                        "dst_end": "last Sunday October"
                    },
                    "coordinates": {
                        "latitude": 40.4168,
                        "longitude": -3.7038
                    }
                },
                "holidays": {
                    "national_fixed": [
                        {
                            "date": "01-01",
                            "name": "Año Nuevo"
                        },
                        {
                            "date": "05-01",
                            "name": "Día del Trabajo"
                        },
                        {
                            "date": "10-12",
                            "name": "Día de la Hispanidad"
                        },
                        {
                            "date": "12-25",
                            "name": "Navidad"
                        }
                    ],
                    "national_floating": [
                        {
                            "name": "Viernes Santo",
                            "calc": "easter-2"
                        },
                        {
                            "name": "Lunes de Pascua",
                            "calc": "easter+1"
                        }
                    ],
                    "regional_specific": {
                        "AN": [
                            {
                                "date": "02-28",
                                "name": "Día de Andalucía"
                            }
                        ],
                        "CT": [
                            {
                                "date": "09-11",
                                "name": "Día de Cataluña"
                            }
                        ],
                        "MD": [
                            {
                                "date": "05-02",
                                "name": "Día de la Comunidad de Madrid"
                            }
                        ]
                    }
                },
                "document_validation": {
                    "tax_number": {
                        "format": "^[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                        "example": "A1234567B"
                    },
                    "vat_id": {
                        "format": "^ES[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                        "example": "ESA1234567B"
                    },
                    "id_card": {
                        "format": "^[0-9]{8}[A-Z]$",
                        "example": "12345678Z",
                        "valid_years": 10
                    },
                    "passport": {
                        "format": "^[A-Z0-9]{9}$",
                        "example": "X12345678",
                        "valid_years": 10
                    }
                },
                "ecommerce": {
                    "returns_period": 14,
                    "cancellation_period": 14,
                    "required_legal_texts": [
                        "imprint",
                        "privacy_policy",
                        "terms_conditions",
                        "cancellation_policy",
                        "shipping_info"
                    ],
                    "price_display": {
                        "must_include_vat": true,
                        "shipping_info_required": true,
                        "basic_price_required": true
                    },
                    "payment_deadline": {
                        "b2c": 14,
                        "b2b": 30
                    }
                },
                "important_contacts": {
                    "emergency": {
                        "general_emergency": "112",
                        "police": "091",
                        "fire_brigade": "080",
                        "ambulance": "061",
                        "poison_control": "+34 915 620 420",
                        "maritime_emergency": "+34 900 202 202",
                        "mountain_rescue": "112",
                        "gas_emergency": "+34 900 924 622",
                        "power_outage": "+34 900 500 049"
                    },
                    "health": {
                        "medical_on_call": "061",
                        "pharmacy_emergency": "N/A",
                        "mental_health_crisis": "+34 917 007 079",
                        "drug_addiction": "+34 900 161 515",
                        "aids_counseling": "+34 915 912 445",
                        "cancer_information": "+34 800 003 003"
                    },
                    "government": {
                        "tax_office_general": "+34 915 548 700",
                        "customs_info": "+34 915 506 400",
                        "federal_police": "+34 900 202 202",
                        "pension_service": "+34 901 166 565",
                        "employment_agency": "+34 900 801 137",
                        "social_security": "+34 901 502 050",
                        "immigration_office": "+34 902 008 210"
                    },
                    "consumer": {
                        "consumer_protection": "+34 915 326 320",
                        "data_protection": "dpd@agpd.es",
                        "banking_supervision": "+34 913 388 830",
                        "energy_advice": "+34 900 648 804",
                        "travel_security": "+34 915 205 948",
                        "food_safety": "+34 913 224 000"
                    },
                    "assistance": {
                        "roadside_assistance": {
                            "mapfre": "+34 918 366 160",
                            "axa": "+34 902 404 084"
                        },
                        "missing_persons": {
                            "hotline": "+34 116 000",
                            "children_emergency": "+34 116 111"
                        },
                        "violence": {
                            "domestic_violence": "+34 016",
                            "child_protection": "+34 116 111"
                        }
                    },
                    "fraud_prevention": {
                        "anti_fraud": "+34 902 007 290",
                        "credit_card_blocking": "+34 900 111 000",
                        "cyber_crime": "+34 915 822 640",
                        "identity_theft": "+34 900 202 202"
                    },
                    "transportation": {
                        "renfe": "+34 912 320 320",
                        "iberia": "+34 901 111 500",
                        "airport_barcelona": "+34 913 211 000",
                        "airport_madrid": "+34 913 936 000",
                        "public_transport_madrid": "+34 915 214 260"
                    },
                    "utilities": {
                        "telefonica_support": "+34 900 104 709",
                        "vodafone_support": "+34 123",
                        "orange_support": "+34 1470"
                    }
                },
                "iseumember": true
            }
        },
        "provider": {
            "as": "AS8708 RCS & RDS",
            "asname": "RCS-RDS",
            "isp": "RCS & RDS",
            "org": "RCS & RDS Residential"
        },
        "status": "success",
        "language": {
            "by_browser": false,
            "by_country": "es"
        },
        "locale": {
            "by_browser": false
        },
        "country_details": {
            "additional_data": "Extended country details loaded successfully"
        }
    },
    "processing_time": "49.18ms"
}
```

### Get IP full information

`POST https://api.paperoffice.ai/latest/ip2location/full`

Full IP Information Get complete IP geolocation and ISP data. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | ip | string | No | IP address default: caller's IP | Response: Location, ISP, timezone, currency, etc.

**Tool-ID:** `po_ip_geolocation_full_all_information` • **Cost:** 10 credits • **MCP:** `po_ip_geolocation_full_all_information` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | No | IP address to look up. If omitted, the callers IP is used. |
| `locale` | string | No | Response locale (en, de, fr, es, etc.) (default: "en") |

**Example Response:**

```json
{
    "device": {
        "browser": "Unknown browser",
        "browser_engine": "",
        "browser_major": "",
        "browser_version": "",
        "crawler": false,
        "device_brand": "",
        "device_model": "",
        "device_type": "desktop",
        "ismobiledevice": false,
        "istablet": false,
        "platform": "Unknown system",
        "platform_family": "",
        "platform_version": ""
    },
    "exchangecurrency": {
        "status": "success",
        "base": "EUR",
        "amount": 1,
        "rates": {
            "AED": 4.250249,
            "AFN": 74.069448,
            "ALL": 96.352918,
            "AMD": 436.507123,
            "ANG": 2.071697,
            "AOA": 1061.304016,
            "ARS": 1600.052522,
            "AUD": 1.673623,
            "AWG": 2.084746,
            "AZN": 1.967742,
            "BAM": 1.974414,
            "BBD": 2.32993,
            "BDT": 141.938183,
            "BGN": 1.978255,
            "BHD": 0.437005,
            "BIF": 3430.361516,
            "BMD": 1.157377,
            "BND": 1.493466,
            "BOB": 7.993201,
            "BRL": 6.011636,
            "BSD": 1.156765,
            "BTC": 1.7e-5,
            "BTN": 110.080925,
            "BWP": 15.958296,
            "BYN": 3.440099,
            "BYR": 22684.355744,
            "BZD": 2.326535,
            "CAD": 1.608991,
            "CDF": 2644.632229,
            "CHF": 0.92241,
            "CLF": 0.02716,
            "CLP": 1072.393732,
            "CNY": 7.970332,
            "CNH": 7.969186,
            "COP": 4263.289526,
            "CRC": 537.878733,
            "CUC": 1.157366,
            "CUP": 30.670481,
            "CVE": 110.964611,
            "CZK": 24.54743,
            "DJF": 205.688699,
            "DKK": 7.472517,
            "DOP": 69.554859,
            "DZD": 154.213888,
            "EGP": 63.166447,
            "ERN": 17.359782,
            "ETB": 181.76305,
            "EUR": 1,
            "FJD": 2.612685,
            "FKP": 0.877293,
            "GBP": 0.872981,
            "GEL": 3.112822,
            "GGP": 0.877345,
            "GHS": 12.731165,
            "GIP": 0.877319,
            "GMD": 85.644584,
            "GNF": 10155.676036,
            "GTQ": 8.851489,
            "GYD": 242.095907,
            "HKD": 9.071701,
            "HNL": 30.784511,
            "HRK": 7.536809,
            "HTG": 151.829937,
            "HUF": 384.136998,
            "IDR": 19669.986941,
            "ILS": 3.633648,
            "IMP": 0.877301,
            "INR": 108.483763,
            "IQD": 1516.163428,
            "IRR": 1522963.015607,
            "ISK": 143.403703,
            "JEP": 0.877337,
            "JMD": 183.017286,
            "JOD": 0.820532,
            "JPY": 183.795536,
            "KES": 150.452919,
            "KGS": 101.208215,
            "KHR": 4641.080265,
            "KMF": 495.929322,
            "KPW": 1041.557602,
            "KRW": 1743.791012,
            "KWD": 0.358375,
            "KYD": 0.963988,
            "KZT": 551.145238,
            "LAK": 25403.65515,
            "LBP": 103595.74929,
            "LKR": 364.945875,
            "LRD": 212.583302,
            "LSL": 19.755209,
            "LTL": 3.417261,
            "LVL": 0.700064,
            "LYD": 7.412969,
            "MAD": 10.812465,
            "MDL": 20.486947,
            "MGA": 4835.326,
            "MKD": 61.632007,
            "MMK": 2429.861488,
            "MNT": 4132.919666,
            "MOP": 9.340818,
            "MRU": 46.422499,
            "MUR": 54.153807,
            "MVR": 17.9035,
            "MWK": 2010.302466,
            "MXN": 20.703219,
            "MYR": 4.672723,
            "MZN": 74.012558,
            "NAD": 19.756839,
            "NGN": 1601.812149,
            "NIO": 42.510064,
            "NOK": 11.193989,
            "NPR": 176.129279,
            "NZD": 2.014072,
            "OMR": 0.445001,
            "PAB": 1.156818,
            "PEN": 4.046023,
            "PGK": 5.080892,
            "PHP": 69.811259,
            "PKR": 323.129693,
            "PLN": 4.287164,
            "PYG": 7493.64958,
            "QAR": 4.217378,
            "RON": 5.097753,
            "RSD": 117.410046,
            "RUB": 94.09203,
            "RWF": 1689.769928,
            "SAR": 4.343964,
            "SBD": 9.307573,
            "SCR": 17.111642,
            "SDG": 695.575845,
            "SEK": 10.928549,
            "SGD": 1.487803,
            "SHP": 0.868289,
            "SLE": 28.412382,
            "SLL": 24268.89438,
            "SOS": 661.428709,
            "SRD": 43.253661,
            "STD": 23954.881083,
            "STN": 25.143756,
            "SVC": 10.122376,
            "SYP": 127.950002,
            "SZL": 19.756668,
            "THB": 37.820975,
            "TJS": 11.087704,
            "TMT": 4.062352,
            "TND": 3.39101,
            "TOP": 2.786629,
            "TRY": 51.486888,
            "TTD": 7.859129,
            "TWD": 36.926984,
            "TZS": 2998.574199,
            "UAH": 50.822777,
            "UGX": 4354.903973,
            "USD": 1.157319,
            "UYU": 46.931537,
            "UZS": 14114.214677,
            "VES": 547.755261,
            "VND": 30485.301291,
            "VUV": 139.279792,
            "WST": 3.204996,
            "XAF": 662.173687,
            "XAG": 0.015511,
            "XAU": 0.000247,
            "XCD": 3.127899,
            "XCG": 2.084793,
            "XDR": 0.822848,
            "XOF": 660.279678,
            "XPF": 119.334129,
            "YER": 276.208455,
            "ZAR": 19.54026,
            "ZMK": 10417.880463,
            "ZMW": 22.111812,
            "ZWL": 372.671087
        },
        "timestamp": 1775654573
    },
    "fingerprint": {
        "device_id": "44256a8eadf880a0660a905910f03b4d",
        "confidence_score": 30,
        "trust_score": 100,
        "ip_location_used_by": "1 user",
        "total_visits": 1,
        "first_seen": "2 months ago",
        "last_seen": "just now",
        "known_device": true
    },
    "ip": {
        "ip": "203.0.113.42",
        "location": {
            "timezone": {
                "name": "Europe/Madrid",
                "offsethours": 1
            },
            "geo_lat": 40.4167,
            "geo_lon": -3.70329,
            "city": {
                "name": "Madrid",
                "zip": "28070",
                "district": ""
            },
            "region": {
                "code": "MD",
                "name": "Madrid"
            },
            "continent": {
                "name": "Europe",
                "code": "EU"
            },
            "country": {
                "name": "Spain",
                "code": "ES",
                "currency": "EUR",
                "primary_language": "es",
                "spoken_languages": [
                    "es",
                    "eu",
                    "ca",
                    "gl"
                ],
                "capital": "Madrid",
                "callingcode": "+34",
                "vat": {
                    "standard_rate": 21,
                    "reduced_rates": [
                        10,
                        4
                    ],
                    "prefix": "ES",
                    "regex": "^ES[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                    "digital_services_rate": 21,
                    "b2b_reverse_charge": true,
                    "tax_free_threshold": 0
                },
                "economy": {
                    "currency_details": {
                        "code": "EUR",
                        "symbol": "€",
                        "position": "after",
                        "decimal": ",",
                        "thousand": ".",
                        "decimals": 2
                    },
                    "economic_zones": [
                        "EU",
                        "EEA",
                        "SEPA",
                        "Schengen"
                    ],
                    "risk_rating": "A",
                    "gdp_per_capita": 28905.45
                },
                "legal": {
                    "legal_system": "Civil Law",
                    "data_protection": "GDPR",
                    "business_registration_required": true,
                    "electronic_signature": "eIDAS",
                    "age_of_majority": 18,
                    "vat_registration_required": true
                },
                "address": {
                    "postal_code_regex": "^[0-9]{5}$",
                    "format": "{{recipient}}\n{{street}} {{house}}\n{{postal}} {{city}}",
                    "required_fields": [
                        "street",
                        "postal",
                        "city"
                    ],
                    "state_required": true,
                    "phone": {
                        "mobile_prefix": [
                            "6",
                            "7"
                        ],
                        "area_code_required": true,
                        "example": "+34 600 123 456",
                        "regex": "^\\+34[6-7][0-9]{8}$"
                    }
                },
                "business": {
                    "working_days": [
                        "mon",
                        "tue",
                        "wed",
                        "thu",
                        "fri"
                    ],
                    "usual_hours": "09:00-18:00",
                    "bank_details": {
                        "iban_prefix": "ES",
                        "iban_length": 24,
                        "swift_format": "^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}[A-Z0-9]{11}$",
                        "local_format": "BBBBBBBBCCCCCCCCCCCC"
                    },
                    "payment_methods": {
                        "popular": [
                            "sepa",
                            "bizum",
                            "cards",
                            "paypal"
                        ],
                        "local": [
                            "bizum"
                        ]
                    }
                },
                "demographics": {
                    "population": 47351567,
                    "capital_population": 3233527,
                    "urbanization": 80.3,
                    "median_age": 45.3,
                    "languages": {
                        "official": [
                            "es"
                        ],
                        "business": [
                            "es",
                            "en"
                        ]
                    }
                },
                "geography": {
                    "neighbors": [
                        "PT",
                        "FR",
                        "AD",
                        "GI"
                    ],
                    "has_coast": true,
                    "climate_zone": "Mediterranean",
                    "timezone": {
                        "winter": "UTC+1",
                        "summer": "UTC+2",
                        "dst_start": "last Sunday March",
                        "dst_end": "last Sunday October"
                    },
                    "coordinates": {
                        "latitude": 40.4168,
                        "longitude": -3.7038
                    }
                },
                "holidays": {
                    "national_fixed": [
                        {
                            "date": "01-01",
                            "name": "Año Nuevo"
                        },
                        {
                            "date": "05-01",
                            "name": "Día del Trabajo"
                        },
                        {
                            "date": "10-12",
                            "name": "Día de la Hispanidad"
                        },
                        {
                            "date": "12-25",
                            "name": "Navidad"
                        }
                    ],
                    "national_floating": [
                        {
                            "name": "Viernes Santo",
                            "calc": "easter-2"
                        },
                        {
                            "name": "Lunes de Pascua",
                            "calc": "easter+1"
                        }
                    ],
                    "regional_specific": {
                        "AN": [
                            {
                                "date": "02-28",
                                "name": "Día de Andalucía"
                            }
                        ],
                        "CT": [
                            {
                                "date": "09-11",
                                "name": "Día de Cataluña"
                            }
                        ],
                        "MD": [
                            {
                                "date": "05-02",
                                "name": "Día de la Comunidad de Madrid"
                            }
                        ]
                    }
                },
                "document_validation": {
                    "tax_number": {
                        "format": "^[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                        "example": "A1234567B"
                    },
                    "vat_id": {
                        "format": "^ES[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                        "example": "ESA1234567B"
                    },
                    "id_card": {
                        "format": "^[0-9]{8}[A-Z]$",
                        "example": "12345678Z",
                        "valid_years": 10
                    },
                    "passport": {
                        "format": "^[A-Z0-9]{9}$",
                        "example": "X12345678",
                        "valid_years": 10
                    }
                },
                "ecommerce": {
                    "returns_period": 14,
                    "cancellation_period": 14,
                    "required_legal_texts": [
                        "imprint",
                        "privacy_policy",
                        "terms_conditions",
                        "cancellation_policy",
                        "shipping_info"
                    ],
                    "price_display": {
                        "must_include_vat": true,
                        "shipping_info_required": true,
                        "basic_price_required": true
                    },
                    "payment_deadline": {
                        "b2c": 14,
                        "b2b": 30
                    }
                },
                "important_contacts": {
                    "emergency": {
                        "general_emergency": "112",
                        "police": "091",
                        "fire_brigade": "080",
                        "ambulance": "061",
                        "poison_control": "+34 915 620 420",
                        "maritime_emergency": "+34 900 202 202",
                        "mountain_rescue": "112",
                        "gas_emergency": "+34 900 924 622",
                        "power_outage": "+34 900 500 049"
                    },
                    "health": {
                        "medical_on_call": "061",
                        "pharmacy_emergency": "N/A",
                        "mental_health_crisis": "+34 917 007 079",
                        "drug_addiction": "+34 900 161 515",
                        "aids_counseling": "+34 915 912 445",
                        "cancer_information": "+34 800 003 003"
                    },
                    "government": {
                        "tax_office_general": "+34 915 548 700",
                        "customs_info": "+34 915 506 400",
                        "federal_police": "+34 900 202 202",
                        "pension_service": "+34 901 166 565",
                        "employment_agency": "+34 900 801 137",
                        "social_security": "+34 901 502 050",
                        "immigration_office": "+34 902 008 210"
                    },
                    "consumer": {
                        "consumer_protection": "+34 915 326 320",
                        "data_protection": "dpd@agpd.es",
                        "banking_supervision": "+34 913 388 830",
                        "energy_advice": "+34 900 648 804",
                        "travel_security": "+34 915 205 948",
                        "food_safety": "+34 913 224 000"
                    },
                    "assistance": {
                        "roadside_assistance": {
                            "mapfre": "+34 918 366 160",
                            "axa": "+34 902 404 084"
                        },
                        "missing_persons": {
                            "hotline": "+34 116 000",
                            "children_emergency": "+34 116 111"
                        },
                        "violence": {
                            "domestic_violence": "+34 016",
                            "child_protection": "+34 116 111"
                        }
                    },
                    "fraud_prevention": {
                        "anti_fraud": "+34 902 007 290",
                        "credit_card_blocking": "+34 900 111 000",
                        "cyber_crime": "+34 915 822 640",
                        "identity_theft": "+34 900 202 202"
                    },
                    "transportation": {
                        "renfe": "+34 912 320 320",
                        "iberia": "+34 901 111 500",
                        "airport_barcelona": "+34 913 211 000",
                        "airport_madrid": "+34 913 936 000",
                        "public_transport_madrid": "+34 915 214 260"
                    },
                    "utilities": {
                        "telefonica_support": "+34 900 104 709",
                        "vodafone_support": "+34 123",
                        "orange_support": "+34 1470"
                    }
                },
                "iseumember": true
            }
        },
        "provider": {
            "as": "AS8708 RCS & RDS",
            "asname": "RCS-RDS",
            "isp": "RCS & RDS",
            "org": "RCS & RDS Residential"
        },
        "status": "success",
        "language": {
            "by_browser": false,
            "by_country": "es"
        },
        "locale": {
            "by_browser": false
        },
        "country_details": {
            "additional_data": "Extended country details loaded successfully"
        }
    },
    "processing_time": "6109.11ms",
    "vpn": {
        "is_vpn": false,
        "is_proxy": false,
        "is_relay": false,
        "is_datacenter": false,
        "is_tor": false,
        "score": "3.72%",
        "ip": "203.0.113.42",
        "last_paperofficeai_overseer_crawl": "2026-04-08 02:02:42"
    },
    "weather": {
        "status": "success",
        "location": {
            "name": "Madrid",
            "region": "Madrid",
            "country": "Spain",
            "lat": 40.4,
            "lon": -3.683,
            "timezone": "Europe/Madrid",
            "localtime": "2026-04-07 23:59"
        },
        "current": {
            "last_updated": "2026-04-07 23:45",
            "temp_c": 14.4,
            "temp_f": 57.9,
            "condition": {
                "text": "Partly cloudy",
                "icon": "02",
                "icon_url": "https://api.paperoffice.ai/v5/ip2location/weathericon_get?condition_code=1003",
                "code": 1003
            },
            "wind_mph": 13.6,
            "wind_kph": 22,
            "wind_degree": 281,
            "wind_dir": "W",
            "pressure_mb": 1019,
            "pressure_in": 30.09,
            "precip_mm": 1.87,
            "precip_in": 0.07,
            "humidity": 82,
            "cloud": 50,
            "feelslike_c": 12.8,
            "feelslike_f": 55,
            "vis_km": 10,
            "vis_miles": 6,
            "uv": 0,
            "gust_mph": 17.4,
            "gust_kph": 28
        },
        "precipitation": {
            "rain_hours": 96,
            "total_mm": 15.3,
            "max_probability": 98,
            "need_umbrella": true
        },
        "air_quality": {
            "co": 134.85,
            "no2": 16.95,
            "o3": 62,
            "so2": 3.15,
            "pm2_5": 15.35,
            "pm10": 34.65,
            "us_epa_index": 1,
            "gb_defra_index": 2
        },
        "forecast": [
            {
                "date": "2026-04-07",
                "date_epoch": 1775520000,
                "day": {
                    "maxtemp_c": 22.7,
                    "maxtemp_f": 72.9,
                    "mintemp_c": 12.2,
                    "mintemp_f": 53.9,
                    "avgtemp_c": 16.8,
                    "avgtemp_f": 62.2,
                    "maxwind_mph": 17.7,
                    "maxwind_kph": 28.4,
                    "totalprecip_mm": 6.22,
                    "totalprecip_in": 0.24,
                    "totalsnow_cm": 0,
                    "avgvis_km": 9.7,
                    "avgvis_miles": 6,
                    "avghumidity": 54,
                    "condition": {
                        "text": "Moderate rain",
                        "icon": "22",
                        "icon_url": "https://api.paperoffice.ai/v5/ip2location/weathericon_get?condition_code=1189",
                        "code": 1189
                    },
                    "uv": 1,
                    "daily_chance_of_rain": 98,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:49 AM",
                    "sunset": "08:45 PM",
                    "moonrise": "01:38 AM",
                    "moonset": "10:23 AM",
                    "moon_phase": "Waning Gibbous",
                    "moon_illumination": 79,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            },
            {
                "date": "2026-04-08",
                "date_epoch": 1775606400,
                "day": {
                    "maxtemp_c": 20.4,
                    "maxtemp_f": 68.7,
                    "mintemp_c": 11.6,
                    "mintemp_f": 52.9,
                    "avgtemp_c": 14.6,
                    "avgtemp_f": 58.2,
                    "maxwind_mph": 14.3,
                    "maxwind_kph": 23,
                    "totalprecip_mm": 0.98,
                    "totalprecip_in": 0.04,
                    "totalsnow_cm": 0,
                    "avgvis_km": 9.8,
                    "avgvis_miles": 6,
                    "avghumidity": 68,
                    "condition": {
                        "text": "Patchy rain nearby",
                        "icon": "06",
                        "icon_url": "https://api.paperoffice.ai/v5/ip2location/weathericon_get?condition_code=1063",
                        "code": 1063
                    },
                    "uv": 1.1,
                    "daily_chance_of_rain": 82,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:48 AM",
                    "sunset": "08:46 PM",
                    "moonrise": "02:34 AM",
                    "moonset": "11:12 AM",
                    "moon_phase": "Waning Gibbous",
                    "moon_illumination": 70,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            },
            {
                "date": "2026-04-09",
                "date_epoch": 1775692800,
                "day": {
                    "maxtemp_c": 26.5,
                    "maxtemp_f": 79.7,
                    "mintemp_c": 10.2,
                    "mintemp_f": 50.4,
                    "avgtemp_c": 17.5,
                    "avgtemp_f": 63.5,
                    "maxwind_mph": 16.6,
                    "maxwind_kph": 26.6,
                    "totalprecip_mm": 0,
                    "totalprecip_in": 0,
                    "totalsnow_cm": 0,
                    "avgvis_km": 10,
                    "avgvis_miles": 6,
                    "avghumidity": 48,
                    "condition": {
                        "text": "Sunny",
                        "icon": "01",
                        "icon_url": "https://api.paperoffice.ai/v5/ip2location/weathericon_get?condition_code=1000",
                        "code": 1000
                    },
                    "uv": 1.4,
                    "daily_chance_of_rain": 0,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:46 AM",
                    "sunset": "08:47 PM",
                    "moonrise": "03:23 AM",
                    "moonset": "12:08 PM",
                    "moon_phase": "Waning Gibbous",
                    "moon_illumination": 61,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            },
            {
                "date": "2026-04-10",
                "date_epoch": 1775779200,
                "day": {
                    "maxtemp_c": 25.7,
                    "maxtemp_f": 78.3,
                    "mintemp_c": 13.5,
                    "mintemp_f": 56.4,
                    "avgtemp_c": 19.2,
                    "avgtemp_f": 66.5,
                    "maxwind_mph": 12.3,
                    "maxwind_kph": 19.8,
                    "totalprecip_mm": 0,
                    "totalprecip_in": 0,
                    "totalsnow_cm": 0,
                    "avgvis_km": 10,
                    "avgvis_miles": 6,
                    "avghumidity": 34,
                    "condition": {
                        "text": "Sunny",
                        "icon": "01",
                        "icon_url": "https://api.paperoffice.ai/v5/ip2location/weathericon_get?condition_code=1000",
                        "code": 1000
                    },
                    "uv": 1.3,
                    "daily_chance_of_rain": 0,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:45 AM",
                    "sunset": "08:48 PM",
                    "moonrise": "04:05 AM",
                    "moonset": "01:10 PM",
                    "moon_phase": "Last Quarter",
                    "moon_illumination": 52,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            },
            {
                "date": "2026-04-11",
                "date_epoch": 1775865600,
                "day": {
                    "maxtemp_c": 17,
                    "maxtemp_f": 62.6,
                    "mintemp_c": 9.6,
                    "mintemp_f": 49.3,
                    "avgtemp_c": 14.5,
                    "avgtemp_f": 58,
                    "maxwind_mph": 17.7,
                    "maxwind_kph": 28.4,
                    "totalprecip_mm": 5.55,
                    "totalprecip_in": 0.22,
                    "totalsnow_cm": 0,
                    "avgvis_km": 8.2,
                    "avgvis_miles": 5,
                    "avghumidity": 65,
                    "condition": {
                        "text": "Moderate rain",
                        "icon": "22",
                        "icon_url": "https://api.paperoffice.ai/v5/ip2location/weathericon_get?condition_code=1189",
                        "code": 1189
                    },
                    "uv": 0.5,
                    "daily_chance_of_rain": 87,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:43 AM",
                    "sunset": "08:49 PM",
                    "moonrise": "04:40 AM",
                    "moonset": "02:15 PM",
                    "moon_phase": "Waning Crescent",
                    "moon_illumination": 42,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            },
            {
                "date": "2026-04-12",
                "date_epoch": 1775952000,
                "day": {
                    "maxtemp_c": 14.3,
                    "maxtemp_f": 57.8,
                    "mintemp_c": 6.1,
                    "mintemp_f": 43,
                    "avgtemp_c": 8.6,
                    "avgtemp_f": 47.4,
                    "maxwind_mph": 17,
                    "maxwind_kph": 27.4,
                    "totalprecip_mm": 2.55,
                    "totalprecip_in": 0.1,
                    "totalsnow_cm": 0,
                    "avgvis_km": 8.3,
                    "avgvis_miles": 5,
                    "avghumidity": 64,
                    "condition": {
                        "text": "Patchy rain nearby",
                        "icon": "06",
                        "icon_url": "https://api.paperoffice.ai/v5/ip2location/weathericon_get?condition_code=1063",
                        "code": 1063
                    },
                    "uv": 1.2,
                    "daily_chance_of_rain": 80,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:41 AM",
                    "sunset": "08:50 PM",
                    "moonrise": "05:10 AM",
                    "moonset": "03:22 PM",
                    "moon_phase": "Waning Crescent",
                    "moon_illumination": 33,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            },
            {
                "date": "2026-04-13",
                "date_epoch": 1776038400,
                "day": {
                    "maxtemp_c": 17.2,
                    "maxtemp_f": 63,
                    "mintemp_c": 3.7,
                    "mintemp_f": 38.6,
                    "avgtemp_c": 10.2,
                    "avgtemp_f": 50.4,
                    "maxwind_mph": 6.3,
                    "maxwind_kph": 10.1,
                    "totalprecip_mm": 0,
                    "totalprecip_in": 0,
                    "totalsnow_cm": 0,
                    "avgvis_km": 10,
                    "avgvis_miles": 6,
                    "avghumidity": 42,
                    "condition": {
                        "text": "Sunny",
                        "icon": "01",
                        "icon_url": "https://api.paperoffice.ai/v5/ip2location/weathericon_get?condition_code=1000",
                        "code": 1000
                    },
                    "uv": 4,
                    "daily_chance_of_rain": 0,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:40 AM",
                    "sunset": "08:52 PM",
                    "moonrise": "05:36 AM",
                    "moonset": "04:30 PM",
                    "moon_phase": "Waning Crescent",
                    "moon_illumination": 23,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            }
        ]
    }
}
```

### Get IP location only

`POST https://api.paperoffice.ai/latest/ip2location/location`

IP Location Only Get basic location data for an IP. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | ip | string | No | IP address default: caller's IP | Response: Country, city, coordinates

**Tool-ID:** `po_ip_geolocation_location` • **Cost:** 10 credits • **MCP:** `po_ip_geolocation_location` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | No | Query parameter: ip |

**Example Response:**

```json
{
    "ip": {
        "ip": "203.0.113.42",
        "location": {
            "timezone": {
                "name": "Europe/Madrid",
                "offsethours": 1
            },
            "geo_lat": 40.4167,
            "geo_lon": -3.70329,
            "city": {
                "name": "Madrid",
                "zip": "28070",
                "district": ""
            },
            "region": {
                "code": "MD",
                "name": "Madrid"
            },
            "continent": {
                "name": "Europe",
                "code": "EU"
            },
            "country": {
                "name": "Spain",
                "code": "ES",
                "currency": "EUR",
                "primary_language": "es",
                "spoken_languages": [
                    "es",
                    "eu",
                    "ca",
                    "gl"
                ],
                "capital": "Madrid",
                "callingcode": "+34",
                "vat": {
                    "standard_rate": 21,
                    "reduced_rates": [
                        10,
                        4
                    ],
                    "prefix": "ES",
                    "regex": "^ES[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                    "digital_services_rate": 21,
                    "b2b_reverse_charge": true,
                    "tax_free_threshold": 0
                },
                "economy": {
                    "currency_details": {
                        "code": "EUR",
                        "symbol": "€",
                        "position": "after",
                        "decimal": ",",
                        "thousand": ".",
                        "decimals": 2
                    },
                    "economic_zones": [
                        "EU",
                        "EEA",
                        "SEPA",
                        "Schengen"
                    ],
                    "risk_rating": "A",
                    "gdp_per_capita": 28905.45
                },
                "legal": {
                    "legal_system": "Civil Law",
                    "data_protection": "GDPR",
                    "business_registration_required": true,
                    "electronic_signature": "eIDAS",
                    "age_of_majority": 18,
                    "vat_registration_required": true
                },
                "address": {
                    "postal_code_regex": "^[0-9]{5}$",
                    "format": "{{recipient}}\n{{street}} {{house}}\n{{postal}} {{city}}",
                    "required_fields": [
                        "street",
                        "postal",
                        "city"
                    ],
                    "state_required": true,
                    "phone": {
                        "mobile_prefix": [
                            "6",
                            "7"
                        ],
                        "area_code_required": true,
                        "example": "+34 600 123 456",
                        "regex": "^\\+34[6-7][0-9]{8}$"
                    }
                },
                "business": {
                    "working_days": [
                        "mon",
                        "tue",
                        "wed",
                        "thu",
                        "fri"
                    ],
                    "usual_hours": "09:00-18:00",
                    "bank_details": {
                        "iban_prefix": "ES",
                        "iban_length": 24,
                        "swift_format": "^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}[A-Z0-9]{11}$",
                        "local_format": "BBBBBBBBCCCCCCCCCCCC"
                    },
                    "payment_methods": {
                        "popular": [
                            "sepa",
                            "bizum",
                            "cards",
                            "paypal"
                        ],
                        "local": [
                            "bizum"
                        ]
                    }
                },
                "demographics": {
                    "population": 47351567,
                    "capital_population": 3233527,
                    "urbanization": 80.3,
                    "median_age": 45.3,
                    "languages": {
                        "official": [
                            "es"
                        ],
                        "business": [
                            "es",
                            "en"
                        ]
                    }
                },
                "geography": {
                    "neighbors": [
                        "PT",
                        "FR",
                        "AD",
                        "GI"
                    ],
                    "has_coast": true,
                    "climate_zone": "Mediterranean",
                    "timezone": {
                        "winter": "UTC+1",
                        "summer": "UTC+2",
                        "dst_start": "last Sunday March",
                        "dst_end": "last Sunday October"
                    },
                    "coordinates": {
                        "latitude": 40.4168,
                        "longitude": -3.7038
                    }
                },
                "holidays": {
                    "national_fixed": [
                        {
                            "date": "01-01",
                            "name": "Año Nuevo"
                        },
                        {
                            "date": "05-01",
                            "name": "Día del Trabajo"
                        },
                        {
                            "date": "10-12",
                            "name": "Día de la Hispanidad"
                        },
                        {
                            "date": "12-25",
                            "name": "Navidad"
                        }
                    ],
                    "national_floating": [
                        {
                            "name": "Viernes Santo",
                            "calc": "easter-2"
                        },
                        {
                            "name": "Lunes de Pascua",
                            "calc": "easter+1"
                        }
                    ],
                    "regional_specific": {
                        "AN": [
                            {
                                "date": "02-28",
                                "name": "Día de Andalucía"
                            }
                        ],
                        "CT": [
                            {
                                "date": "09-11",
                                "name": "Día de Cataluña"
                            }
                        ],
                        "MD": [
                            {
                                "date": "05-02",
                                "name": "Día de la Comunidad de Madrid"
                            }
                        ]
                    }
                },
                "document_validation": {
                    "tax_number": {
                        "format": "^[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                        "example": "A1234567B"
                    },
                    "vat_id": {
                        "format": "^ES[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                        "example": "ESA1234567B"
                    },
                    "id_card": {
                        "format": "^[0-9]{8}[A-Z]$",
                        "example": "12345678Z",
                        "valid_years": 10
                    },
                    "passport": {
                        "format": "^[A-Z0-9]{9}$",
                        "example": "X12345678",
                        "valid_years": 10
                    }
                },
                "ecommerce": {
                    "returns_period": 14,
                    "cancellation_period": 14,
                    "required_legal_texts": [
                        "imprint",
                        "privacy_policy",
                        "terms_conditions",
                        "cancellation_policy",
                        "shipping_info"
                    ],
                    "price_display": {
                        "must_include_vat": true,
                        "shipping_info_required": true,
                        "basic_price_required": true
                    },
                    "payment_deadline": {
                        "b2c": 14,
                        "b2b": 30
                    }
                },
                "important_contacts": {
                    "emergency": {
                        "general_emergency": "112",
                        "police": "091",
                        "fire_brigade": "080",
                        "ambulance": "061",
                        "poison_control": "+34 915 620 420",
                        "maritime_emergency": "+34 900 202 202",
                        "mountain_rescue": "112",
                        "gas_emergency": "+34 900 924 622",
                        "power_outage": "+34 900 500 049"
                    },
                    "health": {
                        "medical_on_call": "061",
                        "pharmacy_emergency": "N/A",
                        "mental_health_crisis": "+34 917 007 079",
                        "drug_addiction": "+34 900 161 515",
                        "aids_counseling": "+34 915 912 445",
                        "cancer_information": "+34 800 003 003"
                    },
                    "government": {
                        "tax_office_general": "+34 915 548 700",
                        "customs_info": "+34 915 506 400",
                        "federal_police": "+34 900 202 202",
                        "pension_service": "+34 901 166 565",
                        "employment_agency": "+34 900 801 137",
                        "social_security": "+34 901 502 050",
                        "immigration_office": "+34 902 008 210"
                    },
                    "consumer": {
                        "consumer_protection": "+34 915 326 320",
                        "data_protection": "dpd@agpd.es",
                        "banking_supervision": "+34 913 388 830",
                        "energy_advice": "+34 900 648 804",
                        "travel_security": "+34 915 205 948",
                        "food_safety": "+34 913 224 000"
                    },
                    "assistance": {
                        "roadside_assistance": {
                            "mapfre": "+34 918 366 160",
                            "axa": "+34 902 404 084"
                        },
                        "missing_persons": {
                            "hotline": "+34 116 000",
                            "children_emergency": "+34 116 111"
                        },
                        "violence": {
                            "domestic_violence": "+34 016",
                            "child_protection": "+34 116 111"
                        }
                    },
                    "fraud_prevention": {
                        "anti_fraud": "+34 902 007 290",
                        "credit_card_blocking": "+34 900 111 000",
                        "cyber_crime": "+34 915 822 640",
                        "identity_theft": "+34 900 202 202"
                    },
                    "transportation": {
                        "renfe": "+34 912 320 320",
                        "iberia": "+34 901 111 500",
                        "airport_barcelona": "+34 913 211 000",
                        "airport_madrid": "+34 913 936 000",
                        "public_transport_madrid": "+34 915 214 260"
                    },
                    "utilities": {
                        "telefonica_support": "+34 900 104 709",
                        "vodafone_support": "+34 123",
                        "orange_support": "+34 1470"
                    }
                },
                "iseumember": true
            }
        },
        "provider": {
            "as": "AS8708 RCS & RDS",
            "asname": "RCS-RDS",
            "isp": "RCS & RDS",
            "org": "RCS & RDS Residential"
        },
        "status": "success",
        "language": {
            "by_browser": false,
            "by_country": "es"
        },
        "locale": {
            "by_browser": false
        },
        "country_details": {
            "additional_data": "Extended country details loaded successfully"
        }
    },
    "processing_time": "11.02ms"
}
```

### List IP countries

`POST https://api.paperoffice.ai/latest/ip2location/countrylist`

Get list of all supported countries with basic info. Returns: - Country codes ISO 2-letter - Country names - Currency codes - Primary languages

**Tool-ID:** `po_ip_geolocation_country_list` • **Cost:** 10 credits • **MCP:** `po_ip_geolocation_country_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `language` | string | No | language the Laenthenamen (e.g. 'de', 'en', 'fr'). (default: "en") |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "ip2location___countrylist",
        "app": "ip2location",
        "action": "countrylist",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "6.01ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

---

## Data AI — Map Tiles

### Get map tile

`GET https://api.paperoffice.ai/latest/maptiles/tiles/get/{z}/{x}/{y}.pbf`

Get a vector map tile. Path parameters: - {z} - Zoom level 0-14, higher = more detail - {x} - Tile X coordinate - {y} - Tile Y coordinate Returns: Mapbox Vector Tile .pbf Example: Zoom 14, Berlin area → /tiles/14/8529/5458.pbf

**Tool-ID:** `po_map_tiles_get_map_tile` • **Cost:** 10 credits • **MCP:** `po_map_tiles_get_map_tile` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `lat` | number | No | Breitengrad (Latitude). |
| `lon` | number | No | Laengengrad (Longitude). |
| `ip` | string | No | IP address for automatic location determination (Alternative to lat/lon). |
| `zoom` | integer | No | Zoom-level the Karte (1-18). (default: 12) |
| `width` | integer | No | Breite the Bilthe in Pixeln. (default: 280) |
| `height` | integer | No | Hoehe the Bilthe in Pixeln. (default: 200) |
| `marker` | integer | No | Standort-Marker display (1) or not (0). (allowed: 0, 1) (default: 1) |

**Example Response:**

```json
{
    "processing_time": "example",
    "content_type": "application/pdf",
    "body": "example",
    "status": "success"
}
```

### Get static map by coordinates

`POST https://api.paperoffice.ai/latest/maptiles/staticmap`

Generate a static map image from coordinates. Returns: PNG image or JSON Parameters: - lat/lon - Coordinates - zoom - 1-16 default: 12 - width/height - Image size - marker - Show red marker 0/1 - format - image, json, base64 Use Cases: - Embed maps in emails - Location previews

**Tool-ID:** `po_map_tiles_static_map_coordinates` • **Cost:** 10 credits • **MCP:** `po_map_tiles_static_map_coordinates` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `lat` | number | No | Latitude |
| `lon` | number | No | Longitude |
| `zoom` | number | No | Zoom level (1-16) |
| `width` | number | No | Image width (100-800) |
| `height` | number | No | Image height (50-600) |
| `marker` | string | No | Show marker (0/1) |

**Example Response:**

```json
{
    "processing_time": "example",
    "content_type": "application/pdf",
    "image_url": "https://example.com/resource",
    "status": "success"
}
```

### Get static map by IP address

`POST https://api.paperoffice.ai/latest/maptiles/staticmap`

Generate a static map from an IP address. Combines IP2Location + Static Map Returns: - Map image or JSON with location data - City, region, country info Perfect for: - Security emails - Login location display

**Tool-ID:** `po_map_tiles_static_map_ip_address` • **Cost:** 10 credits • **MCP:** `po_map_tiles_static_map_ip_address` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | No | IP address to locate |
| `zoom` | number | No | Zoom level |
| `width` | number | No | Image width |
| `height` | number | No | Image height |

**Example Response:**

```json
{
    "processing_time": "example",
    "content_type": "application/pdf",
    "image_url": "https://example.com/resource",
    "status": "success"
}
```

---

## Data AI — Validation & VAT

### Validate All (Email + Phone + Website)

`POST https://api.paperoffice.ai/latest/validate/all`

Validate All (Email + Phone + Website)\n\nRun all validations at once: email, phone, and website. Only provided fields are validated. Returns combined results with individual risk scores.\n\n--- Parameters\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| email | string | No | Email address to validate |\n| phone | string | No | Phone number to validate |\n| url | string | No | Website URL to validate |

**Tool-ID:** `po_validate_all` • **Cost:** 20 credits • **MCP:** `po_validate_all` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | No | Email address to validate |
| `phone` | string | No | Phone number to validate |
| `url` | string | No | Website URL to validate |
| `website` | string | No | Website |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "results": [],
    "all_valid": true,
    "status": {
        "code": 200,
        "message": "ALL_VALID",
        "success": true
    },
    "processing_time": "1,773,928,304,997.64ms"
}
```

### Validate Email Address

`POST https://api.paperoffice.ai/latest/validate/email`

Validate Email Address\n\nCheck if an email address is valid, fake, disposable, or temporary. Uses format validation, DNS/MX record checks, and the PaperOffice Fake Email Detector database.\n\n--- Parameters\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| email | string | Yes | Email address to validate |

**Tool-ID:** `po_validate_email` • **Cost:** 10 credits • **MCP:** `po_validate_email` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | Yes | Email address to validate |

**Example Response:**

```json
{
    "result": {
        "email": "test",
        "valid": false,
        "is_fake": true,
        "risk_score": 100,
        "risk_level": "CRITICAL",
        "detection_method": "INVALID_FORMAT",
        "recommendation": "REJECT"
    },
    "status": {
        "code": 200,
        "message": "EMAIL_INVALID_FORMAT",
        "success": true
    },
    "processing_time": "1,773,928,305,151.46ms"
}
```

### Validate Phone Number

`POST https://api.paperoffice.ai/latest/validate/phone`

Validate Phone Number\n\nValidate a phone number format, detect country, carrier type (mobile/landline), and check if it is a valid number.\n\n--- Parameters\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| phone | string | Yes | Phone number to validate (with or without country code) |

**Tool-ID:** `po_validate_phone` • **Cost:** 10 credits • **MCP:** `po_validate_phone` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `phone` | string | Yes | Phone number to validate (with or without country code, e.g. +49171123456) |

**Example Response:**

```json
{
    "result": {
        "valid": false,
        "original": "test",
        "cleaned": "",
        "digits_only": "",
        "country_code": null,
        "format": null,
        "error": "TOO_SHORT"
    },
    "status": {
        "code": 200,
        "message": "PHONE_INVALID",
        "success": true
    },
    "processing_time": "1,773,928,305,332.64ms"
}
```

### Validate Website URL

`POST https://api.paperoffice.ai/latest/validate/website`

Validate Website URL\n\nComprehensive website validation including DNS resolution, HTTP reachability, SSL certificate check, redirect analysis, and risk scoring.\n\n--- Parameters\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| url | string | Yes | Website URL to validate |

**Tool-ID:** `po_validate_website` • **Cost:** 10 credits • **MCP:** `po_validate_website` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `url` | string | Yes | Website URL to validate (e.g. https://example.com) |

**Example Response:**

```json
{
    "result": {
        "url": "test",
        "valid": false,
        "risk_level": "CRITICAL",
        "recommendation": "REJECT",
        "checks": {
            "format": {
                "passed": false,
                "error": "Invalid domain format"
            }
        }
    },
    "status": {
        "code": 200,
        "message": "URL_INVALID_FORMAT",
        "success": true
    },
    "processing_time": "1,773,928,305,525.51ms"
}
```

### Get EU VAT Rates

`GET https://api.paperoffice.ai/latest/vat/rates`

Get EU VAT Rates\n\nReturns current VAT rates for all 27 EU member states including standard and reduced rates.\n\n--- Parameters\nNo parameters required.

**Tool-ID:** `po_vat_rates_get` • **Cost:** 10 credits • **MCP:** `po_vat_rates_get` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "status": "success",
    "rates": {
        "AT": {
            "standard": 20,
            "reduced": 10
        },
        "BE": {
            "standard": 21,
            "reduced": 6
        },
        "BG": {
            "standard": 20,
            "reduced": 9
        },
        "CY": {
            "standard": 19,
            "reduced": 5
        },
        "CZ": {
            "standard": 21,
            "reduced": 12
        },
        "DE": {
            "standard": 19,
            "reduced": 7
        },
        "DK": {
            "standard": 25,
            "reduced": 0
        },
        "EE": {
            "standard": 22,
            "reduced": 9
        },
        "EL": {
            "standard": 24,
            "reduced": 6
        },
        "ES": {
            "standard": 21,
            "reduced": 10
        },
        "FI": {
            "standard": 25.5,
            "reduced": 10
        },
        "FR": {
            "standard": 20,
            "reduced": 5.5
        },
        "HR": {
            "standard": 25,
            "reduced": 5
        },
        "HU": {
            "standard": 27,
            "reduced": 5
        },
        "IE": {
            "standard": 23,
            "reduced": 9
        },
        "IT": {
            "standard": 22,
            "reduced": 5
        },
        "LT": {
            "standard": 21,
            "reduced": 5
        },
        "LU": {
            "standard": 17,
            "reduced": 8
        },
        "LV": {
            "standard": 21,
            "reduced": 12
        },
        "MT": {
            "standard": 18,
            "reduced": 5
        },
        "NL": {
            "standard": 21,
            "reduced": 9
        },
        "PL": {
            "standard": 23,
            "reduced": 8
        },
        "PT": {
            "standard": 23,
            "reduced": 6
        },
        "RO": {
            "standard": 19,
            "reduced": 5
        },
        "SE": {
            "standard": 25,
            "reduced": 6
        },
        "SI": {
            "standard": 22,
            "reduced": 9.5
        },
        "SK": {
            "standard": 23,
            "reduced": 10
        }
    },
    "count": 27
}
```

### Validate EU VAT ID

`POST https://api.paperoffice.ai/latest/vat/validate`

Validate EU VAT ID\n\nValidate a European VAT identification number against the EU VIES database. Returns company name, address, validity status, tax context (VAT rates), and optional fraud risk assessment.\n\n--- Parameters\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| vat_id | string | Yes | EU VAT ID (e.g. DE123456789, FR12345678901, NL123456789B01) |\n| ip | string | No | IP for fraud cross-check |\n| email | string | No | Email for fraud cross-check |

**Tool-ID:** `po_vat_validate` • **Cost:** 10 credits • **MCP:** `po_vat_validate` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `vat_id` | string | Yes | EU VAT identification number (e.g. DE123456789, FR12345678901) |
| `ip` | string | No | IP address for fraud cross-check (optional) |
| `email` | string | No | Email for fraud cross-check (optional) |
| `force_recheck` | boolean | No | Force recheck |
| `geocoding` | string | No | Geocoding |
| `vat_ids` | array | No | Vat ids |

**Example Response:**

```json
{
    "status": "success",
    "vat_id": "example",
    "format_valid": true,
    "error": "example",
    "message": "Operation completed successfully",
    "layer": "example",
    "processing_time_ms": 150,
    "processing_time": "example",
    "count": "example",
    "results": "example"
}
```

---

## Data AI — Weather

### Get weather by city

`POST https://api.paperoffice.ai/latest/location2weather`

Weather by City Get current weather and 7-day forecast for any city worldwide. --- When to Use - Display weather for a specific city - Travel planning - Weather widgets --- Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | city | string | ✅.

**Tool-ID:** `po_weather_by_city` • **Cost:** 10 credits • **MCP:** `po_weather_by_city` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `city` | string | No | City name (e.g. Berlin, Munich, New York) |
| `locale` | string | No | Language for weather descriptions |

**Example Response:**

```json
{
    "processing_time": "example",
    "temperature": 1,
    "humidity": 1,
    "description": "example",
    "wind_speed": 1,
    "icon": "example",
    "status": "success"
}
```

### Get weather by coordinates

`POST https://api.paperoffice.ai/latest/location2weather`

Weather by Coordinates Get weather for specific coordinates. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | lat | float | Yes | Latitude | | lon | float | Yes | Longitude | Response: Current weather conditions

**Tool-ID:** `po_weather_by_coordinates` • **Cost:** 10 credits • **MCP:** `po_weather_by_coordinates` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `lat` | number | No | Latitude (e.g. 52.52 for Berlin) |
| `lon` | number | No | Longitude (e.g. 13.405 for Berlin) |
| `lang` | string | No | Response language (e.g. de, en) |

**Example Response:**

```json
{
    "processing_time": "example",
    "temperature": 1,
    "humidity": 1,
    "description": "example",
    "wind_speed": 1,
    "icon": "example",
    "status": "success"
}
```

### Get weather by IP

`POST https://api.paperoffice.ai/latest/ip2location/weather`

Weather by IP Get weather for IP-based location. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | ip | string | No | IP address default: caller's IP | Response: Current weather conditions

**Tool-ID:** `po_weather_by_ip` • **Cost:** 10 credits • **MCP:** `po_weather_by_ip` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `locale` | string | No | Query parameter: locale |

**Example Response:**

```json
{
    "ip": {
        "ip": "203.0.113.42",
        "location": {
            "timezone": {
                "name": "Europe/Madrid",
                "offsethours": 1
            },
            "geo_lat": 40.4167,
            "geo_lon": -3.70329,
            "city": {
                "name": "Madrid",
                "zip": "28070",
                "district": ""
            },
            "region": {
                "code": "MD",
                "name": "Madrid"
            },
            "continent": {
                "name": "Europe",
                "code": "EU"
            },
            "country": {
                "name": "Spain",
                "code": "ES",
                "currency": "EUR",
                "primary_language": "es",
                "spoken_languages": [
                    "es",
                    "eu",
                    "ca",
                    "gl"
                ],
                "capital": "Madrid",
                "callingcode": "+34",
                "vat": {
                    "standard_rate": 21,
                    "reduced_rates": [
                        10,
                        4
                    ],
                    "prefix": "ES",
                    "regex": "^ES[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                    "digital_services_rate": 21,
                    "b2b_reverse_charge": true,
                    "tax_free_threshold": 0
                },
                "economy": {
                    "currency_details": {
                        "code": "EUR",
                        "symbol": "€",
                        "position": "after",
                        "decimal": ",",
                        "thousand": ".",
                        "decimals": 2
                    },
                    "economic_zones": [
                        "EU",
                        "EEA",
                        "SEPA",
                        "Schengen"
                    ],
                    "risk_rating": "A",
                    "gdp_per_capita": 28905.45
                },
                "legal": {
                    "legal_system": "Civil Law",
                    "data_protection": "GDPR",
                    "business_registration_required": true,
                    "electronic_signature": "eIDAS",
                    "age_of_majority": 18,
                    "vat_registration_required": true
                },
                "address": {
                    "postal_code_regex": "^[0-9]{5}$",
                    "format": "{{recipient}}\n{{street}} {{house}}\n{{postal}} {{city}}",
                    "required_fields": [
                        "street",
                        "postal",
                        "city"
                    ],
                    "state_required": true,
                    "phone": {
                        "mobile_prefix": [
                            "6",
                            "7"
                        ],
                        "area_code_required": true,
                        "example": "+34 600 123 456",
                        "regex": "^\\+34[6-7][0-9]{8}$"
                    }
                },
                "business": {
                    "working_days": [
                        "mon",
                        "tue",
                        "wed",
                        "thu",
                        "fri"
                    ],
                    "usual_hours": "09:00-18:00",
                    "bank_details": {
                        "iban_prefix": "ES",
                        "iban_length": 24,
                        "swift_format": "^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}[A-Z0-9]{11}$",
                        "local_format": "BBBBBBBBCCCCCCCCCCCC"
                    },
                    "payment_methods": {
                        "popular": [
                            "sepa",
                            "bizum",
                            "cards",
                            "paypal"
                        ],
                        "local": [
                            "bizum"
                        ]
                    }
                },
                "demographics": {
                    "population": 47351567,
                    "capital_population": 3233527,
                    "urbanization": 80.3,
                    "median_age": 45.3,
                    "languages": {
                        "official": [
                            "es"
                        ],
                        "business": [
                            "es",
                            "en"
                        ]
                    }
                },
                "geography": {
                    "neighbors": [
                        "PT",
                        "FR",
                        "AD",
                        "GI"
                    ],
                    "has_coast": true,
                    "climate_zone": "Mediterranean",
                    "timezone": {
                        "winter": "UTC+1",
                        "summer": "UTC+2",
                        "dst_start": "last Sunday March",
                        "dst_end": "last Sunday October"
                    },
                    "coordinates": {
                        "latitude": 40.4168,
                        "longitude": -3.7038
                    }
                },
                "holidays": {
                    "national_fixed": [
                        {
                            "date": "01-01",
                            "name": "Año Nuevo"
                        },
                        {
                            "date": "05-01",
                            "name": "Día del Trabajo"
                        },
                        {
                            "date": "10-12",
                            "name": "Día de la Hispanidad"
                        },
                        {
                            "date": "12-25",
                            "name": "Navidad"
                        }
                    ],
                    "national_floating": [
                        {
                            "name": "Viernes Santo",
                            "calc": "easter-2"
                        },
                        {
                            "name": "Lunes de Pascua",
                            "calc": "easter+1"
                        }
                    ],
                    "regional_specific": {
                        "AN": [
                            {
                                "date": "02-28",
                                "name": "Día de Andalucía"
                            }
                        ],
                        "CT": [
                            {
                                "date": "09-11",
                                "name": "Día de Cataluña"
                            }
                        ],
                        "MD": [
                            {
                                "date": "05-02",
                                "name": "Día de la Comunidad de Madrid"
                            }
                        ]
                    }
                },
                "document_validation": {
                    "tax_number": {
                        "format": "^[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                        "example": "A1234567B"
                    },
                    "vat_id": {
                        "format": "^ES[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                        "example": "ESA1234567B"
                    },
                    "id_card": {
                        "format": "^[0-9]{8}[A-Z]$",
                        "example": "12345678Z",
                        "valid_years": 10
                    },
                    "passport": {
                        "format": "^[A-Z0-9]{9}$",
                        "example": "X12345678",
                        "valid_years": 10
                    }
                },
                "ecommerce": {
                    "returns_period": 14,
                    "cancellation_period": 14,
                    "required_legal_texts": [
                        "imprint",
                        "privacy_policy",
                        "terms_conditions",
                        "cancellation_policy",
                        "shipping_info"
                    ],
                    "price_display": {
                        "must_include_vat": true,
                        "shipping_info_required": true,
                        "basic_price_required": true
                    },
                    "payment_deadline": {
                        "b2c": 14,
                        "b2b": 30
                    }
                },
                "important_contacts": {
                    "emergency": {
                        "general_emergency": "112",
                        "police": "091",
                        "fire_brigade": "080",
                        "ambulance": "061",
                        "poison_control": "+34 915 620 420",
                        "maritime_emergency": "+34 900 202 202",
                        "mountain_rescue": "112",
                        "gas_emergency": "+34 900 924 622",
                        "power_outage": "+34 900 500 049"
                    },
                    "health": {
                        "medical_on_call": "061",
                        "pharmacy_emergency": "N/A",
                        "mental_health_crisis": "+34 917 007 079",
                        "drug_addiction": "+34 900 161 515",
                        "aids_counseling": "+34 915 912 445",
                        "cancer_information": "+34 800 003 003"
                    },
                    "government": {
                        "tax_office_general": "+34 915 548 700",
                        "customs_info": "+34 915 506 400",
                        "federal_police": "+34 900 202 202",
                        "pension_service": "+34 901 166 565",
                        "employment_agency": "+34 900 801 137",
                        "social_security": "+34 901 502 050",
                        "immigration_office": "+34 902 008 210"
                    },
                    "consumer": {
                        "consumer_protection": "+34 915 326 320",
                        "data_protection": "dpd@agpd.es",
                        "banking_supervision": "+34 913 388 830",
                        "energy_advice": "+34 900 648 804",
                        "travel_security": "+34 915 205 948",
                        "food_safety": "+34 913 224 000"
                    },
                    "assistance": {
                        "roadside_assistance": {
                            "mapfre": "+34 918 366 160",
                            "axa": "+34 902 404 084"
                        },
                        "missing_persons": {
                            "hotline": "+34 116 000",
                            "children_emergency": "+34 116 111"
                        },
                        "violence": {
                            "domestic_violence": "+34 016",
                            "child_protection": "+34 116 111"
                        }
                    },
                    "fraud_prevention": {
                        "anti_fraud": "+34 902 007 290",
                        "credit_card_blocking": "+34 900 111 000",
                        "cyber_crime": "+34 915 822 640",
                        "identity_theft": "+34 900 202 202"
                    },
                    "transportation": {
                        "renfe": "+34 912 320 320",
                        "iberia": "+34 901 111 500",
                        "airport_barcelona": "+34 913 211 000",
                        "airport_madrid": "+34 913 936 000",
                        "public_transport_madrid": "+34 915 214 260"
                    },
                    "utilities": {
                        "telefonica_support": "+34 900 104 709",
                        "vodafone_support": "+34 123",
                        "orange_support": "+34 1470"
                    }
                },
                "iseumember": true
            }
        },
        "provider": {
            "as": "AS8708 RCS & RDS",
            "asname": "RCS-RDS",
            "isp": "RCS & RDS",
            "org": "RCS & RDS Residential"
        },
        "status": "success",
        "language": {
            "by_browser": false,
            "by_country": "es"
        },
        "locale": {
            "by_browser": false
        },
        "country_details": {
            "additional_data": "Extended country details loaded successfully"
        }
    },
    "processing_time": "40.12ms",
    "weather": {
        "status": "success",
        "location": {
            "name": "Madrid",
            "region": "Madrid",
            "country": "Spain",
            "lat": 40.4,
            "lon": -3.683,
            "timezone": "Europe/Madrid",
            "localtime": "2026-04-07 23:59"
        },
        "current": {
            "last_updated": "2026-04-07 23:45",
            "temp_c": 14.4,
            "temp_f": 57.9,
            "condition": {
                "text": "Partly cloudy",
                "icon": "02",
                "icon_url": "https://api.paperoffice.ai/latest/ip2location/weathericon_get?condition_code=1003",
                "code": 1003
            },
            "wind_mph": 13.6,
            "wind_kph": 22,
            "wind_degree": 281,
            "wind_dir": "W",
            "pressure_mb": 1019,
            "pressure_in": 30.09,
            "precip_mm": 1.87,
            "precip_in": 0.07,
            "humidity": 82,
            "cloud": 50,
            "feelslike_c": 12.8,
            "feelslike_f": 55,
            "vis_km": 10,
            "vis_miles": 6,
            "uv": 0,
            "gust_mph": 17.4,
            "gust_kph": 28
        },
        "precipitation": {
            "rain_hours": 96,
            "total_mm": 15.3,
            "max_probability": 98,
            "need_umbrella": true
        },
        "air_quality": {
            "co": 134.85,
            "no2": 16.95,
            "o3": 62,
            "so2": 3.15,
            "pm2_5": 15.35,
            "pm10": 34.65,
            "us_epa_index": 1,
            "gb_defra_index": 2
        },
        "forecast": [
            {
                "date": "2026-04-07",
                "date_epoch": 1775520000,
                "day": {
                    "maxtemp_c": 22.7,
                    "maxtemp_f": 72.9,
                    "mintemp_c": 12.2,
                    "mintemp_f": 53.9,
                    "avgtemp_c": 16.8,
                    "avgtemp_f": 62.2,
                    "maxwind_mph": 17.7,
                    "maxwind_kph": 28.4,
                    "totalprecip_mm": 6.22,
                    "totalprecip_in": 0.24,
                    "totalsnow_cm": 0,
                    "avgvis_km": 9.7,
                    "avgvis_miles": 6,
                    "avghumidity": 54,
                    "condition": {
                        "text": "Moderate rain",
                        "icon": "22",
                        "icon_url": "https://api.paperoffice.ai/latest/ip2location/weathericon_get?condition_code=1189",
                        "code": 1189
                    },
                    "uv": 1,
                    "daily_chance_of_rain": 98,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:49 AM",
                    "sunset": "08:45 PM",
                    "moonrise": "01:38 AM",
                    "moonset": "10:23 AM",
                    "moon_phase": "Waning Gibbous",
                    "moon_illumination": 79,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            },
            {
                "date": "2026-04-08",
                "date_epoch": 1775606400,
                "day": {
                    "maxtemp_c": 20.4,
                    "maxtemp_f": 68.7,
                    "mintemp_c": 11.6,
                    "mintemp_f": 52.9,
                    "avgtemp_c": 14.6,
                    "avgtemp_f": 58.2,
                    "maxwind_mph": 14.3,
                    "maxwind_kph": 23,
                    "totalprecip_mm": 0.98,
                    "totalprecip_in": 0.04,
                    "totalsnow_cm": 0,
                    "avgvis_km": 9.8,
                    "avgvis_miles": 6,
                    "avghumidity": 68,
                    "condition": {
                        "text": "Patchy rain nearby",
                        "icon": "06",
                        "icon_url": "https://api.paperoffice.ai/latest/ip2location/weathericon_get?condition_code=1063",
                        "code": 1063
                    },
                    "uv": 1.1,
                    "daily_chance_of_rain": 82,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:48 AM",
                    "sunset": "08:46 PM",
                    "moonrise": "02:34 AM",
                    "moonset": "11:12 AM",
                    "moon_phase": "Waning Gibbous",
                    "moon_illumination": 70,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            },
            {
                "date": "2026-04-09",
                "date_epoch": 1775692800,
                "day": {
                    "maxtemp_c": 26.5,
                    "maxtemp_f": 79.7,
                    "mintemp_c": 10.2,
                    "mintemp_f": 50.4,
                    "avgtemp_c": 17.5,
                    "avgtemp_f": 63.5,
                    "maxwind_mph": 16.6,
                    "maxwind_kph": 26.6,
                    "totalprecip_mm": 0,
                    "totalprecip_in": 0,
                    "totalsnow_cm": 0,
                    "avgvis_km": 10,
                    "avgvis_miles": 6,
                    "avghumidity": 48,
                    "condition": {
                        "text": "Sunny",
                        "icon": "01",
                        "icon_url": "https://api.paperoffice.ai/latest/ip2location/weathericon_get?condition_code=1000",
                        "code": 1000
                    },
                    "uv": 1.4,
                    "daily_chance_of_rain": 0,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:46 AM",
                    "sunset": "08:47 PM",
                    "moonrise": "03:23 AM",
                    "moonset": "12:08 PM",
                    "moon_phase": "Waning Gibbous",
                    "moon_illumination": 61,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            },
            {
                "date": "2026-04-10",
                "date_epoch": 1775779200,
                "day": {
                    "maxtemp_c": 25.7,
                    "maxtemp_f": 78.3,
                    "mintemp_c": 13.5,
                    "mintemp_f": 56.4,
                    "avgtemp_c": 19.2,
                    "avgtemp_f": 66.5,
                    "maxwind_mph": 12.3,
                    "maxwind_kph": 19.8,
                    "totalprecip_mm": 0,
                    "totalprecip_in": 0,
                    "totalsnow_cm": 0,
                    "avgvis_km": 10,
                    "avgvis_miles": 6,
                    "avghumidity": 34,
                    "condition": {
                        "text": "Sunny",
                        "icon": "01",
                        "icon_url": "https://api.paperoffice.ai/latest/ip2location/weathericon_get?condition_code=1000",
                        "code": 1000
                    },
                    "uv": 1.3,
                    "daily_chance_of_rain": 0,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:45 AM",
                    "sunset": "08:48 PM",
                    "moonrise": "04:05 AM",
                    "moonset": "01:10 PM",
                    "moon_phase": "Last Quarter",
                    "moon_illumination": 52,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            },
            {
                "date": "2026-04-11",
                "date_epoch": 1775865600,
                "day": {
                    "maxtemp_c": 17,
                    "maxtemp_f": 62.6,
                    "mintemp_c": 9.6,
                    "mintemp_f": 49.3,
                    "avgtemp_c": 14.5,
                    "avgtemp_f": 58,
                    "maxwind_mph": 17.7,
                    "maxwind_kph": 28.4,
                    "totalprecip_mm": 5.55,
                    "totalprecip_in": 0.22,
                    "totalsnow_cm": 0,
                    "avgvis_km": 8.2,
                    "avgvis_miles": 5,
                    "avghumidity": 65,
                    "condition": {
                        "text": "Moderate rain",
                        "icon": "22",
                        "icon_url": "https://api.paperoffice.ai/latest/ip2location/weathericon_get?condition_code=1189",
                        "code": 1189
                    },
                    "uv": 0.5,
                    "daily_chance_of_rain": 87,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:43 AM",
                    "sunset": "08:49 PM",
                    "moonrise": "04:40 AM",
                    "moonset": "02:15 PM",
                    "moon_phase": "Waning Crescent",
                    "moon_illumination": 42,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            },
            {
                "date": "2026-04-12",
                "date_epoch": 1775952000,
                "day": {
                    "maxtemp_c": 14.3,
                    "maxtemp_f": 57.8,
                    "mintemp_c": 6.1,
                    "mintemp_f": 43,
                    "avgtemp_c": 8.6,
                    "avgtemp_f": 47.4,
                    "maxwind_mph": 17,
                    "maxwind_kph": 27.4,
                    "totalprecip_mm": 2.55,
                    "totalprecip_in": 0.1,
                    "totalsnow_cm": 0,
                    "avgvis_km": 8.3,
                    "avgvis_miles": 5,
                    "avghumidity": 64,
                    "condition": {
                        "text": "Patchy rain nearby",
                        "icon": "06",
                        "icon_url": "https://api.paperoffice.ai/latest/ip2location/weathericon_get?condition_code=1063",
                        "code": 1063
                    },
                    "uv": 1.2,
                    "daily_chance_of_rain": 80,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:41 AM",
                    "sunset": "08:50 PM",
                    "moonrise": "05:10 AM",
                    "moonset": "03:22 PM",
                    "moon_phase": "Waning Crescent",
                    "moon_illumination": 33,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            },
            {
                "date": "2026-04-13",
                "date_epoch": 1776038400,
                "day": {
                    "maxtemp_c": 17.2,
                    "maxtemp_f": 63,
                    "mintemp_c": 3.7,
                    "mintemp_f": 38.6,
                    "avgtemp_c": 10.2,
                    "avgtemp_f": 50.4,
                    "maxwind_mph": 6.3,
                    "maxwind_kph": 10.1,
                    "totalprecip_mm": 0,
                    "totalprecip_in": 0,
                    "totalsnow_cm": 0,
                    "avgvis_km": 10,
                    "avgvis_miles": 6,
                    "avghumidity": 42,
                    "condition": {
                        "text": "Sunny",
                        "icon": "01",
                        "icon_url": "https://api.paperoffice.ai/latest/ip2location/weathericon_get?condition_code=1000",
                        "code": 1000
                    },
                    "uv": 4,
                    "daily_chance_of_rain": 0,
                    "daily_chance_of_snow": 0
                },
                "astro": {
                    "sunrise": "07:40 AM",
                    "sunset": "08:52 PM",
                    "moonrise": "05:36 AM",
                    "moonset": "04:30 PM",
                    "moon_phase": "Waning Crescent",
                    "moon_illumination": 23,
                    "is_moon_up": 0,
                    "is_sun_up": 0
                }
            }
        ]
    }
}
```

### List weather icons

`POST https://api.paperoffice.ai/latest/ip2location/weathericon_get`

Weather Icons Get weather icon URLs. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | icon_code | string | Yes | Weather icon code | Response: Icon URL

**Tool-ID:** `po_weather_icons` • **Cost:** 10 credits • **MCP:** `po_weather_icons` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `condition_code` | string | No | Query parameter: condition_code |
| `size` | string | No | Query parameter: size |
| `is_day` | string | No | Query parameter: is_day |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "icons": [],
    "processing_time": "example"
}
```

---

## Document AI — Anonymization

### Anonymize document (single-step)

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Complete GDPR-compliant anonymization in one step: PDF Upload → OCR → PII Detection → Redaction → Anonymized PDF. Combines po_anonymization_pii_detect and po_anonymization_redaction_apply without intermediate steps. Configurable via categories, whitelist, and custom instructions.

**Tool-ID:** `po_anonymization_anonymize_document` • **Cost:** Free • **MCP:** `po_anonymization_anonymize_document` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template` | string | No | Workflow template (default: "document_anonymize") |
| `file` | string | Yes | PDF or image file to anonymize |
| `pofid` | string | No | Or: existing DMS document POFID (default: "") |
| `redact_categories` | string | No | Categories: all, none, names, addresses, phone, email, iban, tax_ids, dates, financial, contact, identity (default: "all") |
| `whitelist` | string | No | Comma-separated terms to NEVER redact (default: "") |
| `custom_redact` | string | No | Additional terms to ALWAYS redact (default: "") |
| `custom_instructions` | string | No | Free-text AI instructions e.g. Also redact all prices (default: "") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. (default: "999") |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654271.3318_4d82887e3daee496bdd20f0a7c3598b7",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "9146.51ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YBWXwZQmQGUw0JRW0FEHtdV2cKWGF_Sg5dY1FGew4SdQYRNgdAPVdMexkfKlAIfl8LJG9eeAk1egVbbw5NdwRBcx1dfgVHCAxUZgERa1FNfgBWYgdTZHtLWl1lBBV3ChcoBEM2U01rbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5zAU4"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6882007122039795,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.688,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654276.031887",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654273.8713_8f1bce6639a685470b0118d4cf7c0e29_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 2306,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 688,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 472,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 6657
    },
    "status": "success",
    "timing": {
        "actual_ms": 6728.41,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 3.3,
        "speed_factor": 30.5,
        "performance": "30.5x faster than expected 🚀"
    }
}
```

### Apply redaction

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Step 2: Apply Redaction. Applies black boxes to the specified regions and generates the final PDF. Important: Use the same job context from Step 1 (pass the job_id from the detect/preview response).

**Tool-ID:** `po_anonymization_apply_redaction` • **Cost:** 10 credits • **MCP:** `po_anonymization_apply_redaction` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | string | Yes | JSON array of original_images URLs from Step 1 (default: "[\"https:\/\/api.paprooffice.ai\/dev\/job\/download\/YOUR_IMAGE_URL_FROM_STEP1\"]") |
| `boxes_by_page` | string | No | JSON object: page number 5 digits → array of box indices from redact_box_ids (default: "{\"00001\": [0, 1, 2, 5, 7]}") |
| `redact_color` | string | No | Redaction color default: black (default: "#000000") |
| `output_pdf` | string | No | true = output PDF, false = output redacted images (default: "true") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. (default: "999") |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654278.1333_037dbf9eabaf4315e76edbe9c6c249e2",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5072.73ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YBWXUZQGQAUQ0IRm1QRH4KCTMKWGd6SAkIaQASelxFKlVBZQBFOFBMKxkfKlAIfl8LJG9eeAk1egVbbw5NdwRBeh1ffgNFCA1XZlRFbgYTKgBWZAJRYy5BCwlkVkIoWUd7A0YzVE07bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5zDkU"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.533944845199585,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.534,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654281.519369",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654280.0077_f825a5da5a764fb1906543f1f9d242d6_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1757,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 534,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 340,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5004
    },
    "status": "success",
    "timing": {
        "actual_ms": 5032.61,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.4,
        "speed_factor": 40.8,
        "performance": "40.8x faster than expected 🚀"
    }
}
```

### Detect PII preview

`GET https://api.paperoffice.ai/latest/document_intelligence/entities/{document_id}`

Step 1: Detect PII Preview Analyzes document and returns detected PII with bounding boxes. Response Structure: json { "status": "success", "job_result": { "workflow_output": { "original_images": "https://api.paperoffice.ai/latest/job/download/ABC123" , "simplified_boxes": { "text": "Max Mustermann",.

**Tool-ID:** `po_anonymization_detect_pii_preview` • **Cost:** 10 credits • **MCP:** `po_anonymization_detect_pii_preview` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template` | string | No | Workflow: PDF → PNG → OCR → PII Detection (default: "document_anonymize_preview") |
| `file` | string | Yes | PDF or Image file PNG, JPG |
| `pofid` | string | No | Optional PaproOffice DMS document ID instead of file (default: "") |
| `redact_categories` | string | No | Categories: all, none, names, addresses, phone, email, iban, tax_ids, dates, financial, contact, identity (default: "all") |
| `whitelist` | string | No | Terms to NEVER mark for redaction comma-separated (default: "") |
| `custom_redact` | string | No | Additional terms to ALWAYS mark for redaction (default: "") |
| `custom_instructions` | string | No | Free-text instructions for AI e.g. 'Also redact all prices' (default: "") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 4900
    },
    "job": {
        "api_job_name": "document_intelligence___entities",
        "app": "document_intelligence",
        "action": "entities",
        "option": "{document_id}",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.56ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Run anonymization full workflow example

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Complete Workflow Example This example shows Step 1 Preview. After running this: 1. Copy the original_images URL from the response 2. Copy the redact_box_ids array 3. Use them in Step 2 Apply Redaction Workflow: ┌───────────────────────────?.

**Tool-ID:** `po_anonymization_example_full_workflow` • **Cost:** 10 credits • **MCP:** `po_anonymization_example_full_workflow` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template` | string | No | Template (default: "document_anonymize_preview") |
| `file` | string | Yes | Upload your PDF here |
| `redact_categories` | string | No | Only redact contact information (default: "contact") |
| `whitelist` | string | No | Keep these company names visible (default: "PaproOffice,ACME Corp") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. (default: "900") |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654283.2787_242fdc9a632778bce6012e50ff8e13c0",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "7719.94ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YBVn4ZQ28EVA1QRGxRQ3pdC2cHWWZ8QQ9YMwUVfFtBdVJPNlYWaFcXLBkfKlAIfl8LJG9eeAk1egVbbw5NdwROcR1cdQdACFVVZ1VCalERfg1XZQRYZX4bDg5iUUZ3XkkoVRVjUxY8bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5zD0Y"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.416431188583374,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604424774646759,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.416,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654287.0507016",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654284.6993_87a37f33de4ed8aa0b0b648408f174ac_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1360,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 416,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 1418,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 7644
    },
    "status": "success",
    "timing": {
        "actual_ms": 7662.81,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 3.7,
        "speed_factor": 26.8,
        "performance": "26.8x faster than expected 🚀"
    }
}
```

---

## Document AI — DMS

### Dissolve (unstaple) folder

`POST https://api.paperoffice.ai/latest/documents/folder-dissolve`

Folder Dissolve Unstaple R260114.1700 Dissolve a document folder - unstaple the documents. --- When to Use - Remove document grouping - Split a bundle back into individual documents - Reorganize documents into different folders - Workflow: auto-dissolve after processing --- How It Works 1. Identi.

**Tool-ID:** `po_documents_folders_dissolve` • **Cost:** 10 credits • **MCP:** `po_documents_folders_dissolve` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `folder_id` | string | No | ID of the document folder to dissolve (e.g. 'folder_abc123..'). Entwethe folder_id or pofid required. |
| `pofid` | string | No | POFID a Documents in the folder. the associated folder is aufgeloest. Alternative zu folder_id. |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "status": "success",
            "released_pofids": [
                "example"
            ]
        }
    }
}
```

### Export document list

`POST https://api.paperoffice.ai/latest/documents/documents-export`

Export Documents Bulk export documents as ZIP archive. Options: - Specific POFIDs - All from workspace

**Tool-ID:** `po_document_lists_documents_export` • **Cost:** 10 credits • **MCP:** `po_document_lists_documents_export` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `selected_pofids` | array | Yes | JSON-Array to document POFIDs to export. |
| `export_format` | string | Yes | Exportformat: xlsx (Excel), csv, json or zip. (allowed: xlsx, csv, json, zip) |
| `selected_fields` | array | Yes | JSON-Array to exportierenthe fields (e.g. ['file_name', 'created_datetime', 'file_size']). |
| `field_order` | array | No | Optional order the columns in the Export. |
| `include_original_files` | boolean | No | Original-files in the Export include (only at ZIP-Format). (default: false) |
| `include_ocr_text` | boolean | No | OCR-extracted Text with export. (default: false) |
| `include_ocr_bounding_boxes` | boolean | No | OCR-Bounding-Boxes (Positionsdaten) with export. (default: false) |
| `archive_format` | string | No | Archive-Format at file-Exporten. (allowed: zip, 7z) (default: "zip") |
| `excel_options` | object | No | Optional Excel-specific settings (column width, header formatting etc.). |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output_files": [],
        "output": {
            "total_exported": 1,
            "format": "example"
        }
    }
}
```

### Extract maximum metadata

`POST https://api.paperoffice.ai/latest/documents/document-metadata`

Variable Metadata Max Extraction Extract all possible metadata and content from any document. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vis.

**Tool-ID:** `po_doc_analysis_metadata_max_extraction` • **Cost:** 10 credits • **MCP:** `po_doc_analysis_metadata_max_extraction` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | Model (default: "ultra") |
| `idp_collection` | string | No | Idp collection (default: "variable_metadata") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "fields": [],
            "text": "example"
        }
    }
}
```

### Get document metadata

`POST https://api.paperoffice.ai/latest/documents/document-metadata`

Document Metadata Extract general document metadata. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | | idp_collection | string .

**Tool-ID:** `po_document_analysis_metadata` • **Cost:** 10 credits • **MCP:** `po_document_analysis_metadata` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | Model (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "document_metadata") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "metadata": [],
            "document_type": "example",
            "language": "en_US",
            "page_count": 1
        }
    }
}
```

### List folders

`POST https://api.paperoffice.ai/latest/documents/folder-list`

Folder List R260114.1700 List all document folders staples in a workspace. --- When to Use - Display document bundles in UI - Find folder_id to add/remove documents - Get overview of grouped documents - Check which documents are stapled together --- How It Works 1. Query all folders in specified .

**Tool-ID:** `po_documents_folders_list` • **Cost:** 10 credits • **MCP:** `po_documents_folders_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | string | No | Required: Workspace ID to list folders from |

### Run DMS document analysis

`POST https://api.paperoffice.ai/latest/documents/document-analysis`

Document Analysis DMS General document classification and metadata extraction. Fields: document_type, date, sender, recipient, subject, keywords Parameter: | Param | Type | Required | |-------|------|----------| | file_1 | file | Yes | | model | string | Yes |

**Tool-ID:** `po_document_analysis_analysis_dms` • **Cost:** 10 credits • **MCP:** `po_document_analysis_analysis_dms` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | Model (default: "ultra") |
| `idp_collection` | string | No | Idp collection (default: "document_analysis") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "document_keywords": [
                "example"
            ],
            "document_name": "example",
            "document_type_classification": "example",
            "document_save_paths": [
                "example"
            ],
            "document_summary_short": "example"
        }
    }
}
```

### Staple documents into folder

`POST https://api.paperoffice.ai/latest/documents/folder-create`

Folder Create Staple Documents R260114.1700 Staple multiple documents together into a document folder. --- When to Use - Group related documents invoice + payment + delivery note - Create document bundles for projects - Organize multi-part documents contract + appendices - Workflow: auto-staple d.

**Tool-ID:** `po_documents_folders_create` • **Cost:** 10 credits • **MCP:** `po_documents_folders_create` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofids` | array | Yes | List the PaproOffice-Document IDs (POFIDs) that are to be summarized in the folder. At least 2 are required. |
| `folder_name` | string | No | Name of the document folder. If empty, it is automatically generated (e.g., '3 linked Documents'). |
| `folder_type` | string | No | type the folder: 'staple' (geheftete Documents) or 'folder' (folder). (allowed: staple, folder) (default: "staple") |
| `folder_description` | string | No | Optional description for the document folder. |
| `parent_pofid` | string | No | POFParent document ID. Default: first document in the list. |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "folder_id": "example",
            "document_count": 1
        }
    }
}
```

### Update folder

`POST https://api.paperoffice.ai/latest/documents/folder-update`

Folder Update R260114.1700 Update a document folder's metadata name, description, icon, color. --- When to Use - Rename a document bundle - Add or update folder description - Change folder icon or color for visual organization - Workflow: auto-update folder name based on status --- How It Works 1.

**Tool-ID:** `po_documents_folders_update` • **Cost:** 10 credits • **MCP:** `po_documents_folders_update` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `folder_id` | string | Yes | ID of the document folder to update. |
| `folder_name` | string | No | New name the document folder. |
| `folder_description` | string | No | new description of the document folder. |
| `folder_icon` | string | No | new Icon for the document folder (Emoji or Icon-Name). |
| `folder_color` | string | No | new color for the document folder (hex color code, e.g. '#3b82f6'). |

**Example Response:**

```json
{
    "folder_id": "test",
    "message": "Document folder updated",
    "processing_time": "81.11ms",
    "status": "success",
    "updates": []
}
```

### Acquire Edit-Session (Presence-Lock)

`POST https://api.paperoffice.ai/latest/documents/document-edit-session-acquire`

Erwirbt a kooperativen metadata-Editing-Lock for a document. if already a anderer users editiert, is status=readonly zurückgegeben. the Lock is ephemer — er hält maximal 60 seconds without Heartbeat.

**Tool-ID:** `po_documents_edit_session_acquire` • **Cost:** Free • **MCP:** `po_documents_edit_session_acquire` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice Document ID (pofid) — as URL-Path-Parameter or in the Body |

### Analyze document vision

`GET https://api.paperoffice.ai/latest/document_intelligence/vision/{document_id}`

Delivers vision analysis data for a document: Extracted tables, charts, forms, barcodes, layout information. Automatically created by the Harvester using AI vision.

**Tool-ID:** `po_intelligence_vision` • **Cost:** 10 credits • **MCP:** `po_intelligence_vision` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_id` | string | Yes | Numeric document ID (integer). Use the documents_id from document listing, NOT the POFID hash string. |
| `include` | string | No | which data (default: all) (allowed: all, tables, charts, forms, barcodes, layout) |

### Create Document from Content

`POST https://api.paperoffice.ai/latest/document_generation/create-from-content`

Generate a PDF document from Markdown or HTML content and save it directly to the DMS. Supports tables, lists, code blocks, images, and automatic metadata assignment.

**Tool-ID:** `po_documents_create_from_content` • **Cost:** 10 credits • **MCP:** `po_documents_create_from_content` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `content` | string | Yes | Markdown or HTML Content for the Document (required) |
| `content_type` | string | No | type the Contents: markdown or html (allowed: markdown, html) (default: "markdown") |
| `output_format` | string | No | Output format of the created document (allowed: pdf) (default: "pdf") |
| `title` | string | No | Documenttitel (is aso as Dataame used) |
| `workspace_id` | integer | Yes | target workspace ID (required). Use po_workspaces_list to find valid workspace IDs. |
| `metadata` | object | No | metadata as key-value pairs (are as IDP-fields stored) |
| `language` | string | No | Language for formatting (de/en) (default: "de") |
| `auto_classify` | boolean | No | automatic Klassifikation after creation (default: false) |
| `custom_css` | string | No | Additionals CSS for the PDF-Layout |
| `header_html` | string | No | HTML for page header |
| `footer_html` | string | No | HTML for footer |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "id": 12345,
    "created_at": "2026-04-16T10:00:00Z"
}
```

### Create Document from Template

`POST https://api.paperoffice.ai/latest/document_generation/create-from-template`

Generate a PDF document from a saved template with variable substitution and save it to the DMS.

**Tool-ID:** `po_documents_create_from_template` • **Cost:** 10 credits • **MCP:** `po_documents_create_from_template` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template_id` | string | Yes | Template ID (e.g. tpl_invoice_standard) |
| `variables` | object | Yes | Variable values for the placeholders in the template. Arrays for {{#each}} blocks. |
| `output_format` | string | No | (allowed: pdf) (default: "pdf") |
| `workspace_id` | integer | Yes | target workspace ID (required). Use po_workspaces_list to find valid workspace IDs. |
| `title` | string | No | Document Title (viaSchreibt Template Name). Can contain {{variable}} placeholders. |
| `metadata` | object | No | Additional metadata |
| `auto_classify` | boolean | No | (default: false) |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "id": 12345,
    "created_at": "2026-04-16T10:00:00Z"
}
```

### Create Document Template

`POST https://api.paperoffice.ai/latest/document_generation/template-create`

Create a new document template with HTML content and placeholder definitions.

**Tool-ID:** `po_templates_create` • **Cost:** 10 credits • **MCP:** `po_templates_create` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template_id` | string | No | Uniquee Template-ID (is auto-generates if empty) |
| `name` | string | Yes | Name the Templates |
| `html_content` | string | Yes | HTML-Content with {{variable}} placeholdersn |
| `description` | string | No | description the Templates |
| `category` | string | No | category (e.g. invoices, contracts, reports) (default: "general") |
| `variables_schema` | object | No | JSON-Schema the erwarteten Variablen |
| `page_format` | string | No | pagesformat (A4, A3, Letter) (default: "A4") |
| `page_orientation` | string | No | (allowed: portrait, landscape) (default: "portrait") |
| `margin_top` | integer | No | (default: 20) |
| `margin_right` | integer | No | (default: 15) |
| `margin_bottom` | integer | No | (default: 20) |
| `margin_left` | integer | No | (default: 15) |
| `header_html` | string | No | HTML for page header |
| `footer_html` | string | No | HTML for footer |

**Example Response:**

```json
{
    "category": "general",
    "message": "Template erfolgreich creates.",
    "name": "test",
    "processing_time": "51.17ms",
    "status": "success",
    "template_id": "tpl_test_37e1ce99"
}
```

### Delete Document Template

`POST https://api.paperoffice.ai/latest/document_generation/template-delete`

Deletes (deactivates) a document template. Soft-Delete — can be reactivated.

**Tool-ID:** `po_templates_delete` • **Cost:** 10 credits • **MCP:** `po_templates_delete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template_id` | string | Yes | Template-ID |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "deleted": true,
    "deleted_at": "2026-04-16T10:00:00Z"
}
```

### Get Document Template

`POST https://api.paperoffice.ai/latest/document_generation/template-get`

Returns details of a document template including HTML content and variable schema.

**Tool-ID:** `po_templates_get` • **Cost:** 10 credits • **MCP:** `po_templates_get` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template_id` | string | Yes | Template-ID |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "data": []
}
```

### Get linked documents

`POST https://api.paperoffice.ai/latest/documents/linked-documents`

Documents linked to a CRM account. Link Types: - invoice - Invoices - contract - Contracts - quote - Quotes - correspondence - Correspondence - related - Other

**Tool-ID:** `po_documents_get_linked_documents` • **Cost:** 10 credits • **MCP:** `po_documents_get_linked_documents` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | string | No | Max results (default: 50, max: 200) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9539
    },
    "job": {
        "api_job_name": "documents___linked_documents",
        "app": "documents",
        "action": "linked-documents",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.28ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Heartbeat Edit-Session

`POST https://api.paperoffice.ai/latest/documents/document-edit-session-heartbeat`

Hält a zuvor erworbene Edit-Session at the Leben. all 30 seconds send. returns 409 EDIT_SESSION_LOST Back, if the Lock already verloren was.

**Tool-ID:** `po_documents_edit_session_heartbeat` • **Cost:** Free • **MCP:** `po_documents_edit_session_heartbeat` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice Document ID (pofid) — as URL-Path-Parameter or in the Body |

### List Document Templates

`POST https://api.paperoffice.ai/latest/document_generation/templates-list`

List all available document templates of the account.

**Tool-ID:** `po_templates_list` • **Cost:** 10 credits • **MCP:** `po_templates_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `category` | string | No | Category filter (e.g. invoices, contracts, reports) |
| `limit` | integer | No | Max results (1-200) (default: 50) |
| `offset` | integer | No | (default: 0) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9539
    },
    "job": {
        "api_job_name": "document_generation___templates-list",
        "app": "document_generation",
        "action": "templates-list",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.69ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Merge publisher

`POST https://api.paperoffice.ai/latest/publishers/{source_publisher_id}/merge`

Two Publisher merge and references move

**Tool-ID:** `po_publishers_merge` • **Cost:** 10 credits • **MCP:** `po_publishers_merge` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `source_publisher_id` | integer | Yes | ID of the Publishers the aufgeloest is |
| `target_publisher_id` | integer | Yes | ID of the target-Publishers in the gemerged is |

**Example Response:**

```json
{
    "processing_time": "362.85ms",
    "status": "success"
}
```

### Query Edit-Session Status

`GET https://api.paperoffice.ai/latest/documents/document-edit-session-status`

Fragt the current Edit-Session-Status of a document's (free/mine/taken) without the Lock zu übernehmen.

**Tool-ID:** `po_documents_edit_session_status` • **Cost:** Free • **MCP:** `po_documents_edit_session_status` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice Document ID (pofid) — as URL-Path-Parameter or in the Body |

### Release Edit-Session

`POST https://api.paperoffice.ai/latest/documents/document-edit-session-release`

returns the Edit-Session-Lock for a document frei. by Release can andere users the document edit.

**Tool-ID:** `po_documents_edit_session_release` • **Cost:** Free • **MCP:** `po_documents_edit_session_release` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice Document ID (pofid) — as URL-Path-Parameter or in the Body |

### Rename publisher

`POST https://api.paperoffice.ai/latest/publishers/{publisher_id}/rename`

Publisher rename with automatic alias storage

**Tool-ID:** `po_publishers_rename` • **Cost:** 10 credits • **MCP:** `po_publishers_rename` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `publisher_id` | integer | Yes | ID of the Publishers |
| `new_name` | string | Yes | New name for the Publisher |

**Example Response:**

```json
{
    "processing_time": "394.65ms",
    "status": "success"
}
```

### Search documents (ultimate)

`POST https://api.paperoffice.ai/latest/documents/documents-list`

ULTIMATE SEARCH ENGINE - Intelligent Multi-Source Document Search (31.01.2026) Searches documents using 4 parallel search sources with RRF Fusion:

**Tool-ID:** `po_storage_documents_list` • **Cost:** 10 credits • **MCP:** `po_storage_documents_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | Yes | Required: ID of the workspace |
| `global_search` | string | No | {"search_term":"Search term for Ultimate Search (all 4 sources)","source_count":4,"pipeline_ids":["paprooffice_datarippro","paprooffice_aiocr","paprooffice_devtools","paprooffice_ai"],"translation_status":"completed","language_pair":"de-en"} |
| `search_mode` | string | No | intelligent=automatic Query-type-detection (empfohlen) (allowed: intelligent, hybrid, semantic, fulltext) (default: "intelligent") |
| `search_preference` | string | No | keyword=Stichwortsuche, semantic=AI-Search, balanced=ausgewogen (allowed: keyword, semantic, balanced) (default: "balanced") |
| `search_scope` | string | No | current=only currenter Workspace, all=all Workspaces (allowed: current, all) (default: "current") |
| `similarity_threshold` | number | No | Minimum Similarity for Semantic Search (0.0-1.0) (default: 0.35) |
| `page` | integer | No | Page number for pagination (default: 1) |
| `limit` | integer | No | documente per page (max 500) (default: 500) |
| `sort` | string | No | Sortierfeld (default: "created_datetime") |
| `order` | string | No | Order (allowed: ASC, DESC) (default: "DESC") |
| `__document__data__classification__document_type` | array | No | Filter: Documenttypen (JSON Array or komma-separiert) |
| `__document__content__extraction__keywords` | array | No | Filter: Keywords |
| `__document__data__workflow__state` | array | No | Filter: Workflow-Status |
| `__document__data__classification__locale` | array | No | Filter: language/Locale |
| `__document__data__metadata__save_paths` | array | No | Filter: Speicherpfade (PREFIX_WILDCARD:/path or EXACT:/path) |
| `ai_dms_status` | array | No | Filter: AI-DMS Tier |
| `ai_agent_status` | array | No | Filter: AI-Agent Status |
| `date_from` | string | No | Filter: Date from (YYYY-MM-DD) |
| `date_to` | string | No | Filter: date bis (YYYY-MM-DD) |
| `share_context` | string | No | Share context |

**Example Response:**

```json
{
    "applied_filters": [],
    "count": 0,
    "documents": [],
    "documents_meta_fields": [],
    "filter_values": [],
    "message": "database is initialisiert — bitte page neu laden",
    "pagination": {
        "total": 0,
        "current_page": 1,
        "total_pages": 1,
        "limit": 500,
        "showing_from": 0,
        "showing_to": 0,
        "has_more": false,
        "message": "database is initialisiert — bitte page neu laden"
    },
    "processing_time": "11.65ms",
    "search_stats": {
        "mode": "intelligent",
        "actual_search_mode": "fulltext",
        "scope": "current",
        "query_type": null,
        "semantic_matches": 0,
        "fulltext_matches": 0,
        "ocr_matches": 0,
        "entity_matches": 0,
        "total_sources_used": 0,
        "embedding_from_cache": false,
        "embedding_time_ms": 0,
        "search_time_ms": 0
    },
    "stats": {
        "total_documents": 0,
        "ai_dms_stats": [],
        "ai_agent_stats": []
    },
    "status": "success",
    "total": 0
}
```

### Update Document Template

`POST https://api.paperoffice.ai/latest/document_generation/template-update`

Updates an existing document template.

**Tool-ID:** `po_templates_update` • **Cost:** 10 credits • **MCP:** `po_templates_update` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template_id` | string | Yes | Template-ID (required) |
| `name` | string | No |  |
| `html_content` | string | No |  |
| `description` | string | No |  |
| `category` | string | No |  |
| `variables_schema` | object | No |  |
| `page_format` | string | No |  |
| `page_orientation` | string | No | (allowed: portrait, landscape) |
| `margin_top` | integer | No |  |
| `margin_right` | integer | No |  |
| `margin_bottom` | integer | No |  |
| `margin_left` | integer | No |  |
| `header_html` | string | No |  |
| `footer_html` | string | No |  |
| `is_active` | integer | No | 1=aktiv, 0=deaktiviert |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "updated": true,
    "updated_at": "2026-04-16T10:00:00Z"
}
```

### Extract Document entities

`POST https://api.paperoffice.ai/latest/document_intelligence/entities`

All extracted entities of a document. Entity Types: company, person, location, date, amount, iban, product, email, phone, tax_id, reference. Includes Confidence scores and source positions.

**Tool-ID:** `po_entities_get_document_entities` • **Cost:** 10 credits • **MCP:** `po_entities_get_document_entities` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `type` | string | No | Optional: company, proson, iban, amount, date, email, phone, invoice_number, etc. |
| `min_confidence` | string | No | Optional: Minimum confidence score (0.0-1.0) |
| `include_positions` | string | No | Optional: Include bounding box positions |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9539
    },
    "job": {
        "api_job_name": "document_intelligence___entities",
        "app": "document_intelligence",
        "action": "entities",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.19ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get Canonical entities

`GET https://api.paperoffice.ai/latest/document_intelligence/entities/canonical`

Canonical deduplicated entities across all documents. Shows how often an entity appears in different documents.

**Tool-ID:** `po_entities_get_canonical_entities` • **Cost:** 10 credits • **MCP:** `po_entities_get_canonical_entities` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `type` | string | No | Optional: Filter by entity type |
| `workspace_id` | string | No | Optional: Filter by workspace |
| `search` | string | No | Optional: Search term |
| `limit` | string | No | Max results (default: 100, max: 500) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9730
    },
    "job": {
        "api_job_name": "document_intelligence___entities",
        "app": "document_intelligence",
        "action": "entities",
        "option": "canonical",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "12.07ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Search entities

`GET https://api.paperoffice.ai/latest/document_intelligence/entities/search`

Search for entities across all documents. Find entities that contain the search term and display the associated document.

**Tool-ID:** `po_entities_search_entities` • **Cost:** 10 credits • **MCP:** `po_entities_search_entities` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `q` | string | No | Search query (required) |
| `type` | string | No | Optional: Filter by entity type |
| `workspace_id` | string | No | Optional: Filter by workspace |
| `limit` | string | No | Max results (max: 200) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9730
    },
    "job": {
        "api_job_name": "document_intelligence___entities",
        "app": "document_intelligence",
        "action": "entities",
        "option": "search",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.39ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get account insights

`POST https://api.paperoffice.ai/latest/documents/account-insights`

All AI insights for a specific CRM account. Including Overall Health Score and Risk Level.

**Tool-ID:** `po_insights_get_account_insights` • **Cost:** 10 credits • **MCP:** `po_insights_get_account_insights` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `account_id` | integer | No | Optional CRM account ID for targeted insights. |
| `type` | string | No | Filter after Insight-type (e.g. 'churn_risk', 'sentiment'). |
| `min_score` | number | No | Minimum score value for filtering. |
| `max_score` | number | No | {"max_score_value_for_filtering":"Maximum score value for filtering."} |
| `limit` | integer | No | Maximum number results. (default: 50) |
| `offset` | integer | No | Offset for pagination. (default: 0) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "documents___account_insights",
        "app": "documents",
        "action": "account-insights",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.35ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get all insights

`POST https://api.paperoffice.ai/latest/documents/all-insights`

All AI Insights across accounts or filtered. Insight Types: - sentiment - communication_sentiment - health_score - relationship_health - churn_risk - attrition_risk - engagement - engagement_level - upsell_potential - upselling_potential - support_satisfaction - support_satisfaction

**Tool-ID:** `po_insights_get_all_insights` • **Cost:** 10 credits • **MCP:** `po_insights_get_all_insights` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `account_id` | string | No | Optional: Filter by CRM account |
| `type` | string | No | Optional: sentiment, health_score, churn_risk, engagement, upsell_potential |
| `min_score` | string | No | Optional: Minimum score |
| `max_score` | string | No | Optional: Maximum score |
| `limit` | string | No | Max results (default: 50, max: 200) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "documents___all_insights",
        "app": "documents",
        "action": "all-insights",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.37ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get meta fields

`GET https://api.paperoffice.ai/latest/document_intelligence/meta_fields/{document_id}`

Get all AI-IDP extracted meta fields for a document by category: financial, parties, dates, classification, analysis.

**Tool-ID:** `po_meta_fields_get_meta_fields` • **Cost:** 10 credits • **MCP:** `po_meta_fields_get_meta_fields` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `category` | string | No | Optional: financial, parties, metadata, dates, content, etc. |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9630
    },
    "job": {
        "api_job_name": "document_intelligence___meta_fields",
        "app": "document_intelligence",
        "action": "meta_fields",
        "option": "{document_id}",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.27ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get upsell opportunities

`POST https://api.paperoffice.ai/latest/documents/upsell-opportunities`

Identify upselling opportunities. Accounts with high upselling potential, sorted by score.

**Tool-ID:** `po_opportunities_get_upsell_opportunities` • **Cost:** 10 credits • **MCP:** `po_opportunities_get_upsell_opportunities` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `min_potential` | string | No | Minimum upsell potential (default: 0.3) |
| `limit` | string | No | Max results (default: 20, max: 100) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "documents___upsell_opportunities",
        "app": "documents",
        "action": "upsell-opportunities",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "7.65ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get document revisions

`GET https://api.paperoffice.ai/latest/documents/document-revisions`

Document version history. Displays all changes with timestamp, user, and change details.

**Tool-ID:** `po_revisions_get_document_revisions` • **Cost:** 10 credits • **MCP:** `po_revisions_get_document_revisions` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice-Document ID, for the revisions should be retrieved. Passed as URL parameter. |
| `limit` | integer | No | Maximum number returned revisions. (default: 50) |
| `offset` | integer | No | Offset for pagination. (default: 0) |
| `action` | string | No | Filter after Action type (e.g. 'field_changed', 'folder_created'). |
| `field_key` | string | No | Filter by changed field (e.g. 'invoice_number'). |
| `date_from` | string | No | revisions from this date (YYYY-MM-DD). |
| `date_to` | string | No | revisions bis zu this date (YYYY-MM-DD). |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9630
    },
    "job": {
        "api_job_name": "documents___document_revisions",
        "app": "documents",
        "action": "document-revisions",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.43ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get at-risk accounts

`POST https://api.paperoffice.ai/latest/documents/risk-analysis`

Accounts with high churn risk. Sorted by risk score, including factors and recommendations.

**Tool-ID:** `po_risk_analysis_get_atrisk_accounts` • **Cost:** 10 credits • **MCP:** `po_risk_analysis_get_atrisk_accounts` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `threshold` | string | No | Churn risk threshold (default: 0.5) |
| `limit` | string | No | Max results (default: 20, max: 100) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "documents___risk_analysis",
        "app": "documents",
        "action": "risk-analysis",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "7.17ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Run RAG search

`POST https://api.paperoffice.ai/latest/documents/document-search`

RAG Semantic Search Search across all knowledge sources using semantic similarity. How it works: 1. Your query is embedded using embedding model3-embedding:8b 2. Vector similarity search finds relevant chunks 3. Results ranked by cosine similarity Response: json { "status": "success", "data": { ".

**Tool-ID:** `po_search_rag` • **Cost:** 10 credits • **MCP:** `po_search_rag` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | No | Search query natural language (default: "How do I reset my password?") |
| `limit` | string | No | Max results default: 5 (default: "5") |
| `connector_types` | string | No | Filter by connector optional, comma-separated (default: "zammad") |
| `source_types` | string | No | Filter by source type optional (default: "ticket,kb_article") |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "documents___document_search",
        "app": "documents",
        "action": "document-search",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "7.59ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Run semantic vector search

`POST https://api.paperoffice.ai/latest/documents/document-search`

Semantic Vector Search AI-powered search using embeddings. How it works: 1. Query text is converted to 4096-dim vector via AI model 2. Cosine similarity search against document embeddings 3. Returns documents above similarity_threshold Requirements: - Documents must have been processed with embed.

**Tool-ID:** `po_search_semantic_vector` • **Cost:** 10 credits • **MCP:** `po_search_semantic_vector` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | Search term for semantic vector search |
| `workspace_id` | integer | No | Workspace ID |
| `limit` | integer | No | Max. results (default: 20) |
| `offset` | integer | No | Pagination-Offset (default: 0) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "documents___document_search",
        "app": "documents",
        "action": "document-search",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "10.7ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Search exact field value

`POST https://api.paperoffice.ai/latest/documents/document-search`

Exact Field Search Filter documents by exact meta-field value. Use cases: - Find all documents of type X - Filter by status field - Custom field filtering Note: Query must exactly match the stored value.

**Tool-ID:** `po_search_exact_field` • **Cost:** 10 credits • **MCP:** `po_search_exact_field` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `field` | string | Yes | fieldname for exact search (e.g., file_name, status) |
| `value` | string | Yes | Exaconcrete value for the field |
| `workspace_id` | integer | No | Workspace ID |
| `limit` | integer | No | Max. results (default: 20) |
| `offset` | integer | No | Pagination-Offset (default: 0) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "documents___document_search",
        "app": "documents",
        "action": "document-search",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Search fulltext

`POST https://api.paperoffice.ai/latest/documents/document-search`

Fulltext Search SQL LIKE + FULLTEXT search on: - file_name - All meta-field values - OCR text Features: - Relevance scoring - Pagination - Optional OCR preview

**Tool-ID:** `po_search_fulltext` • **Cost:** 10 credits • **MCP:** `po_search_fulltext` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | Search term for full-text search |
| `workspace_id` | integer | No | Workspace ID to restrict the search |
| `limit` | integer | No | Max. results (default: 20) |
| `offset` | integer | No | Pagination-Offset (default: 0) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "documents___document_search",
        "app": "documents",
        "action": "document-search",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "7.92ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Search hybrid

`POST https://api.paperoffice.ai/latest/documents/document-search`

Hybrid Search Fulltext + Semantic Combines both search methods for best results using OpenClaw-style weighted scoring. Parameters: - vector_weight float, default: 0.7: Weight for semantic/vector search 0-1 - bm25_weight float, default: 0.3: Weight for keyword/BM25 search 0-1 - Weights are automat.

**Tool-ID:** `po_search_hybrid` • **Cost:** 10 credits • **MCP:** `po_search_hybrid` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | Search term for hybrid search (Full-text + Semantic) |
| `workspace_id` | integer | No | Workspace ID for Restriction |
| `limit` | integer | No | Max. results (default: 20) |
| `offset` | integer | No | Pagination-Offset (default: 0) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "documents___document_search",
        "app": "documents",
        "action": "document-search",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "7.87ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get sentiment history

`POST https://api.paperoffice.ai/latest/documents/sentiment-history`

Sentiment analysis for an account over time. Shows sentiment trend from emails and notes.

**Tool-ID:** `po_sentiment_get_sentiment_history` • **Cost:** 10 credits • **MCP:** `po_sentiment_get_sentiment_history` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `days` | string | No | History proiod in days (default: 90, max: 365) |

### Get CRM statistics

`POST https://api.paperoffice.ai/latest/documents/crm-stats`

Global CRM Intelligence Statistics. Overview of all accounts, insights, risks, and opportunities.

**Tool-ID:** `po_statistics_get_crm_stats` • **Cost:** 10 credits • **MCP:** `po_statistics_get_crm_stats` via `mcp.paperoffice.ai`

### Add Document day

`POST https://api.paperoffice.ai/latest/documents/document-tag-add`

Add a day to a document.

**Tool-ID:** `po_documents_tags_create` • **Cost:** Free • **MCP:** `po_documents_tags_create` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID |
| `tag_name` | string | Yes | day-Name (max 100 characters) |
| `tag_color` | string | No | Optional hex color (#RGB or #RRGGBB format, e.g. #FF0000). Invalid formats will be rejected. |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Add Storage Mount

`POST https://api.paperoffice.ai/latest/storage_mounts/add`

Add Storage Mount Create a new storage mount connection. Required: name, host Optional: connector_type sftp|ftp|ftps|smb|webdav|s3, port, username, password, ssh_key, base_path Response: json { "status": "success", "message": "MOUNT_CREATED", "data": { "mount_id": 123, "name": "Office NAS" } }

**Tool-ID:** `po_storage_mounts_add` • **Cost:** 10 credits • **MCP:** `po_storage_mounts_add` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Name the Storage Mounts (required field). |
| `host` | string | No | Hostname or IP-address the Servers. |
| `connector_type` | string | No | type the Speicheranbindung. (allowed: sftp, s3, azure_blob, webdav, google_drive, onedrive, dropbox, box, imap) (default: "sftp") |
| `mount_purpose` | string | Yes | Zweck the Mounts: 'byos' (Bring Your Own Storage) or 'connector' (Datensource). required field, after creation unveraenthelich. (allowed: byos, connector) |
| `description` | string | No | description the Mounts. |
| `port` | integer | No | Port (Default: 22 for SFTP, 443 for S3/WebDAV, 993 for IMAP). |
| `username` | string | No | Username for the authentication. |
| `password` | string | No | Password (is stored encrypted). |
| `ssh_key` | string | No | SSH Private Key (is stored encrypted). |
| `api_token` | string | No | API-Token (is stored encrypted). |
| `base_path` | string | No | Basispfad on the Remote-Server. No '.' Segmente allowed. (default: "\/") |
| `encryption_key` | string | No | Encryption Password for BYOS Mounts (Mandatory when mount_purpose='byos'). WARNING: Irreversible in case of loss! |
| `connection_options` | object | No | Additional Verbindungsoptionen as JSON object (e.g. S3-Region, IMAP-folder). |
| `icon_url` | string | No | URL for a Userdefiniertes Icon. |

**Example Response:**

```json
{
    "processing_time": "example",
    "mount_id": "example",
    "type": "example",
    "status": "success"
}
```

### Batch-process documents (AI-DMS)

`POST https://api.paperoffice.ai/latest/documents/document-batch-process`

Triggers AI-DMS processing for multiple documents simultaneously. Max 50 POFIDs per batch. Each document is processed asynchronously via OCR, Entity Extraction, Classification, etc.

**Tool-ID:** `po_documents_batch_process` • **Cost:** 10 credits • **MCP:** `po_documents_batch_process` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofids` | array | Yes | Array of POFIDs to process (max 50) |
| `ai_dms_tier` | string | No | AI-DMS processing tier: basic (OCR + classification), premium (+ entity extraction), ultra (+ deep analysis) (allowed: basic, premium, ultra) (default: "basic") |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "ai_dms_tier": "example",
    "queued": [
        {
            "pofid": "pofid_01HXYZABC12345",
            "file_name": "example.pdf",
            "status": "success",
            "was_reset": true
        }
    ],
    "queued_count": 1,
    "reset_count": 1,
    "not_found": [
        "example"
    ],
    "not_found_count": 1,
    "errors": [
        {
            "pofid": "pofid_01HXYZABC12345",
            "file_name": "example.pdf",
            "error": "example"
        }
    ],
    "error_count": 1,
    "processing_time": "example"
}
```

### Browse storage mount files

`GET https://api.paperoffice.ai/latest/storage_mounts/browse`

Browse files and directories on a storage mount. Returns file listing with metadata (size, modified date, type).

**Tool-ID:** `po_storage_mounts_browse` • **Cost:** Free • **MCP:** `po_storage_mounts_browse` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | Yes | ID of the storage mount to browse |
| `path` | string | No | Path to browse. Relative paths are resolved against mount base_path. Use / for root. |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "storage_mounts___browse",
        "app": "storage_mounts",
        "action": "browse",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "mount_id": "1",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "35.97ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Check for duplicate documents

`POST https://api.paperoffice.ai/latest/documents/duplicate-check`

Check if a document with the same SHA-256 hash already exists.

**Tool-ID:** `po_documents_duplicate_check` • **Cost:** Free • **MCP:** `po_documents_duplicate_check` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_hash` | string | Yes | SHA-256 Hash the file (Required) |
| `workspace_id` | integer | No | Optional: on Workspace einschraenken |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Copy document

`POST https://api.paperoffice.ai/latest/documents/document-copy`

Copy a document to another workspace.

**Tool-ID:** `po_documents_copy` • **Cost:** 10 credits • **MCP:** `po_documents_copy` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID of the document to copy |
| `target_workspace_id` | integer | Yes | ID of the target workspace, where the document should be copied to |
| `locale` | string | No | Locale |
| `new_file_name` | string | No | New file name |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "locale": "en_US",
    "original": {
        "pofid": "pofid_01HXYZABC12345",
        "file_name": "example.pdf",
        "workspace_id": 12345
    },
    "copy": {
        "documents_id": 12345,
        "pofid": "pofid_01HXYZABC12345",
        "file_name": "example.pdf",
        "workspace_id": 12345,
        "workspace_name": "example"
    },
    "processing_time": "example"
}
```

### Create Document Comment

`POST https://api.paperoffice.ai/latest/documents/document-comment-create`

Create a comment or response to a document.

**Tool-ID:** `po_documents_comments_create` • **Cost:** Free • **MCP:** `po_documents_comments_create` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID |
| `content` | string | Yes | Comment text (Required) |
| `parent_id` | integer | No | Parent comment ID for reply (optional) |
| `page_number` | integer | No | pagesnummer (optional) |
| `anchor_text` | string | No | Ankertext in the Document (optional) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Create Document Note

`POST https://api.paperoffice.ai/latest/documents/document-note-create`

Add a new note to a document.

**Tool-ID:** `po_documents_notes_create` • **Cost:** Free • **MCP:** `po_documents_notes_create` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID |
| `content` | string | Yes | note-content (Required) |
| `title` | string | No | Optional title |
| `category` | string | No | category (default: general) (allowed: general, review, legal, technical, financial, internal) |
| `is_pinned` | integer | No | Pin note to top (0 = no, 1 = yes, default: 0) (allowed: 0, 1) |
| `is_private` | integer | No | Private note visible only to you (0 = no, 1 = yes, default: 0) (allowed: 0, 1) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Create storage mount directory

`POST https://api.paperoffice.ai/latest/storage_mounts/mkdir`

Create a new directory on a storage mount. Specify the mount ID and the path for the new directory.

**Tool-ID:** `po_storage_mounts_mkdir` • **Cost:** Free • **MCP:** `po_storage_mounts_mkdir` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | Yes | ID of the storage mount |
| `folder_name` | string | Yes | Name of the new folder (no special characters) |
| `path` | string | No | Parent path where the folder will be created (relative to base_path) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Create storage mount mirror

`POST https://api.paperoffice.ai/latest/storage_mounts/mirrors-add`

Add a new mirror target for a storage mount. Configure destination, sync interval, and filter rules.

**Tool-ID:** `po_storage_mounts_mirrors_create` • **Cost:** Free • **MCP:** `po_storage_mounts_mirrors_create` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `source_mount_id` | integer | Yes | Source mount ID (data origin) |
| `target_mount_id` | integer | Yes | Target mount ID (mirror destination) |
| `sync_mode` | string | No | Synchronization mode (allowed: realtime, scheduled, manual) (default: "realtime") |
| `priority` | integer | No | Mirror priority (lower = higher priority) (default: 0) |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Delete document

`DELETE https://api.paperoffice.ai/latest/documents/document-delete`

Deletes a document (soft-delete). The document is marked as deleted.

**Tool-ID:** `po_documents_delete` • **Cost:** 10 credits • **MCP:** `po_documents_delete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID |
| `share_context` | string | No | Share context |
| `mode` | string | No | Mode |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "deleted_count": 1,
    "not_found_count": 1,
    "error_count": 1,
    "deleted_documents": [
        {
            "pofid": "pofid_01HXYZABC12345",
            "file_name": "example.pdf",
            "documents_id": 12345,
            "workspace_id": 12345
        }
    ],
    "cleanup_queued": 1,
    "mode": "trash",
    "not_found_documents": [
        "example"
    ],
    "deleted_folders": [
        "example"
    ],
    "processing_time": "example"
}
```

### Delete Document Comment

`POST https://api.paperoffice.ai/latest/documents/document-comment-delete`

Own comment delete (incl. replies).

**Tool-ID:** `po_documents_comments_delete` • **Cost:** Free • **MCP:** `po_documents_comments_delete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `comment_id` | integer | Yes | ID of the comment to delete |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Delete Document Note

`POST https://api.paperoffice.ai/latest/documents/document-note-delete`

note delete (Soft Delete, only own).

**Tool-ID:** `po_documents_notes_delete` • **Cost:** Free • **MCP:** `po_documents_notes_delete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `note_id` | integer | Yes | ID of the note to delete |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Delete Storage Mount

`POST https://api.paperoffice.ai/latest/storage_mounts/delete`

Delete Storage Mount ⚠️ Cannot delete mounts with active connectors.

**Tool-ID:** `po_storage_mounts_delete` • **Cost:** 10 credits • **MCP:** `po_storage_mounts_delete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | No | Parameter: mount_id |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "data": {
        "mount_id": 12345
    },
    "processing_time": "example"
}
```

### Delete storage mount mirror

`POST https://api.paperoffice.ai/latest/storage_mounts/mirrors-remove`

Remove a mirror configuration from a storage mount. Stops future syncs but does not delete mirrored data.

**Tool-ID:** `po_storage_mounts_mirrors_delete` • **Cost:** Free • **MCP:** `po_storage_mounts_mirrors_delete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mirror_id` | integer | Yes | Mirror ID to remove |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Edit document fields

`POST https://api.paperoffice.ai/latest/documents/document-edit/{pofid}`

Sets or modifies a document's meta-fields via short alias keys.

**Tool-ID:** `po_documents_edit` • **Cost:** Free • **MCP:** `po_documents_edit` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID |
| `fields` | object | Yes | Key-Value-pairs with Alias-Keys (document_type, senthe_name, total_amount, etc.) or nativen __-Pfathe |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "updated": true,
    "updated_at": "2026-04-16T10:00:00Z"
}
```

### Empty document trash

`POST https://api.paperoffice.ai/latest/documents/trash-empty`

Empty Trash (permanently remove all deleted documents).

**Tool-ID:** `po_documents_trash_empty` • **Cost:** Free • **MCP:** `po_documents_trash_empty` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | No | Optional: Only Trash a Workspaces empty |
| `confirm` | boolean | Yes | Confirmation required (must be true sa) |

**Example Response:**

```json
{
    "force_deleted_count": 0,
    "message": "Trash is already empty",
    "processing_time": "33.7ms",
    "status": "success"
}
```

### Get document details

`GET https://api.paperoffice.ai/latest/documents/document-get/{pofid}`

Returns detailed metadata of a document.

**Tool-ID:** `po_documents_get` • **Cost:** 10 credits • **MCP:** `po_documents_get` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID |
| `share_context` | string | No | Share context |

### Get Document Lifecycle

`GET https://api.paperoffice.ai/latest/documents/document-lifecycle-get`

Get the current lifecycle status of a document, including allowed transitions.

**Tool-ID:** `po_documents_lifecycle_get` • **Cost:** Free • **MCP:** `po_documents_lifecycle_get` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID |

### Get document OCR text

`GET https://api.paperoffice.ai/latest/documents/ocr-get`

Returns the OCR-extracted text of a document. Contains text per page with confidence scoring.

**Tool-ID:** `po_documents_ocr_get` • **Cost:** 10 credits • **MCP:** `po_documents_ocr_get` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File Document ID |
| `locale` | string | No | Locale |
| `page` | integer | No | Page |
| `include_bounding_boxes` | boolean | No | Include bounding boxes |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "documents___ocr_get",
        "app": "documents",
        "action": "ocr-get",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "9.41ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get storage mount access logs

`GET https://api.paperoffice.ai/latest/storage_mounts/logs`

View access and operation logs for storage mounts. Returns recent log entries with timestamps, operation types, and affected paths.

**Tool-ID:** `po_storage_mounts_logs` • **Cost:** Free • **MCP:** `po_storage_mounts_logs` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | Yes | ID of the storage mount |
| `limit` | integer | No | Number of log entries to return (max 100) (default: 50) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "storage_mounts___logs",
        "app": "storage_mounts",
        "action": "logs",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "mount_id": "1",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "15.91ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get storage mount details

`GET https://api.paperoffice.ai/latest/storage_mounts/get`

Get Mount Details Get full details including linked connectors.

**Tool-ID:** `po_storage_mounts_get` • **Cost:** 10 credits • **MCP:** `po_storage_mounts_get` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | No | Parameter: mount_id |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "storage_mounts___get",
        "app": "storage_mounts",
        "action": "get",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "17.36ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get storage mount health status

`GET https://api.paperoffice.ai/latest/storage_mounts/health`

Check health status of all configured storage mounts. Returns availability, latency, and disk usage per mount.

**Tool-ID:** `po_storage_mounts_health` • **Cost:** Free • **MCP:** `po_storage_mounts_health` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "storage_mounts___health",
        "app": "storage_mounts",
        "action": "health",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "16.94ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get trash settings

`GET https://api.paperoffice.ai/latest/documents/trash-settings`

Get or modify trash settings.

**Tool-ID:** `po_documents_trash_settings` • **Cost:** Free • **MCP:** `po_documents_trash_settings` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `retention_days` | integer | No | Optional: Aufbewahrungsdauer in daysn setzen |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "documents___trash_settings",
        "app": "documents",
        "action": "trash-settings",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.34ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List Deleted Documents (Trash)

`POST https://api.paperoffice.ai/latest/documents/trash-list`

Displays all soft-deleted documents in the trash. Paginated with days_remaining and is_restorable. Optionally filterable by Workspace.

**Tool-ID:** `po_documents_trash_list` • **Cost:** 10 credits • **MCP:** `po_documents_trash_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | No | Optional: Filter by workspace |
| `page` | integer | No | Page number (default: 1) (default: 1) |
| `pro_page` | integer | No | Items per page (10-200, default: 50) (default: 50) |

**Example Response:**

```json
{
    "page": 1,
    "pages": 1,
    "per_page": 50,
    "processing_time": "12.31ms",
    "retention_days": 30,
    "status": "success",
    "total": 0,
    "total_size_bytes": 0,
    "total_size_human": "0 MB",
    "trash_items": []
}
```

### List Document Comments

`GET https://api.paperoffice.ai/latest/documents/document-comments`

List document comments as a thread structure.

**Tool-ID:** `po_documents_comments_list` • **Cost:** Free • **MCP:** `po_documents_comments_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID |
| `include_resolved` | string | No | Also show resolved comments (default: 0) (allowed: 0, 1) |
| `page_number` | integer | No | Only comments for these page (optional) |

### List Document Notes

`GET https://api.paperoffice.ai/latest/documents/document-notes`

List all notes of a document.

**Tool-ID:** `po_documents_notes_list` • **Cost:** Free • **MCP:** `po_documents_notes_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID |
| `include_private` | string | No | Include private notes of OTHER users (default: false). Your own private notes are always visible regardless of this setting. (allowed: 0, 1) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "documents___document_notes",
        "app": "documents",
        "action": "document-notes",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.77ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List Document Tags

`GET https://api.paperoffice.ai/latest/documents/document-tags`

List all tags of a document.

**Tool-ID:** `po_documents_tags_list` • **Cost:** Free • **MCP:** `po_documents_tags_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "documents___document_tags",
        "app": "documents",
        "action": "document-tags",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "9.05ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List Legal Holds

`GET https://api.paperoffice.ai/latest/documents/document-legal-holds-list`

List Legal Holds (per Workspace or Document).

**Tool-ID:** `po_documents_legal_holds_list` • **Cost:** Free • **MCP:** `po_documents_legal_holds_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | No | Workspace ID to filter holds. Omit both workspace_id and pofid to list ALL legal holds account-wide (compliance mode). |
| `pofid` | string | No | PaproOffice File ID to filter holds for a specific document. Omit both workspace_id and pofid for account-wide listing. |
| `active_only` | string | No | Only active Holds (default: 1) (allowed: 0, 1) |

**Example Response:**

```json
{
    "holds": [],
    "processing_time": "18.31ms",
    "scope": "account_global",
    "status": "success",
    "total": 0
}
```

### List storage mount mirrors

`GET https://api.paperoffice.ai/latest/storage_mounts/mirrors-list`

List all configured mirror targets for storage mounts. Shows mirror destinations, sync status, and last sync time.

**Tool-ID:** `po_storage_mounts_mirrors_list` • **Cost:** Free • **MCP:** `po_storage_mounts_mirrors_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | Yes | Source mount ID to list mirrors for |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "storage_mounts___mirrors-list",
        "app": "storage_mounts",
        "action": "mirrors-list",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "mount_id": "1",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "17.16ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List storage mounts

`GET https://api.paperoffice.ai/latest/storage_mounts/list`

List Storage Mounts Get all storage mount connections. Response: json { "status": "success", "data": { "mounts": { "mount_id": 1, "name": "Office NAS", "connector_type": "sftp", "host": "nas.example.com", "port": 22, "base_path": "/documents", "is_active": true, "connector_count": 2 } , "total": .

**Tool-ID:** `po_storage_mounts_list` • **Cost:** 10 credits • **MCP:** `po_storage_mounts_list` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "storage_mounts___list",
        "app": "storage_mounts",
        "action": "list",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "17.06ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Move document

`POST https://api.paperoffice.ai/latest/documents/document-move`

Move a document to another workspace.

**Tool-ID:** `po_documents_move` • **Cost:** 10 credits • **MCP:** `po_documents_move` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID of the document to move |
| `target_workspace_id` | integer | Yes | ID of the target workspace, where the document should be moved to |
| `locale` | string | No | Locale |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "locale": "en_US",
    "document": {
        "pofid": "pofid_01HXYZABC12345",
        "file_name": "example.pdf",
        "old_workspace_id": 12345,
        "new_workspace_id": 12345,
        "new_workspace_name": "example"
    },
    "processing_time": "example"
}
```

### Place legal hold

`POST https://api.paperoffice.ai/latest/documents/document-legal-hold`

Place document under Legal Hold (deletion lock for legal retention).

**Tool-ID:** `po_documents_legal_holds_create` • **Cost:** Free • **MCP:** `po_documents_legal_holds_create` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID |
| `reason` | string | Yes | Grand for Legal Hold (Mandatory, e.g., lawsuit, audit) |
| `reference` | string | No | Optional reference (Aktencharacters, Case-ID) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Release legal hold

`POST https://api.paperoffice.ai/latest/documents/document-legal-hold-release`

Release a legal hold (document becomes deletable again).

**Tool-ID:** `po_documents_legal_hold_release` • **Cost:** Free • **MCP:** `po_documents_legal_hold_release` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `hold_id` | integer | Yes | Legal hold ID (Required) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Remove Document day

`POST https://api.paperoffice.ai/latest/documents/document-tag-remove`

Remove the day from a document.

**Tool-ID:** `po_documents_tags_delete` • **Cost:** Free • **MCP:** `po_documents_tags_delete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID |
| `tag_name` | string | No | Name of the day to delete (REQUIRED if tag_id not provided) |
| `tag_id` | integer | No | ID of the day to delete (REQUIRED if tag_name not provided) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Rename document

`POST https://api.paperoffice.ai/latest/documents/document-rename`

Rename a document. The original extension is always preserved. Path separators (/, \, .) are rejected. Special characters are removed, leading dots are deleted. Maximum length: 255 characters.

**Tool-ID:** `po_documents_rename` • **Cost:** 10 credits • **MCP:** `po_documents_rename` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | Document POFID to rename |
| `new_file_name` | string | Yes | New file name (extension preserved if omitted) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "pofid": "pofid_01HXYZABC12345",
    "new_name": "example",
    "processing_time": "example",
    "document": "example",
    "old_file_name": "example",
    "new_file_name": "example",
    "workspace_id": "ws_01HXYZ1234"
}
```

### Resolve Document Comment

`POST https://api.paperoffice.ai/latest/documents/document-comment-resolve`

Mark the comment thread as completed or reopen it.

**Tool-ID:** `po_documents_comments_resolve` • **Cost:** Free • **MCP:** `po_documents_comments_resolve` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `comment_id` | integer | Yes | Root comment ID (not a reply) |
| `resolved` | boolean | No | true = as erledigt mark, false = wiethe open (default: true) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Restore Document from Trash

`POST https://api.paperoffice.ai/latest/documents/document-restore`

Restore one or more soft-deleted documents from the trash. Also supports document folders (.podf). Only restorable while phase=pending (not permanently deleted).

**Tool-ID:** `po_documents_restore` • **Cost:** 10 credits • **MCP:** `po_documents_restore` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | Array | Yes | POFID or array of POFIDs to restore |
| `target_workspace_id` | integer | No | Optional: Restore to this workspace instead of original |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "pofid": "pofid_01HXYZABC12345",
    "processing_time": "example",
    "restored_count": "example",
    "failed_count": "example",
    "restored_documents": "example",
    "failed_documents": "example"
}
```

### Run storage mount health check

`POST https://api.paperoffice.ai/latest/storage_mounts/health-check-now`

Trigger an immediate health check on a storage mount. Returns real-time connectivity, disk space, and I/O performance metrics.

**Tool-ID:** `po_storage_mounts_health_check_now` • **Cost:** Free • **MCP:** `po_storage_mounts_health_check_now` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | No | Specific mount ID to check. Omit to check ALL active mounts. |

**Example Response:**

```json
{
    "data": {
        "check_results": [],
        "health_data": [],
        "checked_count": 0
    },
    "message": "HEALTH_CHECK_COMPLETE",
    "processing_time": "19.93ms",
    "status": "success",
    "timestamp": "2026-04-19 07:00:24"
}
```

### Search documents (full-text)

`GET https://api.paperoffice.ai/latest/documents/document-search`

Search documents by full-text search terms.

**Tool-ID:** `po_documents_search` • **Cost:** 10 credits • **MCP:** `po_documents_search` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | Search term for the Documentsnsuche (full text, Semantisch or Hybrid) |
| `workspace_id` | integer | Yes | Workspace ID for the Documentsnsuche |
| `limit` | integer | No | Maximum number results (Standard: 20, Max: 100) (default: 20) |
| `locale` | string | No | Locale |
| `mode` | string | No | Mode |
| `field_key` | string | No | Field key |
| `page` | integer | No | Page |
| `workspace_ids` | array | No | Alternative: Array of Workspace IDs for the Search |
| `include_meta_fields` | boolean | No | Include meta fields |
| `include_ocr_preview` | boolean | No | Include ocr preview |
| `similarity_threshold` | number | No | Similarity threshold |
| `multi_vector` | string | No | Multi vector |
| `vector_weight` | number | No | Vector weight |
| `bm25_weight` | number | No | Bm25 weight |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "documents___document_search",
        "app": "documents",
        "action": "document-search",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "12.21ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### day Autocomplete

`GET https://api.paperoffice.ai/latest/documents/tag-autocomplete`

Search tags for autocomplete (cross-workspace).

**Tool-ID:** `po_documents_tags_autocomplete` • **Cost:** Free • **MCP:** `po_documents_tags_autocomplete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `q` | string | Yes | Search term (mind. 1 characters) |
| `workspace_id` | integer | No | Optional: on Workspace einschraenken |
| `limit` | integer | No | Max. results (default: 20, max: 50) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "documents___tag_autocomplete",
        "app": "documents",
        "action": "day-autocomplete",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "9.24ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Test storage mount connection

`POST https://api.paperoffice.ai/latest/storage_mounts/test`

Test Connection Test if the storage mount is reachable. Can also test new credentials without saving: json { "connector_type": "sftp", "host": "nas.example.com", "port": 22, "username": "user", "password": "pass" }

**Tool-ID:** `po_storage_mounts_test` • **Cost:** 10 credits • **MCP:** `po_storage_mounts_test` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | No | Parameter: mount_id |

**Example Response:**

```json
{
    "processing_time": "example",
    "connected": true,
    "message": "Operation completed successfully",
    "latency_ms": 150,
    "status": "success"
}
```

### Toggle storage mount mirror

`POST https://api.paperoffice.ai/latest/storage_mounts/mirrors-toggle`

Enable or disable a storage mount mirror without deleting the configuration. Useful for temporary maintenance.

**Tool-ID:** `po_storage_mounts_mirrors_toggle` • **Cost:** Free • **MCP:** `po_storage_mounts_mirrors_toggle` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mirror_id` | integer | Yes | Mirror ID to toggle |
| `is_active` | integer | Yes | 1 = active, 0 = paused (allowed: 0, 1) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Transition document lifecycle

`POST https://api.paperoffice.ai/latest/documents/document-lifecycle-transition`

Change the lifecycle status of a document. Only allowed transitions are possible.

**Tool-ID:** `po_documents_lifecycle_transition` • **Cost:** Free • **MCP:** `po_documents_lifecycle_transition` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID |
| `new_state` | string | Yes | new lifecycle status (allowed: draft, in_review, approved, published, archived, expired, suproseded) |
| `comment` | string | No | Optional comment for translation |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Update Document Comment

`POST https://api.paperoffice.ai/latest/documents/document-comment-update`

Update (edit) an existing comment authored by the current user.

**Tool-ID:** `po_documents_comments_update` • **Cost:** Free • **MCP:** `po_documents_comments_update` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `comment_id` | integer | Yes | Comment ID |
| `content` | string | Yes | new Comment text |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Update Document Note

`POST https://api.paperoffice.ai/latest/documents/document-note-update`

existing note update (only own).

**Tool-ID:** `po_documents_notes_update` • **Cost:** Free • **MCP:** `po_documents_notes_update` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `note_id` | integer | Yes | Note ID (Required) |
| `title` | string | No | New title |
| `content` | string | No | New content |
| `category` | string | No | new category (allowed: general, review, legal, technical, financial, internal) |
| `is_pinned` | integer | No | Anheften/Loesen (allowed: 0, 1) |
| `is_private` | integer | No | Privat/Public (allowed: 0, 1) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Update Storage Mount

`POST https://api.paperoffice.ai/latest/storage_mounts/update`

Update Storage Mount Modify an existing storage mount. Required: mount_id Optional: Any field to update

**Tool-ID:** `po_storage_mounts_update` • **Cost:** 10 credits • **MCP:** `po_storage_mounts_update` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | No | Parameter: mount_id |
| `name` | string | No | Parameter: name |
| `is_active` | boolean | No | Parameter: is_active |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "data": {
        "mount_id": 12345
    },
    "processing_time": "example"
}
```

### Upload document

`POST https://api.paperoffice.ai/latest/documents/document-put`

Uploads a new document and saves it encrypted.

**Tool-ID:** `po_documents_update` • **Cost:** 10 credits • **MCP:** `po_documents_update` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file` | string | Yes | Hochzuladende file (multipart/form-data, binary) |
| `workspace_id` | integer | Yes | target workspace ID for the hochgelathee Document |
| `workspace_name` | string | No | Workspace name |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "results": [
        {
            "status": "success",
            "pofid": "pofid_01HXYZABC12345",
            "documents_id": 12345,
            "filename": "example.pdf",
            "size": 1024,
            "total_pages": 1,
            "message": "Operation completed successfully"
        }
    ],
    "workspace_id": 12345,
    "workspace_name": "example",
    "workflow_import": {
        "source_job_id": "example",
        "documents_imported": 1
    },
    "processing_time": "example"
}
```

### Get document summary

`POST https://api.paperoffice.ai/latest/documents/document-summary`

Compact summary of all Document Intelligence data. An endpoint for all key metrics and API links.

**Tool-ID:** `po_summary_stats_get_document_summary` • **Cost:** 10 credits • **MCP:** `po_summary_stats_get_document_summary` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_id` | integer | Yes | numeric Document ID (documents_id). Passed as URL parameter (/summary/{document_id}). |

### Get global statistics

`POST https://api.paperoffice.ai/latest/documents/global-stats`

Global Document Intelligence Statistics. Overview of all processed documents, entities, embeddings, etc.

**Tool-ID:** `po_summary_stats_get_global_stats` • **Cost:** 10 credits • **MCP:** `po_summary_stats_get_global_stats` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | string | No | Optional: Filter by workspace |

### Get vision data

`POST https://api.paperoffice.ai/latest/documents/vision-data`

Vision-extracted data Ultra-Tier. Includes: - Tables - Structured table data with rows/columns - charts - Recognized charts with data - Form Fields - Form fields with values - barcodes - QR codes and barcodes - Layout - Document structure Headers, Paragraphs, etc.

**Tool-ID:** `po_vision_get_vision_data` • **Cost:** 10 credits • **MCP:** `po_vision_get_vision_data` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `include` | string | No | all, tables, charts, forms, barcodes, layout |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9439
    },
    "job": {
        "api_job_name": "documents___vision_data",
        "app": "documents",
        "action": "vision-data",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "7.76ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Check access

`POST https://api.paperoffice.ai/latest/documents/workspace-access-check`

Check Workspace Access Verify if the current user session has access to a specific workspace. Returns: Access status and session details.

**Tool-ID:** `po_workspaces_security_check_access` • **Cost:** Free • **MCP:** `po_workspaces_security_check_access` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | string | No | Required: Workspace ID to check access for |

**Example Response:**

```json
{
    "processing_time": "example",
    "has_access": true,
    "requires_password": true,
    "requires_code": true,
    "status": "success"
}
```

### Create workspace

`POST https://api.paperoffice.ai/latest/documents/workspace-create`

Create New Workspace Create a workspace to organize documents. Optional metadata: - data_contact: Contact information - data_address: Address information

**Tool-ID:** `po_workspaces_create` • **Cost:** Free • **MCP:** `po_workspaces_create` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Workspace name (required, must not be empty). |
| `description` | string | No | description the workspace. |
| `type` | string | No | type the workspace. (default: "folder") |
| `workspace_tier` | string | No | Security level: standard, confithetial (confidential) or compliance (highest level). (allowed: standard, confidential, compliance) (default: "standard") |
| `is_revision_secure` | boolean | No | revision safety enable (WORM-protection). Einmal activates, not deaktivierbar. Erforthet PaproOffice EU Cloud. (default: false) |
| `retention_years` | integer | No | Retention period in years (Standard: 10 years, GoBD-compliant). (default: 10) |
| `ai_dms_mode` | string | No | AI-DMS Verarattungsmodus: disabled (from), basic, premium or ultra. (allowed: disabled, basic, premium, ultra) (default: "disabled") |
| `storage_mode` | string | No | Storage mode: 'cloud' (PaproOffice EU Cloud) or 'byos' (Bring Your Own Storage). After creation, not deletable. (allowed: cloud, byos) (default: "cloud") |
| `storage_mount_id` | integer | No | Identify the Storage Mounts for BYOS Mode. |
| `storage_mount_path` | string | No | Path on the Storage Mount for BYOS mode. |
| `default_locale` | string | No | Default language/region in the Format 'de:DE', 'en:US' etc. |
| `image` | string | No | Bild-URL the workspace. |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. (default: 500) |
| `is_default` | boolean | No | Mark as standard workspace. |
| `is_stealth` | boolean | No | Workspace in the Stealth-Modus (versteckt). |
| `is_archived` | boolean | No | Archive workspace. |
| `workspace_password` | string | No | Password for the workspace access. |
| `color` | string | No | Farbcode the workspace. |
| `icon` | string | No | Icon the workspace. |
| `tags` | array | No | Tags for the workspace. |
| `contact_salutation` | string | No | Anrede the Ansprechpartners. |
| `contact_firstname` | string | No | Vorname the Ansprechpartners. |
| `contact_lastname` | string | No | Nachname the Ansprechpartners. |
| `contact_email` | string | No | email the Ansprechpartners. |
| `contact_phone` | string | No | phone the Ansprechpartners. |
| `company_name` | string | No | company name. |
| `address_street` | string | No | Strasse. |
| `address_zip` | string | No | Postleitzahl. |
| `address_city` | string | No | Stadt. |
| `address_country` | string | No | Land. |
| `metadata` | object | No | Additional metadata as JSON object. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "id": 12345,
    "workspace_tier": "standard",
    "processing_time": "example"
}
```

### Delete workspace

`POST https://api.paperoffice.ai/latest/documents/workspace-delete`

Delete Workspace Warning: This will also delete all documents in the workspace!

**Tool-ID:** `po_workspaces_delete` • **Cost:** Free • **MCP:** `po_workspaces_delete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | Yes | ID of the workspace to delete. |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "documents_queued": 1,
    "processing_time": "example"
}
```

### List workspaces

`GET https://api.paperoffice.ai/latest/documents/workspaces-list`

List All Workspaces Get all workspaces for the authenticated account. Response includes: - id, name, description - type standard/project - status active/inactive - is_default flag

**Tool-ID:** `po_workspaces_list` • **Cost:** 10 credits • **MCP:** `po_workspaces_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `locale` | string | No | Response language: de_DE, en_US, es_ES, fr_FR, it_IT, pt_PT |

**Example Response:**

```json
{
    "count": 3,
    "processing_time": "10.42ms",
    "result": [
        {
            "id": 8,
            "name": "test",
            "description": "",
            "type": "folder",
            "status": "active",
            "is_default": 0,
            "is_stealth": 0,
            "is_archived": 0,
            "image": "",
            "priority": 500,
            "data_contact": "{\"salutation\":\"\",\"firstname\":\"\",\"lastname\":\"\",\"position\":\"\",\"department\":\"\",\"email\":\"\",\"phone\":\"\",\"mobile\":\"\",\"notes\":\"\",\"company_name\":\"\",\"company_vatid\":\"\",\"company_taxnr\":\"\"}",
            "data_address": "{\"street\":\"\",\"extra\":\"\",\"zip\":\"\",\"city\":\"\",\"region\":\"\",\"country\":\"\"}",
            "data_settings": "{\"color\":null,\"icon\":null,\"tags\":[],\"custom_label\":null,\"revision_secure\":false,\"workspace_tier\":\"standard\",\"retention_years\":10,\"reference\":\"\",\"external_id\":\"\",\"cost_center\":\"\",\"is_stealth\":false,\"is_archived\":false,\"password_enabled\":false,\"sms_enabled\":false,\"sms_phone\":\"\",\"dual_auth_enabled\":false,\"dual_auth_phone_1\":\"\",\"dual_auth_phone_2\":\"\"}",
            "metadata": null,
            "is_revision_secure": 0,
            "revision_retention_days": 3650,
            "revision_secure_since": null,
            "ai_dms_mode": "disabled",
            "storage_mount_id": null,
            "storage_mount_path": null,
            "storage_mode": "cloud",
            "auto_locked": 0,
            "auto_locked_reason": null,
            "default_locale": null,
            "created_at": "2026-03-19 13:51:14",
            "updated_at": "2026-04-08 07:00:14",
            "workspace_tier": "basic",
            "ai_dms_max_pages": null,
            "contact_firstname": "",
            "contact_lastname": "",
            "contact_email": "",
            "contact_phone": "",
            "address_street": "",
            "address_zip": "",
            "address_city": "",
            "address_country": "",
            "tier": "basic",
            "security_tier": "basic",
            "retention_years": 10,
            "reference": "",
            "external_id": "",
            "cost_center": "",
            "color": "",
            "icon": "",
            "tags": [],
            "password_enabled": false,
            "sms_enabled": false,
            "sms_phone": "",
            "dual_auth_enabled": false,
            "dual_auth_phone_1": "",
            "dual_auth_phone_2": "",
            "session_max_duration": 480,
            "session_inactivity_timeout": 0,
            "contact_salutation": "",
            "contact_position": "",
            "contact_department": "",
            "contact_mobile": "",
            "contact_notes": "",
            "company_name": "",
            "company_vatid": "",
            "company_taxnr": "",
            "address_extra": "",
            "address_region": "",
            "stats": {
                "doc_count": 0,
                "storage_size": "0 MB"
            }
        },
        {
            "id": 5,
            "name": "test",
            "description": "",
            "type": "folder",
            "status": "active",
            "is_default": 0,
            "is_stealth": 0,
            "is_archived": 0,
            "image": "",
            "priority": 500,
            "data_contact": "{\"salutation\":\"\",\"firstname\":\"\",\"lastname\":\"\",\"position\":\"\",\"department\":\"\",\"email\":\"\",\"phone\":\"\",\"mobile\":\"\",\"notes\":\"\",\"company_name\":\"\",\"company_vatid\":\"\",\"company_taxnr\":\"\"}",
            "data_address": "{\"street\":\"\",\"extra\":\"\",\"zip\":\"\",\"city\":\"\",\"region\":\"\",\"country\":\"\"}",
            "data_settings": "{\"color\":null,\"icon\":null,\"tags\":[],\"custom_label\":null,\"revision_secure\":false,\"workspace_tier\":\"standard\",\"retention_years\":10,\"reference\":\"\",\"external_id\":\"\",\"cost_center\":\"\",\"is_stealth\":false,\"is_archived\":false,\"password_enabled\":false,\"sms_enabled\":false,\"sms_phone\":\"\",\"dual_auth_enabled\":false,\"dual_auth_phone_1\":\"\",\"dual_auth_phone_2\":\"\"}",
            "metadata": null,
            "is_revision_secure": 0,
            "revision_retention_days": 3650,
            "revision_secure_since": null,
            "ai_dms_mode": "disabled",
            "storage_mount_id": null,
            "storage_mount_path": null,
            "storage_mode": "cloud",
            "auto_locked": 0,
            "auto_locked_reason": null,
            "default_locale": null,
            "created_at": "2026-03-19 10:54:01",
            "updated_at": "2026-04-08 07:00:14",
            "workspace_tier": "basic",
            "ai_dms_max_pages": null,
            "contact_firstname": "",
            "contact_lastname": "",
            "contact_email": "",
            "contact_phone": "",
            "address_street": "",
            "address_zip": "",
            "address_city": "",
            "address_country": "",
            "tier": "basic",
            "security_tier": "basic",
            "retention_years": 10,
            "reference": "",
            "external_id": "",
            "cost_center": "",
            "color": "",
            "icon": "",
            "tags": [],
            "password_enabled": false,
            "sms_enabled": false,
            "sms_phone": "",
            "dual_auth_enabled": false,
            "dual_auth_phone_1": "",
            "dual_auth_phone_2": "",
            "session_max_duration": 480,
            "session_inactivity_timeout": 0,
            "contact_salutation": "",
            "contact_position": "",
            "contact_department": "",
            "contact_mobile": "",
            "contact_notes": "",
            "company_name": "",
            "company_vatid": "",
            "company_taxnr": "",
            "address_extra": "",
            "address_region": "",
            "stats": {
                "doc_count": 0,
                "storage_size": "0 MB"
            }
        },
        {
            "id": 2,
            "name": "Standard",
            "description": null,
            "type": "standard",
            "status": "active",
            "is_default": 1,
            "is_stealth": 0,
            "is_archived": 0,
            "image": "",
            "priority": 500,
            "data_contact": null,
            "data_address": null,
            "data_settings": null,
            "metadata": null,
            "is_revision_secure": 0,
            "revision_retention_days": 3650,
            "revision_secure_since": null,
            "ai_dms_mode": "disabled",
            "storage_mount_id": null,
            "storage_mount_path": null,
            "storage_mode": "cloud",
            "auto_locked": 0,
            "auto_locked_reason": null,
            "default_locale": "de:DE",
            "created_at": "2026-03-18 09:39:46",
            "updated_at": "2026-04-08 07:00:14",
            "workspace_tier": "basic",
            "ai_dms_max_pages": null,
            "contact_firstname": "",
            "contact_lastname": "",
            "contact_email": "",
            "contact_phone": "",
            "address_street": "",
            "address_zip": "",
            "address_city": "",
            "address_country": "",
            "tier": "basic",
            "security_tier": "basic",
            "retention_years": 10,
            "reference": "",
            "external_id": "",
            "cost_center": "",
            "color": "",
            "icon": "",
            "tags": [],
            "password_enabled": false,
            "sms_enabled": false,
            "sms_phone": "",
            "dual_auth_enabled": false,
            "dual_auth_phone_1": "",
            "dual_auth_phone_2": "",
            "session_max_duration": 480,
            "session_inactivity_timeout": 0,
            "contact_salutation": "",
            "contact_position": "",
            "contact_department": "",
            "contact_mobile": "",
            "contact_notes": "",
            "company_name": "",
            "company_vatid": "",
            "company_taxnr": "",
            "address_extra": "",
            "address_region": "",
            "stats": {
                "doc_count": 1,
                "storage_size": "0.16 MB"
            }
        }
    ]
}
```

### Update workspace

`POST https://api.paperoffice.ai/latest/documents/workspace-update`

Update Workspace Modify workspace name, description, status, or metadata.

**Tool-ID:** `po_workspaces_update` • **Cost:** Free • **MCP:** `po_workspaces_update` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | Yes | ID to update Workspaces (required field). |
| `name` | string | No | new Workspace name. |
| `description` | string | No | New description. |
| `workspace_tier` | string | No | Security level (only upgrade allowed, no Downgrade). (allowed: standard, confidential, compliance) |
| `is_revision_secure` | boolean | No | revision safety enable (einmalig, unwiderruflich). |
| `retention_years` | integer | No | Retention proiod in years. Increase allowed only for WORM only. |
| `ai_dms_mode` | string | No | AI-DMS Mode. In Aentheung, existing documents are retroactively age-planted. (allowed: disabled, basic, premium, ultra) |
| `default_locale` | string | No | Default language/region. |
| `workspace_password` | string | No | new Workspace password. |
| `status` | string | No | Workspace-Status. |
| `type` | string | No | Workspace-type. |
| `image` | string | No | Bild-URL. |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |
| `is_default` | boolean | No | Mark as standard. |
| `is_stealth` | boolean | No | Stealth-Modus. |
| `is_archived` | boolean | No | Archived. |
| `color` | string | No | Farbcode. |
| `icon` | string | No | Icon. |
| `tags` | array | No | Tags. |
| `contact_salutation` | string | No | Contact salutation |
| `contact_firstname` | string | No | Contact firstname |
| `contact_lastname` | string | No | Contact lastname |
| `contact_email` | string | No | Contact email |
| `contact_phone` | string | No | Contact phone |
| `company_name` | string | No | Company name |
| `address_street` | string | No | Address street |
| `address_zip` | string | No | Address zip |
| `address_city` | string | No | Address city |
| `address_country` | string | No | Address country |
| `metadata` | object | No | Additional metadata. |
| `password_enabled` | boolean | No | Enable or disable password protection. |
| `sms_enabled` | boolean | No | SMS-verification enable. |
| `sms_phone` | string | No | Phone number for SMS verification. |
| `dual_auth_enabled` | boolean | No | 2-persons-approval enable. |
| `dual_auth_phone_1` | string | No | Telefonnummer Person 1. |
| `dual_auth_phone_2` | string | No | Telefonnummer Person 2. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "workspace_tier": "standard",
    "ai_dms_backfill": {
        "documents_queued": 1,
        "documents_tier_updated": 1,
        "ai_dms_tier": "example",
        "source": "activation"
    },
    "processing_time": "example"
}
```

### Validate Workspace Storage Health

`POST https://api.paperoffice.ai/latest/documents/workspace-storage-health`

Check the storage status of a workspace: Cloud-Mode, BYOS-Health, Latency, Offline-Status, Auto-Lock Reason. Especially important for BYOD/BYOS workspaces with external storage.

**Tool-ID:** `po_workspaces_validate_storage` • **Cost:** 10 credits • **MCP:** `po_workspaces_validate_storage` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | Yes | Workspace ID to check |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9439
    },
    "job": {
        "api_job_name": "documents___workspace_storage_health",
        "app": "documents",
        "action": "workspace-storage-health",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "7.94ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

---

## Document AI — E-Signatures

### Cancel Signature Request

`POST https://api.paperoffice.ai/latest/signatures/cancel`

Cancel a signature request.

**Tool-ID:** `po_esignatures_cancel_signature_request` • **Cost:** 990 credits • **MCP:** `po_esignatures_cancel_signature_request` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signature_id` | string | No | Signature request ID (default: "") |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "cancelled": true,
            "signature_id": "example"
        }
    }
}
```

### Create Signature Request

`POST https://api.paperoffice.ai/latest/signatures/create`

Create a new signature request for a document

**Tool-ID:** `po_esignatures_create_signature_request` • **Cost:** 990 credits • **MCP:** `po_esignatures_create_signature_request` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_id` | string | No | ID of the document to sign (default: "") |
| `signers` | string | No | JSON Array the signers {email, name, orthe} (default: "") |
| `message` | string | No | message an the signer (default: "") |
| `level` | string | No | Signature level: SES, AES, QES (default: "SES") |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "signature_id": "example",
            "signing_url": "https://example.com/resource",
            "status": "pending",
            "signers": [
                []
            ],
            "created_at": "2026-04-16T10:00:00Z",
            "expires_at": "2026-04-16T10:00:00Z"
        }
    }
}
```

### Download eSignature Document

`GET https://api.paperoffice.ai/latest/signatures/download`

Download the signed document

**Tool-ID:** `po_esignatures_download_signed_document` • **Cost:** 10 credits • **MCP:** `po_esignatures_download_signed_document` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signature_id` | string | No | Signature request ID |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9730
    },
    "job": {
        "api_job_name": "signatures___download",
        "app": "signatures",
        "action": "download",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "12.23ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get signature details

`GET https://api.paperoffice.ai/latest/signatures/get`

Get details of a signature request.

**Tool-ID:** `po_esignatures_get_signature_details` • **Cost:** 10 credits • **MCP:** `po_esignatures_get_signature_details` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signature_id` | string | No | Signature request ID |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9730
    },
    "job": {
        "api_job_name": "signatures___get",
        "app": "signatures",
        "action": "get",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "10.86ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List signature requests

`GET https://api.paperoffice.ai/latest/signatures/list`

List all signature requests

**Tool-ID:** `po_esignatures_list_signature_requests` • **Cost:** 10 credits • **MCP:** `po_esignatures_list_signature_requests` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | No | Filter after signature-Status. (allowed: draft, pending, sent, completed, declined, expired, cancelled) |
| `page` | integer | No | {"page_number_for_pagination":"Page number for pagination."} (default: 1) |
| `limit` | integer | No | Number of results per page. (default: 20) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9730
    },
    "job": {
        "api_job_name": "signatures___list",
        "app": "signatures",
        "action": "list",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "10.4ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Send reminder

`POST https://api.paperoffice.ai/latest/signatures/remind`

Send a reminder to outstanding signers

**Tool-ID:** `po_esignatures_send_reminder` • **Cost:** 10 credits • **MCP:** `po_esignatures_send_reminder` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signature_id` | string | No | Signature request ID (default: "") |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "sent": true,
            "signature_id": "example"
        }
    }
}
```

### Cancel Signing Request

`POST https://api.paperoffice.ai/latest/signature_link/cancel_signing_request`

Cancel Signing Request Cancel a pending signing request. --- Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | signing_id | string | ✅ | Signing request ID | --- Response json { "success": true }

**Tool-ID:** `po_signature_links_cancel_signing_request` • **Cost:** 10 credits • **MCP:** `po_signature_links_cancel_signing_request` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `request_id` | string | Yes | ID to stornierenthe signature request |
| `reason` | string | No | cancellation reason |

**Example Response:**

```json
{
    "success": false,
    "error": "REQUEST_ID_REQUIRED"
}
```

### Check signing status

`GET https://api.paperoffice.ai/latest/signature_link/get_signing_status`

Check Signing Status Get current status of a signing request. --- Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | signing_id | string | ✅ | Signing request ID | --- Response json { "success": true, "status": "completed", "signed_at": "202.

**Tool-ID:** `po_signature_links_check_signing_status` • **Cost:** 10 credits • **MCP:** `po_signature_links_check_signing_status` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signing_id` | string | No | Query parameter: signing_id |

**Example Response:**

```json
{
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    },
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9630
    },
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "job": {
        "api_job_name": "signature_link___get_signing_status",
        "app": "signature_link",
        "action": "get_signing_status",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "rate_limited": true,
        "credits_billed": 0
    }
}
```

### Download Signing Link Document

`GET https://api.paperoffice.ai/latest/signature_link/download_signed_document`

Download Signed Document Download the completed signed document. --- Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | signing_id | string | ✅ | Signing request ID | --- Response Returns the signed PDF document.

**Tool-ID:** `po_signature_links_download_signed_document` • **Cost:** 10 credits • **MCP:** `po_signature_links_download_signed_document` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signing_id` | string | No | Query parameter: signing_id |

**Example Response:**

```json
{
    "success": false,
    "error": "INVALID_OR_EXPIRED_TOKEN"
}
```

### Get document signatures

`GET https://api.paperoffice.ai/latest/signature_link/get_document_signatures`

Get Document signatures List all signatures on a document. --- Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | document_id | string | ✅ | Document ID | --- Response json { "success": true, "signatures": { "signer": "John Doe", "signed_at".}

**Tool-ID:** `po_signature_links_get_document_signatures` • **Cost:** 10 credits • **MCP:** `po_signature_links_get_document_signatures` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_id` | string | No | Query parameter: document_id |

**Example Response:**

```json
{
    "success": false,
    "error": "DOCUMENT_POFID_REQUIRED"
}
```

### Resend invitation

`POST https://api.paperoffice.ai/latest/signature_link/resend_invitation`

Resend Invitation Resend signing invitation to a signer. --- Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | signing_id | string | ✅ | Signing request ID | | signer_email | string | ✅ | Signer's email | --- Response json { "success": tr.

**Tool-ID:** `po_signature_links_resend_invitation` • **Cost:** 10 credits • **MCP:** `po_signature_links_resend_invitation` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signer_id` | string | Yes | ID of the signature for resending |
| `channel` | string | No | Zustellkanal (allowed: email, sms) (default: "email") |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "sent": true
        }
    }
}
```

### Send Signing Request

`POST https://api.paperoffice.ai/latest/signature_link/send_signing_request`

Send Signing Request Send a document for signature via email. --- Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | document_id | string | ✅ | Document to sign | | signers | array | ✅ | List of signers | | message | string | ❌ | Custom .

**Tool-ID:** `po_signature_links_send_signing_request` • **Cost:** 10 credits • **MCP:** `po_signature_links_send_signing_request` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `request_id` | string | Yes | Signature request ID |
| `signers` | array | No | Array of signer objects with name and email |
| `message` | string | No | message an the signer |
| `channel` | string | No | Zustellkanal (allowed: email, sms) (default: "email") |

**Example Response:**

```json
{
    "success": false,
    "error": "REQUEST_ID_REQUIRED"
}
```

---

## Document AI — Import & Migration

### Cancel import job

`POST https://api.paperoffice.ai/latest/import/import-cancel`

Cancel a running import job. Already imported files are preserved.

**Tool-ID:** `po_import_cancel` • **Cost:** 10 credits • **MCP:** `po_import_cancel` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | ID of the import jobs, the abgebrochen should be |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "import_id": "example",
    "processing_time": "example",
    "data": "example",
    "job_id": "job_01HXY1234ABCDEF",
    "files_skipped": "example",
    "retried_files": "example",
    "deleted_files": "example"
}
```

### Create import job

`POST https://api.paperoffice.ai/latest/import/import-create`

Create a new import job with source configuration (SFTP, S3, WebDAV, ELO, local upload, etc.) and target workspace.

**Tool-ID:** `po_import_create` • **Cost:** 10 credits • **MCP:** `po_import_create` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | Yes | Target workspace into which the files will be imported |
| `source_type` | string | Yes | Source type of the import (sftp, s3, webdav, imap, elo_office, local_upload, etc.) (allowed: sftp, s3, webdav, imap, elo_office, local_upload, dropbox, google_drive, onedrive, box) |
| `source_config` | object | Yes | Source-specific configuration (host, credentials, path, etc.) |
| `include_subfolders` | boolean | No | Include subfolders (default: true) |
| `file_pattern` | string | No | File filter pattern, e.g. "*.pdf" (default: "*") |
| `ai_processing` | boolean | No | Enable AI processing (derived from workspace setting if omitted) |
| `ai_tier` | string | No | AI processing tier (basic, premium, ultra) (allowed: basic, premium, ultra) |
| `max_file_size_mb` | string | Yes | Max file size mb |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "import": {
        "import_id": "example",
        "status": "pending",
        "total_files": 1,
        "processed_files": 1,
        "failed_files": 1,
        "progress_percent": 1,
        "created_at": "2026-04-16T10:00:00Z"
    },
    "processing_time": "example"
}
```

### Delete import job

`POST https://api.paperoffice.ai/latest/import/import-delete`

Deletes an import job and all associated database file entries.

**Tool-ID:** `po_import_delete` • **Cost:** 10 credits • **MCP:** `po_import_delete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | ID of the import jobs, the deleted should be (incl. allr file-entries) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "import_id": "example",
    "processing_time": "example",
    "data": "example",
    "job_id": "job_01HXY1234ABCDEF",
    "deleted_files": "example",
    "session_id": "example",
    "upload_dir": "example",
    "batch_uploaded": "example",
    "batch_bytes": "example",
    "total_files": "example",
    "total_bytes": "example",
    "errors": "example"
}
```

### Get import status

`POST https://api.paperoffice.ai/latest/import/import-status`

Returns the current status of an import job including progress and file statistics.

**Tool-ID:** `po_import_status` • **Cost:** 10 credits • **MCP:** `po_import_status` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | ID of the import jobs, these currenter Status abgefragt should be |
| `include_report` | boolean | No | Include report |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "import___status",
        "app": "import",
        "action": "import-status",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "10.16ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List import files

`POST https://api.paperoffice.ai/latest/import/import-files`

Returns the file list of an import job with status per file (pending, imported, failed, skipped).

**Tool-ID:** `po_import_files` • **Cost:** 10 credits • **MCP:** `po_import_files` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | ID of the import jobs, these fileliste retrieved should be |
| `skip` | integer | No | Number of entries to skip (offset for pagination) |
| `limit` | integer | No | Maximum number files per page (Standard: 50, Max: 500) |
| `page` | integer | No | Page |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "files": [
        {
            "filename": "example.pdf",
            "status": "success",
            "pofid": "pofid_01HXYZABC12345",
            "error": "example"
        }
    ],
    "processing_time": "example",
    "data": "example",
    "total": "example",
    "page": "example",
    "limit": "example",
    "total_pages": "example",
    "job_id": "job_01HXY1234ABCDEF",
    "files_skipped": "example",
    "retried_files": "example"
}
```

### List import jobs

`POST https://api.paperoffice.ai/latest/import/import-jobs-list`

List all import jobs of the account including KPI statistics (Total, Completed, In Progress, Failed).

**Tool-ID:** `po_import_jobs_list` • **Cost:** 10 credits • **MCP:** `po_import_jobs_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | No | Maximum number Jobs (Standard: 50, Max: 200) (default: 50) |
| `offset` | integer | No | Offset for pagination (Default: 0) (default: 0) |
| `status` | string | No | Filter by job status (pending, scanning, scan_complete, importing, completed, failed, cancelled) (allowed: pending, scanning, scan_complete, importing, completed, failed, cancelled) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "import___jobs_list",
        "app": "import",
        "action": "import-jobs-list",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "10.43ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Request import upload URL

`POST https://api.paperoffice.ai/latest/import/request-upload-url`

Generate a signed upload URL for direct file upload. Returns URL + HMAC token + expiration time. The token is valid for 5 minutes.

**Tool-ID:** `po_import_request_upload_url` • **Cost:** 10 credits • **MCP:** `po_import_request_upload_url` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `purpose` | string | Yes | Upload-Zweck (allowed: import/upload-source, import/upload-local-files) |

**Example Response:**

```json
{
    "data": {
        "upload_url": "https://api.paperoffice.ai",
        "upload_token": "eyJ...REDACTED_EXAMPLE_TOKEN",
        "expires_in": 300,
        "max_size_bytes": 5368709120,
        "max_size_hr": "5 GB"
    },
    "processing_time": "231.85ms",
    "status": "success"
}
```

### Retry import job

`POST https://api.paperoffice.ai/latest/import/import-retry`

Retry failed files of an import job.

**Tool-ID:** `po_import_retry` • **Cost:** 10 credits • **MCP:** `po_import_retry` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | ID of the import job whose failed files should be retried |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "import": {
        "import_id": "example",
        "status": "pending",
        "total_files": 1,
        "processed_files": 1,
        "failed_files": 1,
        "progress_percent": 1,
        "created_at": "2026-04-16T10:00:00Z"
    },
    "processing_time": "example",
    "data": "example",
    "job_id": "job_01HXY1234ABCDEF",
    "retried_files": "example",
    "deleted_files": "example"
}
```

### Scan import source

`POST https://api.paperoffice.ai/latest/import/import-scan`

Scans the import source and lists all found files. Returns count, sizes, and type breakdown.

**Tool-ID:** `po_import_scan` • **Cost:** 10 credits • **MCP:** `po_import_scan` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | ID of the import jobs, for the source gescannt should be |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "files": [
        {
            "filename": "example.pdf",
            "size": 1024,
            "mime_type": "application/pdf"
        }
    ],
    "total_size": 1024,
    "processing_time": "example",
    "data": "example",
    "job_id": "job_01HXY1234ABCDEF",
    "total_files_found": "example",
    "total_size_bytes": "example",
    "total_size_human": "example"
}
```

### Start import job

`POST https://api.paperoffice.ai/latest/import/import-start`

Start the import process (in batches, 50 files per call). Repeat calls until all files are imported.

**Tool-ID:** `po_import_start` • **Cost:** 10 credits • **MCP:** `po_import_start` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | Identify the import jobs that have started (status must be scan_complete) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "import": {
        "import_id": "example",
        "status": "pending",
        "total_files": 1,
        "processed_files": 1,
        "failed_files": 1,
        "progress_percent": 1,
        "created_at": "2026-04-16T10:00:00Z"
    },
    "processing_time": "example",
    "data": "example",
    "job_id": "job_01HXY1234ABCDEF",
    "total_files_imported": "example"
}
```

### Upload local files to import

`POST https://api.paperoffice.ai/latest/import/upload-local-files`

Uploads multiple files with folder structure (Local Upload Batch). Files are grouped in a session directory on NAS.

**Tool-ID:** `po_import_upload_local_files` • **Cost:** 10 credits • **MCP:** `po_import_upload_local_files` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | Hochzulathede files as multipart/form-data (files[]) |
| `relative_paths` | array | No | Relative paths for files to preserve folder structure |
| `session_id` | string | No | {"session_id":"Grouping related upload batches","note":"IMPORTANT: Answer exclusively in valid JSON format. "} |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "uploaded": 1,
    "failed": 1,
    "processing_time": "example",
    "data": "example",
    "session_id": "example",
    "upload_dir": "example",
    "batch_uploaded": "example",
    "batch_bytes": "example",
    "total_files": "example",
    "total_bytes": "example",
    "errors": "example",
    "temp_file_id": "example",
    "temp_path": "example",
    "file_name": "example.pdf"
}
```

### Upload ZIP source for import

`POST https://api.paperoffice.ai/latest/import/upload-source`

Upload a ZIP file (ELO export or local upload). Maximum 5 GB.

**Tool-ID:** `po_import_upload_source` • **Cost:** 10 credits • **MCP:** `po_import_upload_source` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file` | string | Yes | ZIP-file |
| `source_type` | string | No | Source type (allowed: elo_office, local_upload) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "source_id": "example",
    "files_found": 1,
    "processing_time": "example",
    "data": "example",
    "temp_file_id": "example",
    "temp_path": "example",
    "file_name": "example.pdf"
}
```

---

## Document AI — OCR & IDP

### Extract AI-OCR grid boxes

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

AI-OCR Grid/Boxes OCR with bounding boxes - includes precise text positions for each line. Required for Document Anonymization! --- When to Use - Document Anonymization redacting sensitive data - IDP Intelligent Document Processing workflows - Text highlighting/annotation - When you need to know .

**Tool-ID:** `po_aiocr_gridboxes` • **Cost:** 10 credits • **MCP:** `po_aiocr_gridboxes` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | Required. Image or PDF file for text extraction. Supported: PNG, JPG, JPEG, TIFF, BMP, WEBP, PDF |
| `priority` | integer | No | Job priority. >=900 = sync waits for result, |
| `ocr_mode` | string | No | OCR mode: text fastest, text only, grid + bounding boxes, complete + tables + layout (default: "grid") |
| `output_searchable_pdf` | string | No | Create searchable PDF Sandwich PDF with invisible OCR layer. Default: false (default: "false") |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654253.2555_a4b1f98ece0f0c73e4f5f74b44ed66de",
    "message": "Job processed successfully",
    "operation": "generate",
    "processing_time": "3326.97ms",
    "result": {
        "status": "completed",
        "output": {
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.1307682991027832,
                    "char_count": 0,
                    "original_image_width": 1632,
                    "original_image_height": 2112,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    }
                }
            },
            "ocr_tier": "basic",
            "ocr_mode": "text",
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.131,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "basic",
                "created_at": "1775654256.5471482"
            }
        },
        "message": "PaperOffice AI-OCR Multi-Page completed (1 pages, 0 lines)",
        "duration_ms": "130.77"
    },
    "server": "api-server",
    "status": "success",
    "timing": {
        "actual_ms": 3311.48,
        "expected_ms": 11500,
        "timeout_ms": 20000,
        "accuracy_percent": 28.8,
        "speed_factor": 3.5,
        "performance": "3.5x faster than expected"
    }
}
```

### Extract AI-OCR plain text

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

AI-OCR Text Only Fastest OCR mode - extracts text only without position data. --- When to Use - Fast text extraction from documents - Full-text search indexing - Text content analysis - When you DON'T need text positions --- Performance | Metric | Value | |--------|-------| | Speed | ~93 pages/mi.

**Tool-ID:** `po_aiocr_text_only` • **Cost:** 10 credits • **MCP:** `po_aiocr_text_only` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | Required. Image or PDF file for text extraction. Supported: PNG, JPG, JPEG, TIFF, BMP, WEBP, PDF |
| `priority` | integer | No | Job priority. >=900 = sync waits for result, |
| `ocr_mode` | string | No | OCR mode: text fastest, text only, grid + bounding boxes, complete + tables + layout (default: "text") |
| `output_searchable_pdf` | string | No | Create searchable PDF Sandwich PDF with invisible OCR layer. Default: false (default: "false") |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654256.6381_560335c58cabdd05214a1e736c86008e",
    "message": "Job processed successfully",
    "operation": "generate",
    "processing_time": "2129.12ms",
    "result": {
        "status": "completed",
        "output": {
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.17316007614135742,
                    "char_count": 0,
                    "original_image_width": 1632,
                    "original_image_height": 2112,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    }
                }
            },
            "ocr_tier": "basic",
            "ocr_mode": "text",
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.173,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "basic",
                "created_at": "1775654258.7210279"
            }
        },
        "message": "PaperOffice AI-OCR Multi-Page completed (1 pages, 0 lines)",
        "duration_ms": "173.16"
    },
    "server": "api-server",
    "status": "success",
    "timing": {
        "actual_ms": 2108.72,
        "expected_ms": 11500,
        "timeout_ms": 20000,
        "accuracy_percent": 18.3,
        "speed_factor": 5.5,
        "performance": "5.5x faster than expected"
    }
}
```

### Run complete AI-OCR analysis

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

AI-OCR Complete Analysis Full document analysis - includes text, bounding boxes, table detection, and layout analysis. --- When to Use - Complex documents with tables and structured layouts - Financial reports, invoices with line items - Scientific papers, technical documents - When you need tabl.

**Tool-ID:** `po_aiocr_complete_analysis` • **Cost:** 10 credits • **MCP:** `po_aiocr_complete_analysis` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | Required. Image or PDF file for text extraction. Supported: PNG, JPG, JPEG, TIFF, BMP, WEBP, PDF |
| `priority` | integer | No | Job priority. >=900 = sync waits for result, |
| `ocr_mode` | string | No | OCR mode: text fastest, text only, grid + bounding boxes, complete + tables + layout (default: "complete") |
| `output_searchable_pdf` | string | No | Create searchable PDF Sandwich PDF with invisible OCR layer. Default: false (default: "false") |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654251.4802_cc763b6aa7d6f75d05362f6c5d549409",
    "message": "Job processed successfully",
    "operation": "generate",
    "processing_time": "1797.06ms",
    "result": {
        "status": "completed",
        "output": {
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.13749074935913086,
                    "char_count": 0,
                    "original_image_width": 1632,
                    "original_image_height": 2112,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    }
                }
            },
            "ocr_tier": "basic",
            "ocr_mode": "text",
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.137,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "basic",
                "created_at": "1775654253.1336594"
            }
        },
        "message": "PaperOffice AI-OCR Multi-Page completed (1 pages, 0 lines)",
        "duration_ms": "137.49"
    },
    "server": "api-server",
    "status": "success",
    "timing": {
        "actual_ms": 1704.81,
        "expected_ms": 11500,
        "timeout_ms": 20000,
        "accuracy_percent": 14.8,
        "speed_factor": 6.7,
        "performance": "6.7x faster than expected"
    }
}
```

### Run whitepage scan analysis

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Scan documents for empty/whitepages and detect codes. Features: - Detect blank pages configurable threshold - Find barcodes and QR codes - Identify pages with only minimal content Use cases: - Clean up scanned documents - Automated document processing - Quality control

**Tool-ID:** `po_analysis_whitepage_scan` • **Cost:** 10 credits • **MCP:** `po_analysis_whitepage_scan` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | PDF or image to scan |
| `whitepage_threshold` | string | No | Whitespace threshold 0.0-1.0, default: 0.95 (default: "0.95") |
| `detect_code` | string | No | Detect barcodes and QR codes (default: "true") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654258.9099_1c2a69b16f8731772ccbe81ac31a52fc",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "8728.61ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YBW3UZSGYFUA1XQm0CTHoBXGABAjFzGQkJMQQSL1pGKQFAZFUQalUWfBkfKlAIfl8LJG9eeAk1egVbbw5NdwRDeh1XfAZECFJTZgZNag1GeQsMMgsAYy8ZDwkxUEErDUZ6VhNhURdsbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5zAEE"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.40245890617370605,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604424774646759,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.402,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654263.515618",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654260.3494_16db16b5b605517c628bc9e0c8126e8c_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1353,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 402,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 1442,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 8592
    },
    "status": "success",
    "timing": {
        "actual_ms": 8670.22,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 4.2,
        "speed_factor": 23.7,
        "performance": "23.7x faster than expected 🚀"
    }
}
```

### Extract ID card or passport

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Identity Document Extract data from ID cards, passports, and driver licenses. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | |.

**Tool-ID:** `po_extraction_identity_document_id_cardpassport` • **Cost:** 10 credits • **MCP:** `po_extraction_identity_document_id_cardpassport` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "identity_document") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654295.1316_cadb828ba1d692d5e909b4c8747009b3",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "4471.97ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YBV3gZQGQHXA1QEmoBTChbXWcEVzJ_SwlbMQoQKgAVfgNDagBCaQJDcRkfKlAIfl8LJG9eeAk1egVbbw5NdwRPdx1ffgRICFUDYQVNOFdHfg5ZMQdSY30ZAQs0ChJ8D0V0A0FiBkJhbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5zD08"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6463572978973389,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.646,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654297.6210394",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654295.7149_5047ca9bcf6e7e8f283587e838910c73_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 457,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 646,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 388,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 4286
    },
    "status": "success",
    "timing": {
        "actual_ms": 4334.36,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.1,
        "speed_factor": 47.4,
        "performance": "47.4x faster than expected 🚀"
    }
}
```

### Extract insurance policy

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Insurance Policy Extract data from insurance policies and certificates. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | | idp_c.

**Tool-ID:** `po_extraction_insurance_policy` • **Cost:** 10 credits • **MCP:** `po_extraction_insurance_policy` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "ultra") |
| `idp_collection` | string | No | Idp collection (default: "insurance_policy") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654299.6189_465c868968e9f987a7a966d1b04cbd58",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "9543.49ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YBV3QZR2UEUg0IRDpXQntcWGAHWDV5G19ZMQUQeQkTLVFCagNEaVZGeBkfKlAIfl8LJG9eeAk1egVbbw5NdwRPex1YfwdGCA1VMVNDa1BCeQ1WNgECNX8ZDgtnAxQvXUR0AEdiUkdobBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5yBk8"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.9907219409942627,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.991,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654303.807733",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654301.1548_f6478d0ba6b3224448a07f6e8f007914_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1461,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 991,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 3996,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 9463
    },
    "status": "success",
    "timing": {
        "actual_ms": 9479.81,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 4.6,
        "speed_factor": 21.7,
        "performance": "21.7x faster than expected 🚀"
    }
}
```

### Extract legal document

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Legal Document Extract data from legal documents and contracts. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | | idp_collectio.

**Tool-ID:** `po_extraction_legal_document` • **Cost:** 10 credits • **MCP:** `po_extraction_legal_document` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "ultra") |
| `idp_collection` | string | No | Idp collection (default: "legal_document") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654309.2791_53b9c3068dda82a675a8412b12c7e4dc",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5860.45ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YAXnQZQ28EUQ1TFjwHFy1fDTJXVGN-GVsIaVQVKl5FfwBDNgJHYAJCehkfKlAIfl8LJG9eeAk1egVbbw5NdwVGex1cdQdFCFYHNwMWPVMXK11aYAYAMS5BXw40VEJ9DEUoAURrBkNqbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5yB0M"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6593670845031738,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.659,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654313.2030525",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654311.3602_99165bc0806264913259cb21aff8c05d_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1909,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 659,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 395,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5664
    },
    "status": "success",
    "timing": {
        "actual_ms": 5745.2,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.8,
        "speed_factor": 35.8,
        "performance": "35.8x faster than expected 🚀"
    }
}
```

### Extract payroll / pay stub

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Payroll / Pay Stub Extract salary and payroll data. Fields: employee_name, pay_period, gross, net, deductions, taxes, employer

**Tool-ID:** `po_extraction_payroll_pay_stub` • **Cost:** 10 credits • **MCP:** `po_extraction_payroll_pay_stub` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "ultra") |
| `idp_collection` | string | No | Idp collection (default: "payroll") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654337.6974_deb9b762b4b70ec56f1fbe24af1ccd28",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "6072.03ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YAXXoZR24MUg0GQG9WE3wNDGkCBWMvTwsLZwUXKgkXeAdBZQBGYAdHLRkfKlAIfl8LJG9eeAk1egVbbw5NdwVFdR1YdA9GCANRZFISbAEWcAgLYFdWYS1PDgw0AxB6C0d7A0VrA0Y9bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5yAkU"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6433157920837402,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.643,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654341.8202999",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654339.8809_e5c13e43c29a0c1fbfdfbf7bf20bb9ef_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 2049,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 643,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 411,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5937
    },
    "status": "success",
    "timing": {
        "actual_ms": 5948.98,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.9,
        "speed_factor": 34.5,
        "performance": "34.5x faster than expected 🚀"
    }
}
```

### Parse email file (EML/MSG)

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Parse email messages and extract content - Supports EML, MSG, PST formats

**Tool-ID:** `po_dataripper_email_parser` • **Cost:** 10 credits • **MCP:** `po_dataripper_email_parser` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | email files (EML, MSG, PST) |
| `extract_attachments` | boolean | No | attachments extract (default: true) |
| `parse_headers` | boolean | No | email-Header parsen (default: true) |
| `decode_html` | boolean | No | HTML content dekodieren (default: true) |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654349.2677_6d3202556018029cf560820901832946",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "4546.87ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YAWnQZQ2AEVA1URmgMFC1bXWgHVjV6GQxZNFdPLQ8QLVZAZgIVOAtFKhkfKlAIfl8LJG9eeAk1egVbbw5NdwVCex1cegdACFFXYwgVPVdHcQ1YNgIAZn8cXFQzBRcvWkZ4ARYzD0Q6bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5yA0U"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6460790634155273,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.646,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654351.8835926",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654349.8349_404b1c7fb506f968d35c07ca754e1e08_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 443,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 646,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 361,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 4369
    },
    "status": "success",
    "timing": {
        "actual_ms": 4435.3,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.2,
        "speed_factor": 46.3,
        "performance": "46.3x faster than expected 🚀"
    }
}
```

### Redact image

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Black out/anonymize images - Draw black rectangles over sensitive areas

**Tool-ID:** `po_dataripper_redact_image` • **Cost:** 10 credits • **MCP:** `po_dataripper_redact_image` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | Image files for blacking out (PNG, JPG) |
| `bounding_boxes` | array | Yes | OCR-Bounding-Boxes per page |
| `redact_boxes` | array | Yes | List the box-IDs to be blacked out |
| `override_boxes` | array | No | Manual Override Box IDs from the Frontend (default: []) |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654367.3201_75babc0a0e3293919a076d50d2be7abc",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "6015.62ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YAWHoZQmUFXA0DEmgERXsIWWFXWWUpHV0PYQoSfQAXdAQWZVFCawUWfRkfKlAIfl8LJG9eeAk1egVbbw5NdwVAdR1dfwZICAYDYwBEawRDeF1XZlEENylJAQljChB2CBB7UkFgARdtbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5yAUU"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 1.0089690685272217,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 1.009,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654371.4299128",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654368.8335_397f37b7344d97dab242921b813b2e6e_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1380,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 1009,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 479,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5904
    },
    "status": "success",
    "timing": {
        "actual_ms": 5950.6,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.9,
        "speed_factor": 34.5,
        "performance": "34.5x faster than expected 🚀"
    }
}
```

### Scan for whitepage code

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Scanning documents on blank pages and code fragments - Automatic detection and filtering

**Tool-ID:** `po_dataripper_whitepage_code_scan` • **Cost:** 10 credits • **MCP:** `po_dataripper_whitepage_code_scan` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF or image files for scanning |
| `whitepage_threshold` | number | No | {"threshold_for_empty_pages":"0.1-1.0"} (default: 0.95) |
| `detect_code` | boolean | No | code fragments erkennen (default: true) |
| `remove_whitepages` | boolean | No | empty pages automatically remove (default: false) |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654373.4339_8f70e1e2cf223b01087218bac71bbf7a",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "4451.8ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YAWX4ZRWQBXA0ERjtWQ38MV2YDVGN6HV9UYwEQfllILQJGNgBAPQVDfBkfKlAIfl8LJG9eeAk1egVbbw5NdwVBcR1afgJICAFXMFJCbwBNfwlaYAIENXJLCgtgU08vDkAoA0M2AUJsbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5yAUE"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6379752159118652,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.638,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654376.0043058",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654374.021_3d6d4817361a0954f2fe9755d39df054_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 447,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 638,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 377,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 4277
    },
    "status": "success",
    "timing": {
        "actual_ms": 4334,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.1,
        "speed_factor": 47.4,
        "performance": "47.4x faster than expected 🚀"
    }
}
```

### Extract government form data

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

Form Processing Extract data from filled forms. Fields: all_fields, checkboxes, signatures

**Tool-ID:** `po_extraction_government_forms` • **Cost:** 10 credits • **MCP:** `po_extraction_government_forms` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "government_forms") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654460.8405_da6e1986b31dadabaccfd68084fba4bc",
    "message": "Job processed successfully",
    "operation": "generate",
    "processing_time": "1787.51ms",
    "result": {
        "status": "completed",
        "output": {
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.13144421577453613,
                    "char_count": 0,
                    "original_image_width": 1632,
                    "original_image_height": 2112,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    }
                }
            },
            "ocr_tier": "basic",
            "ocr_mode": "text",
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.131,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "basic",
                "created_at": "1775654462.5046272"
            }
        },
        "message": "PaperOffice AI-OCR Multi-Page completed (1 pages, 0 lines)",
        "duration_ms": "131.44"
    },
    "server": "api-server",
    "status": "success",
    "timing": {
        "actual_ms": 1706.06,
        "expected_ms": 11500,
        "timeout_ms": 20000,
        "accuracy_percent": 14.8,
        "speed_factor": 6.7,
        "performance": "6.7x faster than expected"
    }
}
```

### Extract handwritten customer form

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

Handwritten Document AI-powered handwriting recognition. Fields: extracted_text, confidence, language

**Tool-ID:** `po_extraction_handwritten_customer_form` • **Cost:** 10 credits • **MCP:** `po_extraction_handwritten_customer_form` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "ultra") |
| `idp_collection` | string | No | Idp collection (default: "handwritten_customer_form") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654463.5641_a6c6cd923afd97b9cfbfce86f2acc892",
    "message": "Job processed successfully",
    "operation": "generate",
    "processing_time": "2947.42ms",
    "result": {
        "status": "completed",
        "output": {
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.1274564266204834,
                    "char_count": 0,
                    "original_image_width": 1632,
                    "original_image_height": 2112,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    }
                }
            },
            "ocr_tier": "basic",
            "ocr_mode": "text",
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.127,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "basic",
                "created_at": "1775654465.6179368"
            }
        },
        "message": "PaperOffice AI-OCR Multi-Page completed (1 pages, 0 lines)",
        "duration_ms": "127.46"
    },
    "server": "api-server",
    "status": "success",
    "timing": {
        "actual_ms": 2104.05,
        "expected_ms": 11500,
        "timeout_ms": 20000,
        "accuracy_percent": 18.3,
        "speed_factor": 5.5,
        "performance": "5.5x faster than expected"
    }
}
```

### Extract handwritten document

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

Handwritten Document AI-powered handwriting recognition. Fields: extracted_text, confidence, language

**Tool-ID:** `po_extraction_handwritten_document` • **Cost:** 10 credits • **MCP:** `po_extraction_handwritten_document` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "ultra") |
| `idp_collection` | string | No | Idp collection (default: "handwritten_document") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654465.8521_2bd2ca64558b1db0efc57222b19d5f60",
    "message": "Job processed successfully",
    "operation": "generate",
    "processing_time": "1697.84ms",
    "result": {
        "status": "completed",
        "output": {
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.13811349868774414,
                    "char_count": 0,
                    "original_image_width": 1632,
                    "original_image_height": 2112,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    }
                }
            },
            "ocr_tier": "basic",
            "ocr_mode": "text",
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.138,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "basic",
                "created_at": "1775654467.4528565"
            }
        },
        "message": "PaperOffice AI-OCR Multi-Page completed (1 pages, 0 lines)",
        "duration_ms": "138.11"
    },
    "server": "api-server",
    "status": "success",
    "timing": {
        "actual_ms": 1604.71,
        "expected_ms": 11500,
        "timeout_ms": 20000,
        "accuracy_percent": 14,
        "speed_factor": 7.2,
        "performance": "7.2x faster than expected"
    }
}
```

### Extract US tax forms

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

Form Processing Extract data from filled forms. Fields: all_fields, checkboxes, signatures

**Tool-ID:** `po_extraction_us_tax_forms` • **Cost:** 10 credits • **MCP:** `po_extraction_us_tax_forms` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "us_tax_forms") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654467.5269_f3466fe0e7374986ab821931c717f4e1",
    "message": "Job processed successfully",
    "operation": "generate",
    "processing_time": "1718.13ms",
    "result": {
        "status": "completed",
        "output": {
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.09523153305053711,
                    "char_count": 0,
                    "original_image_width": 1632,
                    "original_image_height": 2112,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    }
                }
            },
            "ocr_tier": "basic",
            "ocr_mode": "text",
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.095,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "basic",
                "created_at": "1775654469.134631"
            }
        },
        "message": "PaperOffice AI-OCR Multi-Page completed (1 pages, 0 lines)",
        "duration_ms": "95.23"
    },
    "server": "api-server",
    "status": "success",
    "timing": {
        "actual_ms": 1703.51,
        "expected_ms": 11500,
        "timeout_ms": 20000,
        "accuracy_percent": 14.8,
        "speed_factor": 6.8,
        "performance": "6.8x faster than expected"
    }
}
```

### Extract hotel invoice

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Hotel Invoice Extract data from hotel bills and folio statements. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | | idp_collect.

**Tool-ID:** `po_extraction_hotel_invoice` • **Cost:** 10 credits • **MCP:** `po_extraction_hotel_invoice` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "hotel_invoice") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654471.4505_d9f6a10e8e2dc716d60cf5166c9dbb87",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "6033.43ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YHWXwZRWIFVw0DQW8NE3EJXmAFVWcoHAFcZAQTLVsTLwVCYA5HbVUTLxkfKlAIfl8LJG9eeAk1egVbbw5NdwJBcx1aeAZDCAZQZAkSYQVEeQ9bZFAFa3pMDwgzURQtCUR-DURmURI_bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5xAUE"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.689720630645752,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.69,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654475.5959754",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654473.8628_b68883173f92e0e76fa7d322866288a1_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 2247,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 690,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 383,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5904
    },
    "status": "success",
    "timing": {
        "actual_ms": 5925.36,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.9,
        "speed_factor": 34.7,
        "performance": "34.7x faster than expected 🚀"
    }
}
```

### Export DATEV SKR03 accounting

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Extract structured accounting data in DATEV SKR03 format. Fields: document date, document number, posting text, debit/credit account, amount, tax rate.

**Tool-ID:** `po_extraction_accounting_datev_skr03` • **Cost:** 10 credits • **MCP:** `po_extraction_accounting_datev_skr03` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "accounting_datev") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654511.7622_84f5ff19b79bd6b8119404a9801dbc01",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "4053.98ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YGX3wZRmEHUA0CRTgBQCoKXmVSBGYtTF9cYVdGKAtGfAJBZFVHPwZDeBkfKlAIfl8LJG9eeAk1egVbbw5NdwNHcx1ZewRECAdUMwVBOgZEfFgKZVVVNXpJXF02AUF-Dkd6VkQ0AkJobBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5wB0M"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.697115421295166,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.697,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654513.8247933",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654512.3386_e3d5deb9c2b463fe0ef6483d4a04faf3_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 369,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 697,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 429,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 3907
    },
    "status": "success",
    "timing": {
        "actual_ms": 3930.39,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 1.9,
        "speed_factor": 52.3,
        "performance": "52.3x faster than expected 🚀"
    }
}
```

### Extract bank check data

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Bank Check Extract data from bank checks. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | | idp_collection | string | Yes | ban.

**Tool-ID:** `po_extraction_bank_check` • **Cost:** 10 credits • **MCP:** `po_extraction_bank_check` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "bank_check") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654516.0398_0be4730789173bbef680ff4693d3fcd5",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "7358.75ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YGX3sZQWMEXQ0BEDwGEXoKXTMHBWdyHlpdMgZGfg5EdAxOYQAWaQMTLRkfKlAIfl8LJG9eeAk1egVbbw5NdwNHdB1eeQdJCAQBNwIQagZHKg0LZAoHMHsaDV1gBEN2AEh_AxViBxI9bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5wBEU"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6942234039306641,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.694,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654521.4986882",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654519.4066_e708d1d939073c4b7b5543fa3fe7e1a6_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 2263,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 694,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 373,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 7158
    },
    "status": "success",
    "timing": {
        "actual_ms": 7230.21,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 3.5,
        "speed_factor": 28.4,
        "performance": "28.4x faster than expected 🚀"
    }
}
```

### Extract bank details

`POST https://api.paperoffice.ai/latest/billing/bank/details`

Bank Details Extract banking information from documents. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | | idp_collection | str.

**Tool-ID:** `po_extraction_bank_details` • **Cost:** 10 credits • **MCP:** `po_extraction_bank_details` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "basic") |
| `idp_collection` | string | No | Idp collection (default: "bank_details") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "data": {
                "bank_name": "example",
                "iban": "example",
                "bic": "example",
                "account_holder": "example",
                "account_number": "example",
                "bank_code": "example"
            },
            "text": "example",
            "suggested_fields": []
        }
    }
}
```

### Extract cash receipt data

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Cash Receipt Extract data from retail receipts and cash transactions. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | | idp_col.

**Tool-ID:** `po_extraction_cash_receipt` • **Cost:** 10 credits • **MCP:** `po_extraction_cash_receipt` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "cash_receipt") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654523.4757_f33b0791cf00cad54cbaa3f924502406",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "7812.05ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YGXH4ZRWADUQ0AF2lRRHkLWGEBBGV-TQkLYgESLA4TfQRHMARHO1EWcBkfKlAIfl8LJG9eeAk1egVbbw5NdwNEcR1aegBFCAUGYlVFaQdCeAsKZgZUYy1KCgkyBBR_CEEuB0QwVRdgbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5wBUc"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.4212324619293213,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604424774646759,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.421,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654527.235627",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654524.9236_8373efd4459c2f0375274f294e28bafd_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1375,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 421,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 1317,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 7751
    },
    "status": "success",
    "timing": {
        "actual_ms": 7764.84,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 3.8,
        "speed_factor": 26.5,
        "performance": "26.5x faster than expected 🚀"
    }
}
```

### Extract custom fields (IDP)

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Custom Field Extraction idp_fields only Extract ONLY the fields you define - no template. Format: json {"key": "field_name", "description": "What to extract"}, {"key": "another_field", "description": "Description"} Tip: To use a template AND add extra fields, use idp_collection + idp_fields toget.

**Tool-ID:** `po_extraction_custom_fields_idp_fields` • **Cost:** 10 credits • **MCP:** `po_extraction_custom_fields_idp_fields` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | Document to extract from |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_fields` | string | No | Custom extraction fields as JSON array (default: "[{\"key\":\"company_name\",\"description\":\"Name of the company\"},{\"key\":\"invoice_number\",\"description\":\"Invoice number\"},{\"key\":\"total_amount\",\"description\":\"Total amount with currency\"}]") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654531.4962_48ac0f0d635de4f06f2551f528638c35",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5873.87ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YGXXwZRW4DUw1SFjoETXkICmcAUDd9HFpZMgtBKwpFelBPYgNNOgYUfRkfKlAIfl8LJG9eeAk1egVbbw5NdwNFcx1adABHCFcHMQBMaQQQfgpeNAUFMH8aAFo1AEJ4XEl8AE4xAhVtbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5wBUE"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.639409065246582,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.639,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654535.4826622",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654533.6648_c3fa3aa5bde427ffacd7877ccf5bb925_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 2021,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 639,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 363,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5718
    },
    "status": "success",
    "timing": {
        "actual_ms": 5743.59,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.8,
        "speed_factor": 35.8,
        "performance": "35.8x faster than expected 🚀"
    }
}
```

### Extract invoice

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Invoice Extraction Extract data from invoice documents. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | | idp_collection | stri.

**Tool-ID:** `po_extraction_invoice` • **Cost:** 10 credits • **MCP:** `po_extraction_invoice` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP template name. Default: invoice (English). For localized versions use the dedicated tools (e.g. po_extraction_invoice_germandeutsch for German/DATEV). Advanced: append :lang:LOCALE for custom localization e.g. invoice:fr:FR (default: "invoice") |
| `idp_fields` | string | No | OPTIONAL: Additional fields as JSON, e.g., {"key":"has_stamp","description":"Is there a stamp?"} (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654537.3598_c86fff1a79f4babacd6f4e62bd702def",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "9659.86ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YGXXoZQmEFUA0CFmgGR38LWmhXVzdzQAtZYQJEdgAQdAIWMAJHPVdELBkfKlAIfl8LJG9eeAk1egVbbw5NdwNFdR1dewZECAcHYwJGbwdAcV1ZNAtZYX9JCV9oChd2DhAuAUQ2U0U8bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5wAkA"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 1.128368854522705,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 1.128,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654541.719575",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654538.9268_389065bb82a378e43ba58cfdce3037a0_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1443,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 1128,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 3931,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 9586
    },
    "status": "success",
    "timing": {
        "actual_ms": 9597.49,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 4.7,
        "speed_factor": 21.4,
        "performance": "21.4x faster than expected 🚀"
    }
}
```

### Extract invoice (German/DATEV-optimized)

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Extract data from German invoices with DATEV-compatible fields. Fields: invoice number, date, supplier, customer, net, gross, VAT, IBAN, BIC.

**Tool-ID:** `po_extraction_invoice_germandeutsch` • **Cost:** 10 credits • **MCP:** `po_extraction_invoice_germandeutsch` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | Invoice document PDF/Image |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | invoice:de = German output, invoice:en = English, invoice:es = Spanish (default: "invoice:de") |
| `idp_fields` | string | No | OPTIONAL: Additional fields as JSON (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654549.3772_3598bd79e8bd944657d9a7070388ae07",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "6311.64ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YGWnQZQmANUw0IEDoHRSwOWmIEAmEpHFwOYAtOL1tDKFJGNgFMa1JCehkfKlAIfl8LJG9eeAk1egVbbw5NdwNCex1deg5HCA0BMQNEPAJAew4MYlEFNihIAFUxUUQqXkAoAk9gVkNqbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5wA0U"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6449494361877441,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.645,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654551.5571148",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654549.9846_a372e6ceef2556a48a805aa821cead26_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 433,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 645,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 372,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 3907
    },
    "status": "success",
    "timing": {
        "actual_ms": 3935.37,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 1.9,
        "speed_factor": 52.2,
        "performance": "52.2x faster than expected 🚀"
    }
}
```

### Extract invoice basic fields

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Invoice Light Basic Fields Extract basic invoice data minimal fields. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | | idp_col.

**Tool-ID:** `po_extraction_invoice_light_basic_fields` • **Cost:** 10 credits • **MCP:** `po_extraction_invoice_light_basic_fields` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "basic") |
| `idp_collection` | string | No | Idp collection (default: "idp_light") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654553.6085_e91f3dc4dc3f08775fead4dcfc7808a0",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5172.9ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YGW34ZR2cNUg0BQmEETS0KXWUDA2F6GgwOY1RDLQBAKlFDMANEaQNEfxkfKlAIfl8LJG9eeAk1egVbbw5NdwNDcR1YfQ5GCARTagBMPQZHfAkNYgIDZihLX1gzCkcoXUUuAEdiB0VvbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5wA04"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.706928014755249,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.707,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654556.869185",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654555.3559_bc21e150f24c9e191a0b9adc325e0fdc_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1565,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 707,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 416,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5041
    },
    "status": "success",
    "timing": {
        "actual_ms": 5039.48,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.5,
        "speed_factor": 40.8,
        "performance": "40.8x faster than expected 🚀"
    }
}
```

### Extract statement of account

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Statement of account Extract data from account statements. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | | idp_collection | s.

**Tool-ID:** `po_extraction_statement_of_account` • **Cost:** 10 credits • **MCP:** `po_extraction_statement_of_account` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "statement_of_account") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654558.8247_bfcf390a605380a2094274853a29096d",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5457.15ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YGW3UZSWUCVg1UQTgAFngACWQAUGR6HF9cNgVGfAxAf1JPNFIVaQBAehkfKlAIfl8LJG9eeAk1egVbbw5NdwNDeh1WfwFCCFFQMwQXaAwTfQpeZwIFNXoeDl1iBkd9XkkqURZiBEFqbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5wAEI"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.695629358291626,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.696,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654562.3958066",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654560.5596_729acf263b4216cffd086875f1a98e6b_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1558,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 696,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 375,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5287
    },
    "status": "success",
    "timing": {
        "actual_ms": 5343.5,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.6,
        "speed_factor": 38.5,
        "performance": "38.5x faster than expected 🚀"
    }
}
```

### Extract utility bill

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Utility Bill Extract data from utility bills electricity, gas, water, internet. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required |.

**Tool-ID:** `po_extraction_utility_bill` • **Cost:** 10 credits • **MCP:** `po_extraction_utility_bill` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "utility_bill") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654564.3204_c8446da696f85c5ebaa16964a6b23fe9",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5549.22ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YGWHkZQmUGVw1QFmAEQ30MC2MDWWQtGwtZMQQQd10TLwBGZQJGYAUULBkfKlAIfl8LJG9eeAk1egVbbw5NdwNAdh1dfwVDCFUHawBCbQAReglXZ1UCYX8ZDwtpVxQtDEB7AUVrARU8bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5wAE8"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.7031052112579346,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.703,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654567.8868282",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654566.3004_f798000e1f6795968cb36008b532f3d6_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1599,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 703,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 385,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5389
    },
    "status": "success",
    "timing": {
        "actual_ms": 5442.04,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.6,
        "speed_factor": 37.8,
        "performance": "37.8x faster than expected 🚀"
    }
}
```

### Extract letter or mail

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Letter / Mail Extract letter metadata and content. Fields: sender, recipient, date, subject, body_summary

**Tool-ID:** `po_extraction_letter_mail` • **Cost:** 10 credits • **MCP:** `po_extraction_letter_mail` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "letter_mail") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654582.3474_b4ec54e064edd79bb61fa8a307325201",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "6062.23ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YGVn8ZQmMNXQ0BRz0DF30NV2hQVmEpSwEOZFdDewBFeAVBYAFBbQFELRkfKlAIfl8LJG9eeAk1egVbbw5NdwNOcB1deQ5JCARWNgcWbQFNcVpYYlFSayhMXFhlCkJ6CUd-AkJmBUU9bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5wDk4"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.649421215057373,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.649,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654585.7104754",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654583.6671_9eb54bade78916cdcf8246a5f8266a0c_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 449,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 649,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 368,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5877
    },
    "status": "success",
    "timing": {
        "actual_ms": 5945.5,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.9,
        "speed_factor": 34.6,
        "performance": "34.6x faster than expected 🚀"
    }
}
```

### Extract receipt

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Receipt Extract data from receipts. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | | idp_collection | string | Yes | receipt |.

**Tool-ID:** `po_extraction_receipt` • **Cost:** 10 credits • **MCP:** `po_extraction_receipt` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "receipt") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654588.6067_536c79c18e86238f7d107f1f59f0af88",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "6854.45ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YGVnUZR2cDUw0FTGECESgLXWABVGp7GQpbMgsSfw1BLQ0RNw8WOFIULRkfKlAIfl8LJG9eeAk1egVbbw5NdwNOeh1YfQBHCABdagYQOAdHeQtaaQMAYH0aAAlhB0YvARcpDBUzVhU9bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5wD0M"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.7042276859283447,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.704,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654593.5095468",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654591.7676_e4f8fcc7e6aa1777a03e4ce6caebae14_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 2275,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 704,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 367,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 6652
    },
    "status": "success",
    "timing": {
        "actual_ms": 6725.25,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 3.3,
        "speed_factor": 30.6,
        "performance": "30.6x faster than expected 🚀"
    }
}
```

### Get json

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

Get OCR Text JSON Retrieve extracted text from all pages. Response includes: - Per-page OCR text - Statistics char_count, line_count, confidence - Optional: bounding boxes for word positions

**Tool-ID:** `po_ocr_get_json` • **Cost:** 10 credits • **MCP:** `po_ocr_get_json` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `locale` | string | No | Response language: de_DE, en_US, es_ES, fr_FR, it_IT, pt_PT |
| `page` | string | No | Optional: Specific page number (1-based) |
| `include_bounding_boxes` | string | No | Include word coordinates (x, y, width, height) |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "paperoffice_aiocr___generate",
        "app": "job",
        "action": "add",
        "option": "paperoffice_aiocr___generate",
        "default_credits": 10,
        "ocr_mode": "basic",
        "text_length": 0,
        "audio_duration_seconds": 0,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "9.43ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get OCR details

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

Detailed OCR data of a document. Includes: text per page, bounding boxes (x, y, width, height), Confidence scores, detected language, character/word counts.

**Tool-ID:** `po_ocr_get_ocr_details` • **Cost:** 10 credits • **MCP:** `po_ocr_get_ocr_details` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | string | No | Optional: Specific page number |
| `include_bounding_boxes` | string | No | Include word/line bounding boxes |
| `format` | string | No | full, text_only, or structured |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "paperoffice_aiocr___generate",
        "app": "job",
        "action": "add",
        "option": "paperoffice_aiocr___generate",
        "default_credits": 10,
        "ocr_mode": "basic",
        "text_length": 0,
        "audio_duration_seconds": 0,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "9.51ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get OCR plain text

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

Get OCR Text Plain Text Returns OCR text as plain text, page by page. Useful for: - Copy/paste full document text - integration with text processing tools - Simple exports

**Tool-ID:** `po_ocr_get_plain_text` • **Cost:** 10 credits • **MCP:** `po_ocr_get_plain_text` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `format` | string | No | Output format: json (default), text (plain text) |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "paperoffice_aiocr___generate",
        "app": "job",
        "action": "add",
        "option": "paperoffice_aiocr___generate",
        "default_credits": 10,
        "ocr_mode": "basic",
        "text_length": 0,
        "audio_duration_seconds": 0,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.37ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Extract delivery note

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Delivery Note Extract data from delivery notes and packing slips. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | | idp_collect.

**Tool-ID:** `po_extraction_delivery_note` • **Cost:** 10 credits • **MCP:** `po_extraction_delivery_note` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "delivery_note") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654598.9458_266ca8b14059b53b3b982b115b6d597d",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "6017.45ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YGV3UZSGMDUw0FFWwBR31bVmdWA2R-QAgLMQdBellEeA1BYwBBblZAfBkfKlAIfl8LJG9eeAk1egVbbw5NdwNPeh1XeQBHCAAEZwVGbVdMflwNZwZZYi0ZDFpkU0N6AUd9A0JlUkFsbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU53BkI"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.8912742137908936,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.891,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654603.024725",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654600.4387_ad42b7f2884125105ce2539cfe5d7796_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1412,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 891,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 502,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5888
    },
    "status": "success",
    "timing": {
        "actual_ms": 5954.87,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.9,
        "speed_factor": 34.5,
        "performance": "34.5x faster than expected 🚀"
    }
}
```

### Extract purchase order

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Purchase Order Extract purchase order data. Fields: order_number, date, vendor, buyer, items, delivery_date, total Parameter: | Param | Type | Required | |-------|------|----------| | file_1 | file | Yes | | model | string | Yes |

**Tool-ID:** `po_extraction_purchase_order` • **Cost:** 10 credits • **MCP:** `po_extraction_purchase_order` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "order") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654605.1471_0ccdc70323e775157c5130121ab6ad79",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "4382.93ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YFXngZQGMMUA1SQ2xQTXEOWGQHU2Z_HVheNgtFL10UfQxCYlRNbwZDcRkfKlAIfl8LJG9eeAk1egVbbw5NdwBGdx1feQ9ECFdSZ1RMYQJCfQ1dZQcEMngeAF4xVxN_AER8V05kAkJhbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU53Bk8"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.7108914852142334,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.711,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654607.5296416",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654605.7121_b45252a9f325bb8eb9d37bc00230eea9_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 371,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 711,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 448,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 4229
    },
    "status": "success",
    "timing": {
        "actual_ms": 4234.4,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.1,
        "speed_factor": 48.5,
        "performance": "48.5x faster than expected 🚀"
    }
}
```

### Extract shipping waybill

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Shipping Waybill Extract data from shipping waybills and freight documents. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision required | | i.

**Tool-ID:** `po_extraction_shipping_waybill` • **Cost:** 10 credits • **MCP:** `po_extraction_shipping_waybill` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "shipping_waybill") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654609.5822_e34abd46bd4cfd7ed1860ae9c7a11a7d",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5512.88ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YFXnQZRG8AVA0GQzgMQ3hdCjUFV2UuSwheaVFFKw5AeAwSYAFHYANMKBkfKlAIfl8LJG9eeAk1egVbbw5NdwBGex1bdQNACANSMwhCaFEQLA9ZZlZSYnhBWl41BEd6ABR-AkRrB004bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU53B0M"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.8959853649139404,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.896,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654613.2638056",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654611.03_28b06f5873a95b9c753e633f4b0b586d_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1384,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 896,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 452,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5435
    },
    "status": "success",
    "timing": {
        "actual_ms": 5447.26,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.7,
        "speed_factor": 37.7,
        "performance": "37.7x faster than expected 🚀"
    }
}
```

### Extract construction plan/blueprint

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Construction Plan / Blueprint Extract data from construction plans and technical drawings. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Document file PDF, PNG, JPG | | model | string | Yes | premium or ultra vision.

**Tool-ID:** `po_extraction_construction_plan_blueprint` • **Cost:** 10 credits • **MCP:** `po_extraction_construction_plan_blueprint` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "ultra") |
| `idp_collection` | string | No | Idp collection (default: "construction_plan") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654645.5188_5a37ae295296c46b4dd590debdac3e72",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5869.53ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YFWngZRGUEVA0FTG0CQH9dWGAKAGcpSwFYYAtPfV4SfVVEYgNAbVVFLBkfKlAIfl8LJG9eeAk1egVbbw5NdwBCdx1bfwdACABdZgZBb1FCeQAOZFFSa35IAFRjVBV_WUJ8AENmUUQ8bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU53A0c"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.697474479675293,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.697,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654649.3439326",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654647.4434_afcb2a14d26f87a75774d612c8c1cbe1_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1781,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 697,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 463,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5687
    },
    "status": "success",
    "timing": {
        "actual_ms": 5745.2,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.8,
        "speed_factor": 35.8,
        "performance": "35.8x faster than expected 🚀"
    }
}
```

### Extract vehicle registration

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Vehicle Registration Extract vehicle registration data. Fields: plate_number, make, model, VIN, owner, registration_date

**Tool-ID:** `po_extraction_vehicle_registration` • **Cost:** 10 credits • **MCP:** `po_extraction_vehicle_registration` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | Idp collection (default: "vehicle_license") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | Processing priority. >=900 = synchronous (result inline), <900 = async (poll with po_jobs_get_job_status_result). Default: 900 |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654651.5254_f567baa3b3830f4c1dc53c2369ff2f31",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5167.77ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YFW3wZRGUCUw1XQ2wGQHhYDDYFVmdyTV0JZAtDKlpBeVJHZwMSPAtMKxkfKlAIfl8LJG9eeAk1egVbbw5NdwBDcx1bfwFHCFJSZwJBaFQWLw9YZApUNy9MAFg0UEZ7XkF5ABE3D007bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU53A0A"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6931095123291016,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.693,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654654.7566893",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654653.2758_65ae889482878f11b8fea12d48f08688_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1587,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 693,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 379,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 4990
    },
    "status": "success",
    "timing": {
        "actual_ms": 5039.08,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.5,
        "speed_factor": 40.8,
        "performance": "40.8x faster than expected 🚀"
    }
}
```

### Execute template

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Execute Workflow Template Run a workflow template with input data. --- Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | template_id | string | ✅ | Template to execute | | input | object | ✅ | Input data for workflow | --- Response json {.

**Tool-ID:** `po_workflow_templates_execute_template` • **Cost:** 10 credits • **MCP:** `po_workflow_templates_execute_template` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `uuid` | string | Yes | UUID of the auszufuehrenthe Templates |
| `input_data` | object | No | inputdaten for the Workflow-execution |
| `file` | string | No | file-reference (e.g. pofid) for the Workflow |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. (default: 800) |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654691.5286_fbda247aeb15d1ffe19ba3127b978790",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "4348.96ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YFV3wZRGQEXA0CTTsCQCpaVmdSU2RyGQ8OMgtBeAsXeAJFNgASPAEWKxkfKlAIfl8LJG9eeAk1egVbbw5NdwBPcx1bfgdICAdcMAZBOlZMflhdZwoAZSgaAFpmARB6DkMoAxE3BRc7bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU53D0M"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6403896808624268,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.64,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654693.9272263",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654692.1243_666d9c89713fc33ed9c737f17a84fc41_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 482,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 640,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 371,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 4197
    },
    "status": "success",
    "timing": {
        "actual_ms": 4232.26,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.1,
        "speed_factor": 48.6,
        "performance": "48.6x faster than expected 🚀"
    }
}
```

---

## Document AI — PDF

### Add password to PDF

`POST https://api.paperoffice.ai/latest/job/add/workflow`

PDF Password Protection Add password protection to PDF documents. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | PDF file | | password | string | Yes | Password to set | | permissions | string | No | Allowed actions .

**Tool-ID:** `po_pdfstudio_security_password_add` • **Cost:** 10 credits • **MCP:** `po_pdfstudio_security_password_add` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `password` | string | No | Password |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654617.5925_88e1dc56527ae50a9a4566c2bc180d17",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5970.77ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YFX3oZRG4AOmUFET0CRXtYWDNXBDUtTl1eZ1ZEfgpFLVBPZVNAbAdBZkYAJFhMOVoGGQlXeGZbfAVZbA1MdQdBbAZXeWhGY1EBZQFGOAIWLVwJNgUFYHwcC11iBhcqAEYoAEJmAys_WhksaV91AVFiGxQoVxt5Dl1-BFlsDEpw"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6400752067565918,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.64,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654621.6452067",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654619.8362_0f59aea85744a437dc8cf622b8fc4a79_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 2064,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 640,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 375,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5796
    },
    "status": "success",
    "timing": {
        "actual_ms": 5846.65,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.8,
        "speed_factor": 35.1,
        "performance": "35.1x faster than expected 🚀"
    }
}
```

### Compress PDF

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Compress PDF to reduce file size

**Tool-ID:** `po_pdfstudio_compress` • **Cost:** 20 credits • **MCP:** `po_pdfstudio_compress` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `quality` | string | No | Compression quality: low (72dpi, smallest), medium (150dpi, balanced), high (300dpi, best quality), lossless (no quality loss) (allowed: low, medium, high, lossless) (default: "medium") |
| `linearize` | boolean | No | Linearize PDF for fast web view (default: true) (default: true) |
| `remove_metadata` | boolean | No | Remove metadata during compression (default: false) |
| `priority` | integer | No | Processing priority (>=900 = synchronous) |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654378.1313_39096bdeda74feed134d55da5f736278",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "4372.75ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YAWXUZQGQGUg0HTDwDEStcCzNWAGB6Sw4ONQtEfl5EeFAUMQVGOgFNcRkfKlAIfl8LJG9eeAk1egVbbw5NdwVBeh1ffgVGCAJdNwcQO1ARKlwOYwJSZCgdAF9gVEN6XBIvBkUxBUxhbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5yDkQ"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.7039504051208496,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.704,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654380.4494991",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654378.6775_d210744f527e915177f757d954904aaa_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 381,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 704,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 441,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 4154
    },
    "status": "success",
    "timing": {
        "actual_ms": 4238.08,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.1,
        "speed_factor": 48.5,
        "performance": "48.5x faster than expected 🚀"
    }
}
```

### Convert eBook to PDF

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Convert E-Books to PDF - Supports EPUB, MOBI, AZW3, FB2 formats

**Tool-ID:** `po_dataripper_ebook2pdf` • **Cost:** 10 credits • **MCP:** `po_dataripper_ebook2pdf` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | E-Book files (EPUB, MOBI, AZW3, FB2) |
| `output_format` | string | No | Output format (default: pdf) (allowed: pdf) (default: "pdf") |
| `page_size` | string | No | page size (allowed: A4, A3, Letter) (default: "A4") |
| `margin` | integer | No | pagesrand in mm (default: 20) |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654345.1787_be9dd2443153972b89acdb0728581e68",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "4076.92ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YAWngZQG9rXGEAQD9UF39fWGMAB2AtT1wOMlBFL1pJfQVOZQNBYVVaOVkOLBwLPFc7fwBXFwhdfAdabwxLdwNYcwsxdARAY1IEMAcSbgZGLwoJZ1YCMSlLWA9oA0d3D0V5DBENUR01Vip5Bl91AE8jWwM6AVB_DFx-BF1uAQ"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.7020864486694336,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.702,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654347.2095928",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654345.7196_512cbb1096cba51d8561484f8b2f02d9_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 371,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 702,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 449,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 3816
    },
    "status": "success",
    "timing": {
        "actual_ms": 3932.7,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 1.9,
        "speed_factor": 52.3,
        "performance": "52.3x faster than expected 🚀"
    }
}
```

### Convert image to PDF

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Convert images to PDF documents - Supports JPG, PNG, TIF, TIFF

**Tool-ID:** `po_dataripper_image2pdf` • **Cost:** 10 credits • **MCP:** `po_dataripper_image2pdf` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | image files (JPG, PNG, TIF, TIFF) |
| `fit_to_a4` | boolean | No | Scale the image to A4 format with a white background (default: false) |
| `merge` | boolean | No | Merge all bills into a single PDF (default: true) (default: true) |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654353.8822_e4a74aacb5dd13bfa15e9c33a10a0f59",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5679.77ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YAW34ZSW8DVw0BFW4NTSgIX2VSUmYpQAxdNQBEfFxDfw0TNAIVaAtMcRkfKlAIfl8LJG9eeAk1egVbbw5NdwVDcR1WdQBDCAQEZQlMOARFfFhcZVFZZnsdC19iVkR9ARUqARZjD01hbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5yA08"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6920878887176514,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.692,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654357.5240488",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654355.8316_6c026123509cd21e7533c7ca6ac2a501_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1796,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 692,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 416,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5455
    },
    "status": "success",
    "timing": {
        "actual_ms": 5545.02,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.7,
        "speed_factor": 37.1,
        "performance": "37.1x faster than expected 🚀"
    }
}
```

### Convert office document to PDF

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Convert Office documents to PDF — Supports DOCX, DOC, XLSX, XLS, PPTX, PPT, ODS, ODT, ODP, RTF. Uses Windows VM clusters with genuine Microsoft Office for maximum conversion fidelity.

**Tool-ID:** `po_dataripper_office2pdf` • **Cost:** 10 credits • **MCP:** `po_dataripper_office2pdf` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | Office-files (DOCX, DOC, XLSX, XLS, PPTX, PPT, PPS, ODS, ODT, ODP, RTF) |
| `provider` | string | No | Conversion Engine (automatic selection for optimal quality) (allowed: auto) (default: "auto") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654361.2879_3dae3b4d94e37dc9f316a9914bfa3d8f",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "7585.1ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YAWHwZQ28NVA1QQm8HF3sMWDMCUGcvSFpcZgdGLw8XegdFa1IQagVAeRkfKlAIfl8LJG9eeAk1egVbbw5NdwVAcx1cdQ5ACFVTZAMWawBCKgheZFdRMHpODF0xBRB4C0N1URNhAUFpbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5yAEE"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.699702262878418,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.7,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654365.466351",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654363.7865_2ae9511cf6a14813ed8d540f19421be2_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 2308,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 700,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 362,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5895
    },
    "status": "success",
    "timing": {
        "actual_ms": 5923.54,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.9,
        "speed_factor": 34.7,
        "performance": "34.7x faster than expected 🚀"
    }
}
```

### Convert PDF to Excel

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Convert PDF to Excel spreadsheet (XLSX)

**Tool-ID:** `po_pdfstudio_convert_to_excel` • **Cost:** 30 credits • **MCP:** `po_pdfstudio_convert_to_excel` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `priority` | integer | No | Processing priority (>=900 = synchronous) |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654382.5438_4d05b6958656f0825c1ae6281eed3854",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5355.43ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YAVn8ZRGMBVA1QQDoGE3sBCWZRBWd8SglVYAdBLwBHKgwRZlJHO1ZGcBkfKlAIfl8LJG9eeAk1egVbbw5NdwVOcB1beQJACFVRMQISaw0Tf1sLZARTY3NIDFoxCkAoABd4UUQwUkdgbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5yDkE"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.7024493217468262,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.702,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654385.973423",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654384.263_19115b832ea6d0e103bdf9cd7df42d65_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1569,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 702,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 390,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5224
    },
    "status": "success",
    "timing": {
        "actual_ms": 5242.16,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.6,
        "speed_factor": 39.2,
        "performance": "39.2x faster than expected 🚀"
    }
}
```

### Convert PDF to JPG

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Convert PDF pages to JPG images

**Tool-ID:** `po_pdfstudio_convert_to_jpg` • **Cost:** 10 credits • **MCP:** `po_pdfstudio_convert_to_jpg` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `quality` | integer | No | Quality (Integer) (default: 70) |
| `max_size` | integer | No | Max size (Integer) (default: 1200) |
| `dpi` | integer | No | Resolution in DPI (default: 150) (default: 150) |
| `priority` | integer | No | Processing priority (>=900 = synchronous) |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654390.2458_4f721489c2e8cd3aa2ce070b5c2c2d53",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "9544.04ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YAV30ZQ2MCUg0FRGkBFi0PCmhWWGsvSFpUYgIXfQxIdAUSawBGOgoTfhkfKlAIfl8LJG9eeAk1egVbbw5NdwVPch1ceQFGCABVYgUXPQMQcVxWaFdRMHJKCQxjBk92CRR1A0UxDhJubBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5yD0E"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6934890747070312,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.693,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654394.7584946",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654392.6406_7addac3758c87a8c1a4dcc3ee3ec55fd_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 2248,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 693,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 363,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 7050
    },
    "status": "success",
    "timing": {
        "actual_ms": 7129.15,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 3.5,
        "speed_factor": 28.8,
        "performance": "28.8x faster than expected 🚀"
    }
}
```

### Convert PDF to PDF/A

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Convert PDF to PDF/A for archiving

**Tool-ID:** `po_pdfstudio_convert_to_pdfa` • **Cost:** 20 credits • **MCP:** `po_pdfstudio_convert_to_pdfa` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `level` | string | No | Level (allowed: pdfa-1b, pdfa-2b, pdfa-3b) (default: "pdfa-2b") |
| `priority` | integer | No | Processing priority (>=900 = synchronous) |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654397.4948_506bc6d872b4553d806e74e068749b36",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5173.78ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YAV3oZRW4CVw1UTTxRTXENWzEKVmB8TQgPYgJHLF1EdAIRY1UVYAsRexkfKlAIfl8LJG9eeAk1egVbbw5NdwVPdR1adAFDCFFcN1VMYQFBKABYYwRUYilKCVwyV0N2Dhd9VhZrDxBrbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5xBkQ"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.532494068145752,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.532,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654400.965616",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654399.3785_45c8955ff324276980a4e624b9f559d6_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1769,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 532,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 328,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5108
    },
    "status": "success",
    "timing": {
        "actual_ms": 5133.72,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.5,
        "speed_factor": 40,
        "performance": "40x faster than expected 🚀"
    }
}
```

### Convert PDF to PowerPoint

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Convert PDF to PowerPoint presentation (PPTX)

**Tool-ID:** `po_pdfstudio_convert_to_powerpoint` • **Cost:** 30 credits • **MCP:** `po_pdfstudio_convert_to_powerpoint` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `priority` | integer | No | Processing priority (>=900 = synchronous) |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654402.7658_1b44af85f3254c89ace92354ee65f7a3",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "8212.15ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YHXn8ZRmEDVg1XEm0FRi1dDWVSVWooSAxbY1dBdg5ALgRCZVERagZHLRkfKlAIfl8LJG9eeAk1egVbbw5NdwJGcB1ZewBCCFIDZgFHPVEXfFhbaVBRZn1LXFpoBEcsCER7UhJhAkY9bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5xB0Y"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.4030604362487793,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604424774646759,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.403,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654406.850579",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654404.2345_2200c2f6408d999d13db610f873a0cb3_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1422,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 403,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 1516,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 8157
    },
    "status": "success",
    "timing": {
        "actual_ms": 8162.95,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 4,
        "speed_factor": 25.2,
        "performance": "25.2x faster than expected 🚀"
    }
}
```

### Convert PDF to WebP

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Convert PDF pages to WebP images

**Tool-ID:** `po_pdfstudio_convert_to_webp` • **Cost:** 10 credits • **MCP:** `po_pdfstudio_convert_to_webp` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `quality` | integer | No | Quality (Integer) (default: 70) |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654411.0946_46e672e677964459791f4745f0dec88e",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5873.7ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YHX3wZQW4COjACF28AEX0LDWcGVzV-GVhUaQQSKA5FdABPMVQRbwtCZkYAJFhMOVoGGQlXeGZbfAVZbA1MdwdHbANXe2gTZFdTZ1VAa1dCfA8JZVIAanJOXQtmBk56ABIvUUFqACs_WhksaV91AVFiGxQoVxt5Dl1-BFlsCkl1"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.689058780670166,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.689,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654415.0234423",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654413.0639_7d2ef35e23c0c334a5f765232405ec69_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1810,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 689,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 409,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5732
    },
    "status": "success",
    "timing": {
        "actual_ms": 5748.24,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.8,
        "speed_factor": 35.8,
        "performance": "35.8x faster than expected 🚀"
    }
}
```

### Convert PDF to Word

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Convert PDF to Word document (DOCX)

**Tool-ID:** `po_pdfstudio_convert_to_word` • **Cost:** 30 credits • **MCP:** `po_pdfstudio_convert_to_word` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `priority` | integer | No | Processing priority (>=900 = synchronous) |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654419.2579_3b35003e6ddd7f2be07f987b234e6b67",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "6605.09ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YHX3QZQ2EEVA0HEDwNQnwNVmlVWGEuG19cMlFDLF1BfQ1FYARMOFEUehkfKlAIfl8LJG9eeAk1egVbbw5NdwJHex1cewdACAIBNwlDbAFMcF9WYlYCNXoaWlgyV0Z_AUN-B08zVRVqbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5xBEU"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6467900276184082,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.647,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654421.6651525",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654419.8632_1f98a406aa7ea883b9639e8a1b044322_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 444,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 647,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 357,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 4160
    },
    "status": "success",
    "timing": {
        "actual_ms": 4236.21,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.1,
        "speed_factor": 48.5,
        "performance": "48.5x faster than expected 🚀"
    }
}
```

### Convert URL to PDF

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Convert webpage URL to PDF with full browser support (cookies, headers, inject CSS/JS)

**Tool-ID:** `po_pdfstudio_url_to` • **Cost:** 30 credits • **MCP:** `po_pdfstudio_url_to` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `url` | string | Yes | URL to convert (http:// or https://) |
| `screen_width` | integer | No | Browser viewport width in pixels (default: 1920) |
| `screen_height` | integer | No | Browser viewport height in pixels (default: 1080) |
| `page_size` | string | No | PDF page size (allowed: A4, A3, A5, Letter, Legal, Tabloid) (default: "A4") |
| `page_orientation` | string | No | Page orientation (allowed: portrait, landscape) (default: "portrait") |
| `page_margins` | integer | No | Page margins in pixels (default: 20) |
| `scale` | string | No | Scale factor 0.1-2.0 (default: "1") |
| `print_background` | string | No | Print background colors/images (true/false) (allowed: true, false) (default: "true") |
| `page_ranges` | string | No | Pages to print, e.g. 1-5,8 |
| `header_template` | string | No | HTML header template |
| `footer_template` | string | No | HTML footer template |
| `remove_classes` | string | No | CSS selectors to remove |
| `inject_css` | string | No | Custom CSS to inject |
| `inject_js` | string | No | JavaScript to execute |
| `cookies` | string | No | JSON array of cookies |
| `extra_headers` | string | No | JSON object of HTTP headers |
| `user_agent` | string | No | Custom User-Agent |
| `wait_until` | string | No | Navigation completion event (allowed: load, domcontentloaded, networkidle0, networkidle2) (default: "networkidle0") |
| `timeout` | integer | No | Navigation timeout in ms (default: 60000) |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654454.413_32594e7c045b96b392b9334cfe3ffe7a",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5796.58ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YHW3kZRWYAUA1TQG4BES0PXDJSBDF7Tl9ZMwtGLQFHdQUVM1VEOlFGehkfKlAIfl8LJG9eeAk1egVbbw5NdwJDdh1afANECFZRZQUQPQNGK1gKMgNXNX8bAF0zC0B3CRMtVkcxVUdqbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5xAEY"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6359515190124512,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604068398475647,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.636,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654458.3125262",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654456.6356_f952627afa69af5fdafb29f3f74b1e3a_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 2062,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 636,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 364,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5639
    },
    "status": "success",
    "timing": {
        "actual_ms": 5643.66,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.7,
        "speed_factor": 36.4,
        "performance": "36.4x faster than expected 🚀"
    }
}
```

### Edit PDF metadata

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Edit PDF metadata (title, author, etc.)

**Tool-ID:** `po_pdfstudio_edit_metadata` • **Cost:** 10 credits • **MCP:** `po_pdfstudio_edit_metadata` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `oproation` | string | No | Oproation: edit (modify metadata fields), remove (clear all metadata), read (return current metadata) (allowed: edit, remove, read) (default: "edit") |
| `metadata` | object | No | Metadata object with fields to set |
| `priority` | integer | No | Processing priority (>=900 = synchronous) |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654423.6657_6c33e053875178e85679aae91ed941a2",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "4462.84ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YHXH4ZR2EDVw0AQWwGTSgJCTUGADB8T18JZQMQLV5Je1BPYA5HO1VAKhkfKlAIfl8LJG9eeAk1egVbbw5NdwJEcR1YewBDCAVQZwJMOAUTLAwOMwRWNS9NCAszVE55XEl-DUQwUUE6bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5xBE4"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6994514465332031,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.699,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654426.1319084",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654424.2719_19045aab3eea573ffbb9a683dd92a76d_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 396,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 699,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 432,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 4263
    },
    "status": "success",
    "timing": {
        "actual_ms": 4334.07,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.1,
        "speed_factor": 47.4,
        "performance": "47.4x faster than expected 🚀"
    }
}
```

### Merge pdf

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Merge multiple PDFs into one

**Tool-ID:** `po_pdfstudio_merge` • **Cost:** 20 credits • **MCP:** `po_pdfstudio_merge` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files to merge |
| `order` | array | No | Merge order |
| `priority` | integer | No | Processing priority (>=900 = synchronous) |
| `output_filename` | string | No | Name of the merged output file (default: "merged.pdf") |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654428.0912_ffce62fac63718fb99381055eab693b1",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "8116.09ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YHXHUZQW4GUw1XRW1XRCwLCjMEWTUqT18JaVZOKgESewRDZVMQagNBfBkfKlAIfl8LJG9eeAk1egVbbw5NdwJEeh1edAVHCFJUZlNFPAcQKg5XNlJWNS9BXVU0CxV5CEV7UBNhB0BsbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5xBUA"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.40227341651916504,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.604424774646759,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.402,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654432.2661028",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654429.6128_2b58fa89d06c7c6883c3915fa57e6cdf_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1410,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 402,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 1373,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 8059
    },
    "status": "success",
    "timing": {
        "actual_ms": 8065.15,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 3.9,
        "speed_factor": 25.5,
        "performance": "25.5x faster than expected 🚀"
    }
}
```

### Remove password from PDF

`POST https://api.paperoffice.ai/latest/job/add/workflow`

PDF Password Removal Remove password protection from PDF requires current password. Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_1 | file | Yes | Protected PDF | | password | string | Yes | Current password | | priority | int | No .

**Tool-ID:** `po_pdfstudio_security_password_remove` • **Cost:** 10 credits • **MCP:** `po_pdfstudio_security_password_remove` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaproOffice File ID to decrypt the PDFs |
| `password` | string | Yes | AktuCurrent PDF password (required to remove protection) |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output_files": []
    }
}
```

### Remove restrictions

`POST https://api.paperoffice.ai/latest/job/add/workflow`

PDF Remove Restrictions Remove printing/editing restrictions. Parameters: | Param | Type | Required | |-------|------|----------| | file_1 | file | Yes | | password | string | No |

**Tool-ID:** `po_pdfstudio_security_remove_restrictions` • **Cost:** 10 credits • **MCP:** `po_pdfstudio_security_remove_restrictions` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | File 1 |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654623.9462_0a35b25ebe00b4e995d955c5e7288853",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "4362.29ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YFXH4ZSGMDUA1SRGEGFChYCTYGBGcoSl1cNgEQfQBFKVZAawFDYVERLxkfKlAIfl8LJG9eeAk1egVbbw5NdwBEcR1XeQBECFdVagIVOFQTLwwKZFBTN3oeCgtjCkIrWkZ1AkBqVRA_bBMgWgoaAVFjBVVoQAkvRVt8BVlsDU53BE4"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.70334792137146,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.703,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654626.3466623",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654624.4659_ba4a8916f6d0530ce5e58c5ce8a03361_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 386,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 703,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 434,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 4230
    },
    "status": "success",
    "timing": {
        "actual_ms": 4235.29,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.1,
        "speed_factor": 48.5,
        "performance": "48.5x faster than expected 🚀"
    }
}
```

### Rotate pdf

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Rotate individual or all pages of a PDF document by 90, 180, or 270 degrees.

**Tool-ID:** `po_pdfstudio_rotate` • **Cost:** 10 credits • **MCP:** `po_pdfstudio_rotate` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `angle` | string | No | Rotation angle in degrees (clockwise): 90, 180, or 270 (allowed: 90, 180, 270) (default: "90") |
| `priority` | integer | No | Processing priority (>=900 = synchronous) |
| `page_range` | string | No | Pages to rotate: "all" (default) or specific pages like "1-5,7,9-10" (default: "all") |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654436.424_4cba19abf7d09d733d04020eab63e896",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5687.97ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YHXXsZRWUBUw0FEmkBFH0JV2cFUDZ_SA8OYgpALAFIe1ZPawcSPAETcRkfKlAIfl8LJG9eeAk1egVbbw5NdwJFdB1afwJHCAADYgUVbQVNfg9eNQdRZShKAVsyC095Wkl1BBE3BRJhbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5xAkc"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6594524383544922,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.659,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654440.169053",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654438.4791_0df99c04a9edc6eeacd1d8e28128e397_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1891,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 659,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 397,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5498
    },
    "status": "success",
    "timing": {
        "actual_ms": 5549.24,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.7,
        "speed_factor": 37,
        "performance": "37x faster than expected 🚀"
    }
}
```

### Split PDF

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Split PDF into individual pages

**Tool-ID:** `po_pdfstudio_split` • **Cost:** 20 credits • **MCP:** `po_pdfstudio_split` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF file to split |
| `mode` | string | No | Split mode: burst = every page becomes a separate PDF (default), ranges = custom page ranges via splits parameter (allowed: burst, ranges) (default: "burst") |
| `splits` | array | No | For ranges mode: Array of split definitions. Each item has pages (e.g. 1-5,7) and optional filename. |
| `output_prefix` | string | No | prefix for burst mode output filenames (default: page_) |
| `priority` | integer | No | Processing priority (>=900 = synchronous) |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654442.314_d9be391fca3dc86ca6210431506c4440",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5991.98ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YHWn8ZQmYBVg0CFj8HFHlYXzMCUzd8GgpeZAdAKlpFeVBANAJMbQQUfRkfKlAIfl8LJG9eeAk1egVbbw5NdwJCcB1dfAJCCAcHNAMVaVRFKghdNAQDYHhMDFs0UEJ7XEYqAU9mABVtbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5xAk4"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6832687854766846,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.683,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654446.2546413",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654444.2707_46a046de70ff3d08ab1a56fc4f825607_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1769,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 683,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 437,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5770
    },
    "status": "success",
    "timing": {
        "actual_ms": 5848,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.8,
        "speed_factor": 35.1,
        "performance": "35.1x faster than expected 🚀"
    }
}
```

### Split PDF via AI

`POST https://api.paperoffice.ai/latest/job/add/workflow`

PDF AI Split Automatically detect and split multi-document PDFs into individual files using AI Vision analysis. --- When to Use - Batch Scanning - Split a stack of scanned documents into individual files - Mail Processing - Separate multiple letters/invoices from one scan - Archive Digitization -.

**Tool-ID:** `po_editing_pdf_ai_split` • **Cost:** 50 credits • **MCP:** `po_editing_pdf_ai_split` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file` | string | Yes | PDF file to analyze and split |
| `template` | string | No | Workflow template name required (default: "pdf_ai_split") |
| `naming_instruction` | string | No | Naming pattern for output files optional (default: "documenttyp_Datum_Absender") |
| `locale` | string | No | Locale for ALL output: 'de_DE', 'en_US', 'fr_FR' - affects document_type, reasoning, filenames (default: "de_DE") |
| `document_types` | string | No | Allowed types, comma-separated: 'invoice,Schreiben,quote' optional (default: "") |
| `date_format` | string | No | Date format: 'YYYY-MM-DD', 'DD.MM.YYYY', 'MM/DD/YYYY' optional (default: "DD.MM.YYYY") |
| `include_document_type` | string | No | Include document_type in response default: false (default: "false") |
| `include_date` | string | No | Include date in response default: false (default: "false") |
| `include_sender` | string | No | Include sender in response default: false (default: "false") |
| `include_reasoning` | string | No | Include reasoning in response default: false (default: "false") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. (default: "900") |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654328.0845_ab8695465587702c24142952f7c95d60",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5472.91ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YAXHUZQW8BUg0DEWEMFy0JWTVVBDB9SVoLYANBLwESelFOMQJBPFIRfRkfKlAIfl8LJG9eeAk1egVbbw5NdwVEeh1edQJGCAYAaggWPQVDLF8KMwVQMC1ICFoxCxV4XUgvAUI3VhBtbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5yBUU"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.6907424926757812,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.691,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654331.589059",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654329.8444_826f8d8ee74b3b304f5ae72d73e9752e_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1592,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 691,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 394,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5244
    },
    "status": "success",
    "timing": {
        "actual_ms": 5341.58,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.6,
        "speed_factor": 38.5,
        "performance": "38.5x faster than expected 🚀"
    }
}
```

### Unlock PDF with password

`POST https://api.paperoffice.ai/latest/job/add/workflow`

Remove password from PDF (password required)

**Tool-ID:** `po_pdfstudio_unlock_with_password` • **Cost:** 10 credits • **MCP:** `po_pdfstudio_unlock_with_password` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `password` | string | Yes | Current password |
| `priority` | integer | No | Processing priority (>=900 = synchronous) |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654448.4695_14c1ce6abf988e853cb4258a4ed88087",
    "message": "Job processed successfully",
    "model": "basic",
    "operation": "document_idp",
    "pipeline": "workflow",
    "processing_time": "5779.95ms",
    "result": {
        "pages_idp": [
            {
                "suggested_fields": []
            }
        ],
        "pages_images": {
            "00001": "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxUDWtaCCpmU3sCM2sPT3YAQ3YHWnUZRWAEXQ0HR2gAFytYV2ABADF_GgoIZwNAKlwQeQQSYQBGO1EXcBkfKlAIfl8LJG9eeAk1egVbbw5NdwJCeh1aegdJCAJWYwQWO1RNeQsOMgcDYC5PCFs0Vhd7CBR_A0UwVRZgbBMgWgoaAVFjBVVoQAkvRVt8BVlsDU5xA0I"
        },
        "pages_aiocr": {
            "simplified_boxes": [],
            "simplified_boxes_compact": "",
            "pages": {
                "00001": {
                    "ocr_text": "",
                    "line_count": 0,
                    "confidence_avg": 0,
                    "processing_time": 0.64095139503479,
                    "char_count": 0,
                    "original_image_width": 1545,
                    "original_image_height": 2000,
                    "language": {
                        "primary": "unknown",
                        "primary_name": "Unknown",
                        "confidence": 0,
                        "all_detected": []
                    },
                    "bounding_boxes": [],
                    "simplified_boxes": [],
                    "qr_barcode_count": 0,
                    "layout_data": [
                        {
                            "label": "Form",
                            "confidence": 0.6112901568412781,
                            "position": 0,
                            "polygon": [
                                [
                                    9.052734375,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    0
                                ],
                                [
                                    1535.947265625,
                                    2000
                                ],
                                [
                                    9.052734375,
                                    2000
                                ]
                            ]
                        }
                    ]
                }
            },
            "summary": {
                "total_pages": 1,
                "total_lines": 0,
                "total_chars": 0,
                "avg_confidence": 0,
                "total_processing_time": 0.641,
                "combined_text": "***Page 1 of 1***\n\n",
                "poaiocr_extracted_fulltext": "***Page 1 of 1***\n\n",
                "total_bounding_boxes": 0,
                "processing_engine": "paperoffice_ai_ocr_neural_v3.0",
                "ocr_tier": "ultra",
                "created_at": "1775654452.2700465",
                "searchable_pdf_path": "/tmp/processing/poai-job_899_1775654450.5793_476c5b464fffe49cb8dc26474970e382_searchable.pdf"
            },
            "total_pages": 1,
            "total_lines": null,
            "total_chars": null,
            "avg_confidence": null,
            "markdown": null
        },
        "fulltext": "***Page 1 of 1***\n\n",
        "steps": [
            {
                "id": "pdf2png",
                "name": "Convert PDF to PNG",
                "status": "completed",
                "duration_ms": 1977,
                "server": null
            },
            {
                "id": "ocr",
                "name": "AI-OCR with Layout-Detection",
                "status": "completed",
                "duration_ms": 641,
                "server": "api-server"
            },
            {
                "id": "extract",
                "name": "LLM Datenextraktion",
                "status": "completed",
                "duration_ms": 380,
                "server": null
            }
        ],
        "total_steps": 3,
        "duration_ms": 5557
    },
    "status": "success",
    "timing": {
        "actual_ms": 5645.01,
        "expected_ms": 205500,
        "timeout_ms": 295000,
        "accuracy_percent": 2.7,
        "speed_factor": 36.4,
        "performance": "36.4x faster than expected 🚀"
    }
}
```

---

## Documentation & Discovery

### Get MCP server AI integration info

`POST https://api.paperoffice.ai/latest/docs/markdown`

🤖 MCP Server - AI Tool integration Model Context Protocol MCP enables AI assistants to directly use PaperOffice tools. --- 🔗 Server URL https://api.paperoffice.ai/latest/mcp --- ⚡ Quick Setup Cursor IDE Remote MCP 1. Open Cursor Settings → MCP 2. Add new Remote MCP Server 3. Enter URL: htt.

**Tool-ID:** `po_documentation_mcp_server_ai_integration` • **Cost:** 10 credits • **MCP:** `po_documentation_mcp_server_ai_integration` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "processing_time": "13.41ms",
    "status": "success"
}
```

### Get Postman collection

`POST https://api.paperoffice.ai/latest/docs/postman`

Complete Postman Collection with all endpoints. Direct URL: https://api.paperoffice.ai/latest/docs/postman Import to Postman: 1. Copy URL above 2. File → Import → Link 3. Paste and Import

**Tool-ID:** `po_documentation_postman_collection` • **Cost:** 10 credits • **MCP:** `po_documentation_postman_collection` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "status": "success",
    "message": "Response truncated"
}
```

---

## Media AI — Image Studio

### Generate image (basic, max 512x512)

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_imagestudio___generate`

AI Image Generation (Basic Tier) Generates images using Z-Image-Turbo AI. Max resolution: 512x512 (16px grid). Parameters:
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| prompt | string | Yes | Text description of the image to generate |
| model | string | No | Tier: basic (default), premium, ultra |
| width | int | No | Image width, max 512 for basic tier, snapped to 16px grid |
| height | int | No | Image height, max 512 for basic tier, snapped to 16px grid |
| num_images | int | No | Number of images to generate (default: 1) |
| negative_prompt | string | No | What to avoid in the generated image |
| seed | int | No | Fixed seed for reperducibility (-1 = random) |
| steps | int | No | Generation quality steps (default: 15) |
| guidance_scale | float | No | Prompt adherence strength (default: 4.0) |
| precompile_prompt | bool | No | AI-optimize prompt before generation (default: true, set false for raw/exact prompts) |
| output | string | No | Response format: url (JSON with download URLs), inline (raw image binary), base64 (JSON with base64 data) |
| priority | int | No | >=900 for synchronous processing, <900 for async (returns job_id) | Common Use Cases:
- Icons/Logos: Square 512x512 with precompile_prompt=false for exact control
- Thumbnails: Small preview images
- Batch generation: Set num_images=2-10 for multiple variants
- Reperducible results: Use a fixed seed value (same seed + same prompt = same image)
- Fine-tuned quality: Increase steps (e.g. 25) and guidance_scale (e.g. 7.5)
- Negative prompts: Exclude unwanted elements (e.g. "blurry, low quality, watermark")
- Aspect ratios: Set width/height freely within max (e.g. 512x288 for landscape, 288x512 for portrait)

**Tool-ID:** `po_image_generate_image_basic_max_512x512` • **Cost:** 30 credits • **MCP:** `po_image_generate_image_basic_max_512x512` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `prompt` | string | Yes | Required. Text description of the image to generate (default: "A beautiful sunset over mountains, photorealistic, golden hour lighting") |
| `model` | string | Yes | Required. Tier: basic, premium, or ultra (default: "basic") |
| `width` | number | No | Image width max 512 for basic tier (default: "512") |
| `height` | number | No | Image height max 512 for basic tier (default: "512") |
| `num_images` | string | No | Number of images to generate default: 1 (default: "1") |
| `negative_prompt` | string | No | Optional. What to avoid in the image (default: "") |
| `seed` | string | No | Seed for reproducibility -1 = random (default: "-1") |
| `precompile_prompt` | string | No | AI-optimize prompt default: true (default: "true") |
| `output` | string | No | Output mode: url JSON with URLs, inline raw image binary, base64 JSON with base64 data (default: "inline") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |
| `steps` | string | No | Steps (default: "15") |
| `guidance_scale` | string | No | Guidance scale (default: "4.0") |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654477.5873_5b26681cbf5795b4b3888a846cc31d8c",
    "message": "Job processed successfully",
    "operation": "generate",
    "processing_time": "9626.58ms",
    "result": {
        "status": "completed",
        "message": "1 image(s) generated (PaperOffice ImageStudio)",
        "output_mode": "url",
        "image_urls": [
            "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxqAyNeAjpYHi5WM2oJJ3MGKXADXHsHRWcMOmMCRmgHQhYJVmYHUmRlCFcKLANBeQ1HeQJFagA"
        ],
        "paperoffice_image_precompiler": {
            "enabled": true,
            "precompile_prompt": true,
            "inject_weather": true,
            "force_location": null,
            "original_prompts": [
                "What is document management?"
            ],
            "optimized_prompts": [
                "What is document management?"
            ],
            "user_context": {
                "continent": "Europe",
                "country": "Spain",
                "weather_condition": "partly cloudy",
                "temperature": 14.4,
                "season": "spring",
                "time_of_day": "night",
                "city": "Madrid"
            }
        }
    },
    "server": "api-server",
    "status": "success",
    "timing": {
        "actual_ms": 9532.98,
        "expected_ms": 130000,
        "timeout_ms": 195000,
        "accuracy_percent": 7.3,
        "speed_factor": 13.6,
        "performance": "13.6x faster than expected 🚀"
    }
}
```

### Generate image (premium, max 1280x1280)

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_imagestudio___generate`

AI Image Generation (Premium Tier) Generates high-quality images using Z-Image-Turbo AI. Max resolution: 1280x1280 (16px grid). Parameters:
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| prompt | string | Yes | Text description of the image to generate |
| model | string | No | Tier: basic, premium (default), ultra |
| width | int | No | Image width, max 1280 for premium tier, snapped to 16px grid |
| height | int | No | Image height, max 1280 for premium tier, snapped to 16px grid |
| num_images | int | No | Number of images to generate (default: 1) |
| negative_prompt | string | No | What to avoid in the generated image |
| seed | int | No | Fixed seed for reperducibility (-1 = random) |
| steps | int | No | Generation quality steps (default: 15) |
| guidance_scale | float | No | Prompt adherence strength (default: 4.0) |
| precompile_prompt | bool | No | AI-optimize prompt before generation (default: true) |
| output | string | No | Response format: url, inline (raw binary), base64 |
| priority | int | No | >=900 for synchronous processing | Common Use Cases:
- Professional photos: 1024x1024 or 1280x1280 for high detail
- Marketing materials: Landscape 1280x720 (16:9) or portrait 720x1280 (9:16)
- Batch generation: num_images=2-10 for A/B testing variants
- Product images: With negative_prompt to exclude unwanted elements
- Reperducible: Fixed seed for consistent branding

**Tool-ID:** `po_image_generate_image_premium_max_1280x1280` • **Cost:** 40 credits • **MCP:** `po_image_generate_image_premium_max_1280x1280` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `prompt` | string | Yes | Required. Text description of the image to generate (default: "A beautiful sunset over mountains, photorealistic, golden hour lighting") |
| `model` | string | Yes | Required. Tier: basic, premium, or ultra (default: "premium") |
| `width` | number | No | Image width max 1280 for premium tier (default: "1024") |
| `height` | number | No | Image height max 1280 for premium tier (default: "1024") |
| `num_images` | string | No | Number of images to generate default: 1 (default: "1") |
| `negative_prompt` | string | No | Optional. What to avoid in the image (default: "") |
| `seed` | string | No | Seed for reproducibility -1 = random (default: "-1") |
| `steps` | string | No | Generation steps default: 15 (default: "15") |
| `guidance_scale` | string | No | Guidance scale default: 4.0 (default: "4.0") |
| `precompile_prompt` | string | No | AI-optimize prompt default: true (default: "true") |
| `output` | string | No | Output mode: url JSON with URLs, inline raw image binary, base64 JSON with base64 data (default: "inline") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654487.3305_a55894bb459305b6f6e3882885ded23a",
    "message": "Job processed successfully",
    "operation": "generate",
    "processing_time": "5320.69ms",
    "result": {
        "status": "completed",
        "message": "1 image(s) generated (PaperOffice ImageStudio)",
        "output_mode": "url",
        "image_urls": [
            "https://api.paperoffice.ai/latest/job/download/ZBVXGX9AFyNcGD9fWCZSGSkcRHxbBiseETxqAyNeAjpYHi5WM2oJJ3MGKXADXHsHRWcMOmMCRmgGRxYMXmkGUGRlCFcKLANBeQ1HeQJFawU"
        ],
        "paperoffice_image_precompiler": {
            "enabled": true,
            "precompile_prompt": true,
            "inject_weather": true,
            "force_location": null,
            "original_prompts": [
                "What is document management?"
            ],
            "optimized_prompts": [
                "What is document management? photorealistic, high quality, 8k"
            ],
            "user_context": {
                "continent": "Europe",
                "country": "Spain",
                "weather_condition": "partly cloudy",
                "temperature": 14.4,
                "season": "spring",
                "time_of_day": "night",
                "city": "Madrid"
            }
        }
    },
    "server": "api-server",
    "status": "success",
    "timing": {
        "actual_ms": 5214.46,
        "expected_ms": 130000,
        "timeout_ms": 195000,
        "accuracy_percent": 4,
        "speed_factor": 24.9,
        "performance": "24.9x faster than expected 🚀"
    }
}
```

### Generate image (ultra, max 2048x2048)

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_imagestudio___generate`

AI Image Generation (Ultra Tier) Generates maximum-quality images using Z-Image-Turbo AI. Max resolution: 2048x2048 (16px grid). Parameters:
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| prompt | string | Yes | Text description of the image to generate |
| model | string | No | Tier: basic, premium, ultra (default) |
| width | int | No | Image width, max 2048 for ultra tier, snapped to 16px grid |
| height | int | No | Image height, max 2048 for ultra tier, snapped to 16px grid |
| num_images | int | No | Number of images to generate (default: 1) |
| negative_prompt | string | No | What to avoid in the generated image |
| seed | int | No | Fixed seed for reperducibility (-1 = random) |
| steps | int | No | Generation quality steps (default: 15, recommended: 25 for ultra) |
| guidance_scale | float | No | Prompt adherence strength (default: 4.0, recommended: 7.5 for ultra) |
| precompile_prompt | bool | No | AI-optimize prompt before generation (default: true) |
| output | string | No | Response format: url, inline (raw binary), base64 |
| priority | int | No | >=900 for synchronous processing | Common Use Cases:
- Print-ready images: 2048x2048 or 1536x1536 for maximum quality
- Poster/banner: Wide formats like 2048x1152 (16:9)
- Art generation: Higher steps (25+) and guidance (7.5+) for detailed output
- Large format: Billboards, presentations, high-DPI displays

**Tool-ID:** `po_image_generate_image_ultra_max_2048x2048` • **Cost:** 50 credits • **MCP:** `po_image_generate_image_ultra_max_2048x2048` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `prompt` | string | Yes | Required. Text description of the image to generate (default: "A beautiful sunset over mountains, photorealistic, golden hour lighting") |
| `model` | string | Yes | Required. Tier: basic, premium, or ultra (default: "ultra") |
| `width` | number | No | Image width max 2048 for ultra tier (default: "1536") |
| `height` | number | No | Image height max 2048 for ultra tier (default: "1536") |
| `num_images` | string | No | Number of images to generate default: 1 (default: "1") |
| `negative_prompt` | string | No | Optional. What to avoid in the image (default: "") |
| `seed` | string | No | Seed for reproducibility -1 = random (default: "-1") |
| `steps` | string | No | Generation steps default: 15 (default: "15") |
| `guidance_scale` | string | No | Guidance scale default: 4.0 (default: "4.0") |
| `precompile_prompt` | string | No | AI-optimize prompt default: true (default: "true") |
| `output` | string | No | Output mode: url JSON with URLs, inline raw image binary, base64 JSON with base64 data (default: "inline") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "job_id": "poai-job_900_1775654492.6125_4a24498d7479f0c8ae9028ca07958b91",
    "message": "Job processed successfully",
    "operation": "generate",
    "processing_time": "17179.09ms",
    "result": {
        "status": "completed",
        "message": "1 image(s) generated (PaperOffice ImageStudio)",
        "output_mode": "url",
        "image_urls": [
            "https://api.paperoffice.ai/latest/job/download/ZBVXGX9BEzxOFD4NRw1oKytSGC1fHC4eFTZYFGkBUiVQBGRCAwVfHS1TBCNHCyloQWZrVWJuRmkHQ3kNX2hsUGB5SQ1UDwVGfgFJfRoHPFAIaARCfABacwJRag"
        ],
        "paperoffice_image_precompiler": {
            "enabled": true,
            "precompile_prompt": true,
            "inject_weather": true,
            "force_location": null,
            "original_prompts": [
                "What is document management?"
            ],
            "optimized_prompts": [
                "What is document management?"
            ],
            "user_context": {
                "continent": "Europe",
                "country": "Spain",
                "weather_condition": "partly cloudy",
                "temperature": 14.4,
                "season": "spring",
                "time_of_day": "night",
                "city": "Madrid"
            }
        }
    },
    "server": "api-server",
    "status": "success",
    "timing": {
        "actual_ms": 17150.87,
        "expected_ms": 130000,
        "timeout_ms": 195000,
        "accuracy_percent": 13.2,
        "speed_factor": 7.6,
        "performance": "7.6x faster than expected"
    }
}
```

### Remove background

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_imagestudio___remove_bg`

Remove Background from Image Removes the background from any image using AI (REMBG), leaving only the foreground subject with transparency. Supported Input Formats: JPG, JPEG, PNG, WebP, GIF, BMP Parameters:
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| file | file | Yes | Image file to process |
| output_format | string | No | Output format: webp (default, best quality/size), png (lossless with transparency) |
| output | string | No | Response format: url (JSON with download URL, default), inline (raw image binary for direct embedding), base64 (JSON with base64 data URL) |
| priority | int | No | >=900 for synchronous processing (default for remove_bg) | Processing Time: ~5 seconds (always synchronous)

**Tool-ID:** `po_image_remove_background` • **Cost:** 10 credits • **MCP:** `po_image_remove_background` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file` | string | Yes | Image file JPG, JPEG, PNG, WebP, GIF, BMP |
| `output_format` | string | No | Output format: webp default or png (default: "webp") |
| `output` | string | No | Output mode: url default, inline raw binary, base64 (default: "url") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output_files": [],
        "output": {
            "width": 1,
            "height": 1,
            "seed": 1,
            "steps": 1,
            "guidance_scale": 1
        }
    }
}
```

---

## Media AI — Translation

### Get Supported Languages

`GET https://api.paperoffice.ai/latest/translate/languages`

Get Supported Translation Languages\n\nReturns a list of all supported languages for AI-powered translation. Includes language codes (ISO 639-1) and native names.\n\n--- When to Use\n- Before translating, to check available target languages\n- To build language selectors in your UI\n- To validate language codes before calling translate/single or translate/batch

**Tool-ID:** `po_translate_get_languages` • **Cost:** 1 credits • **MCP:** `po_translate_get_languages` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "job": {
        "api_job_name": "translate___languages",
        "app": "translate",
        "action": "languages",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "27.49ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Translate Batch

`POST https://api.paperoffice.ai/latest/translate/text`

Translate multiple texts in a single call. Alias for po_translate_text.

**Tool-ID:** `po_translate_batch` • **Cost:** Free • **MCP:** `po_translate_batch` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | array | Yes | Array of strings to translate in one call |
| `target_language` | string | Yes | Target language ISO-639-1 code (e.g. en, de, fr, es, ja, zh) |
| `source_language` | string | No | Source language ISO-639-1 code or auto (default: "auto") |
| `tier` | string | No | Quality tier: basic (fast), premium (balanced), ultra (best) (allowed: basic, premium, ultra) (default: "premium") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "data": {
        "input_type": "array",
        "source_language": "auto",
        "target_language": "de",
        "tier": "premium",
        "priority_requested": 900,
        "preserve_terms": [],
        "characters": 26,
        "async": false,
        "translations": [
            "Hallo",
            "Guten Morgen",
            "Danke"
        ],
        "items_count": 3,
        "job_id": "poai-job_900_1776509284.8425_c9e2a4584189b3804db23a008534d492",
        "priority_effective": 900,
        "processing_time": "508.41ms"
    },
    "processing_time": "519.78ms",
    "status": "success"
}
```

### Translate Single Text

`POST https://api.paperoffice.ai/latest/translate/text`

Translate a single text. Alias for po_translate_text.

**Tool-ID:** `po_translate_single` • **Cost:** Free • **MCP:** `po_translate_single` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | Yes | Text to translate |
| `target_language` | string | Yes | Target language ISO-639-1 code (e.g. en, de, fr, es, ja, zh) |
| `source_language` | string | No | Source language ISO-639-1 code or auto (default: "auto") |
| `tier` | string | No | Quality tier: basic (fast), premium (balanced), ultra (best) (allowed: basic, premium, ultra) (default: "premium") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "data": {
        "input_type": "string",
        "source_language": "auto",
        "target_language": "de",
        "tier": "premium",
        "priority_requested": 900,
        "preserve_terms": [],
        "characters": 11,
        "async": false,
        "translation": "Hallo Welt",
        "job_id": "poai-job_900_1776509284.2456_dac553df27a99839abc9c838cee71d21",
        "priority_effective": 900,
        "processing_time": "408.35ms"
    },
    "processing_time": "442.69ms",
    "status": "success"
}
```

### Translate Text

`POST https://api.paperoffice.ai/latest/translate/text`

Unified Translation: Translates text, arrays, or JSON objects via AI. Accepts string, string[], or object as input. Billing per 1K characters, 3 quality levels (basic/premium/ultra).

**Tool-ID:** `po_translate_text` • **Cost:** Free • **MCP:** `po_translate_text` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string|array|object | Yes | Text to translate. Can be a string, array of strings, or JSON object with string values. |
| `target_language` | string | Yes | Target language ISO-639-1 code (e.g. en, de, fr, es, ja, zh) |
| `source_language` | string | No | Source language ISO-639-1 code, or "auto" for auto detection (default: auto) (default: "auto") |
| `tier` | string | No | Translation quality tier: basic (fast, 4B model), premium (balanced, 9B model), ultra (best quality, cloud model) (allowed: basic, premium, ultra) (default: "premium") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |
| `preserve_terms` | array | No | Optional list of terms (brand names, product names, proper nouns) that MUST be preserved verbatim in the translation. Each term 1-100 chars, max 50 entries. The terms are injected into the LLM system prompt with explicit "do not translate or transliterate" instructions. Typical use: plan names ("Starter", "Ultra"), brand names ("DATEV", "SAP"), or any identifier that should never be localized. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "data": {
        "input_type": "string",
        "source_language": "auto",
        "target_language": "de",
        "tier": "premium",
        "priority_requested": 900,
        "preserve_terms": [],
        "characters": 58,
        "async": false,
        "translation": "PaperOffice hilft enterprises dabei, documents effizient zu verwalten.",
        "job_id": "poai-job_900_1776509283.6663_29cb44f710ed6e7f18dba273d85d91c8",
        "priority_effective": 900,
        "processing_time": "509.47ms"
    },
    "processing_time": "529.95ms",
    "status": "success"
}
```

---

## Media AI — Voice

### Transcribe audio

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_voice___stt`

Transcribe audio to text with 3 quality tiers. Basic (1ct/min): Full transcription, 50+ languages, auto detection, language confidence.
Premium (2ct/min): + Word-level timestamps with confidence, segment timestamps, SRT/VTT export, custom vocabulary (hotwords).
Ultra (3ct/min): + Multi-speaker diarization, speaker labels, overlap detection, speaker count, multilingual meetings, RTTM export. Supported Formats: MP3, WAV, OGG, FLAC, M4A, WEBM. Max Size: 25 MB.
Sync/Async: Use priority >= 900 for synchronous processing.

**Tool-ID:** `po_stt_transcribe_audio` • **Cost:** 10 credits • **MCP:** `po_stt_transcribe_audio` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | No | Audio file to transcribe (required). Supported: MP3, WAV, OGG, FLAC, M4A, WEBM. Max 25 MB. |
| `quality` | string | No | STT quality tier. basic: text only (1ct/min). premium: + word timestamps, SRT/VTT, hotwords (2ct/min). ultra: + speaker diarization, overlap detection, RTTM (3ct/min) (allowed: basic, premium, ultra) (default: "basic") |
| `output_format` | string | No | Response format. json: structured JSON (default). srt: SubRip subtitle format. vtt: WebVTT subtitle format. rttm: Rich Transcription Time Marked (ultra only). Only srt/vtt/rttm available with premium or ultra quality. (allowed: json, srt, vtt, rttm) (default: "json") |
| `hotwords` | string | No | Custom vocabulary hint. Comma-separated list of domain-specific words, names, or technical terms to improve recognition accuracy. Only available with premium or ultra quality. Example: PaproOffice,Datacore,Galera (default: "") |
| `priority` | integer | No | Processing priority: >=900 = sync (waits for result). Default: 999 (default: "999") |
| `locale` | string | No | Language hint (optional): de, en, es, fr, etc. Empty = auto detection (default: "") |
| `language` | string | No | Alternative to locale - same functionality. Language code: de, en, es, etc. (default: "") |
| `min_speakers` | integer | No | Minimum expected speakers (ultra only). Helps diarization accuracy when you know the approximate speaker count. |
| `max_speakers` | integer | No | Maximum expected speakers (ultra only). Helps diarization accuracy when you know the approximate speaker count. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "text": "example",
            "language": "en_US",
            "confidence": 1,
            "duration_seconds": 150,
            "segments": [
                {
                    "start": 1,
                    "end": 1,
                    "text": "example"
                }
            ]
        }
    }
}
```

### Clone voice (TTS)

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_voice___tts`

Clone ANY voice with just an audio sample! Requires Premium or Ultra tier. No voice parameter needed - upload voice_sample instead. Voice Sample Requirements: Duration: 5-15 seconds (optimal: ~10s). Quality: Clean audio, NO background noise. Formats: WAV, MP3, OGG, FLAC, M4A, WebM, AAC. Max size: 10 MB. Tip: Clearer samples produce better results.

**Tool-ID:** `po_tts_voice_cloning` • **Cost:** 100 credits • **MCP:** `po_tts_voice_cloning` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | Yes | Text to speak (max 50.000 characters) (default: "Hello, this is a test with my cloned voice.") |
| `voice_sample` | string | Yes | Audio file of the voice to clone (required for cloning). 5-15 seconds, clean audio, max 10 MB. Formats: WAV, MP3, OGG, FLAC, M4A, WebM, AAC. |
| `quality` | string | No | Quality tier: premium (balanced) or ultra (best quality). Basic is NOT supported for voice cloning. Default: premium (allowed: premium, ultra) (default: "premium") |
| `output_format` | string | No | Audio format: mp3 (compressed), wav (lossless), ogg (open source). Default: mp3 (allowed: mp3, wav, ogg) (default: "mp3") |
| `output` | string | No | Response format: url (download URL), base64, inline. Default: url (allowed: url, base64, inline) (default: "url") |
| `priority` | integer | No | Processing priority: >= 900 = sync. Default: 999 (default: "999") |
| `language` | string | No | Language code (optional, auto-detected from sample if empty): de, en, es, fr, it, ja, pt, etc. (default: "") |
| `speed` | string | No | Speech speed: 0.9 to 1.1. Default: 1.0 (default: "1.0") |
| `temproature` | string | No | Sampling temproature: 0.1 to 1.0. Default: 0.9 (default: "0.9") |
| `top_p` | string | No | Top-P: 0.1 to 1.0. Default: 0.7 (default: "0.7") |
| `repetition_penalty` | string | No | Repetition penalty: 0.9 to 1.99. Default: 1.1 (default: "1.1") |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output_files": []
    }
}
```

### Generate multi-speaker TTS (inline tags)

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_voice___tts`

Generate audio with unlimited speakers using inline tags! Two day formats supported: **Shorthand:** [de|Anneliese] Text [de|Florian] Text
**Key-Value:** [voice:Anneliese lang:de] Text [voice:Florian lang:de speed:0.95] Text Supported day attributes: voice, lang, speed, temp, quality.
Speaker names must match voices from /voices_info endpoint. Languages: ar, bg, cs, da, de, el, en, es-ES, es-MX, et, fi, fr, he, hi, hr, hu, id, it, ja, ko, lt, lv, ms, nl, no, pl, pt-BR, pt-PT, ro, ru, sk, sl, sr, sv, th, tr, uk, vi, zh-cn. Output: MP3, WAV, OGG. Speed: 0.9-1.1. Quality: basic, premium (default), ultra.

**Tool-ID:** `po_tts_multivoice_4_speakers` • **Cost:** 50 credits • **MCP:** `po_tts_multivoice_4_speakers` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | Yes | Text with inline voice tags. Shorthand: [de / Anneliese] Text. Key-Value: [voice:Anneliese lang:de] Text. Emotion markers inline: (excited) (whisproing) etc. |
| `language` | string | Yes | fallback language if not specified in tags. One of: ar,bg,cs,da,de,el,en,es-ES,es-MX,et,fi,fr,he,hi,hr,hu,id,it,ja,ko,lt,lv,ms,nl,no,pl,pt-BR,pt-PT,ro,ru,sk,sl,sr,sv,th,tr,uk,vi,zh-cn |
| `quality` | string | No | Global quality tier (default: premium). Can be overridden per-day with quality:ultra. (allowed: basic, premium, ultra) |
| `output_format` | string | No | Audio output format (default: mp3). Basic tier: mp3 only. (allowed: mp3, wav, ogg) |
| `speed` | number | No | Global speech speed 0.9-1.1 (default: 1.0). Can be overridden per-day with speed:0.95. |
| `temproature` | number | No | Expressiveness 0.1-1.0 (default: 0.9) |
| `top_p` | number | No | Diversity 0.1-1.0 (default: 0.7) |
| `repetition_penalty` | number | No | Repetition penalty 0.9-1.99 (default: 1.1) |
| `priority` | integer | No | Job priority. 100=async (recommended), 900=sync. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output_files": []
    }
}
```

### Generate speech

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_voice___tts`

Convert text to speech using neural voices. Output Formats: MP3, WAV, OGG. 39 Languages: DE, EN, ES, ES-MX, FR, IT, JA, PT, PT-PT, PT-BR, PL, TR, RU, NL, CS, AR, ZH, HU, KO, HI, BG, DA, EL, ET, FI, HE, HR, ID, LT, LV, MS, NO, RO, SK, SL, SR, SV, TH, UK, VI. Quality Tiers: basic (fast, 1:7), premium (balanced, 1:4), ultra (best quality, 1:1). Sync/Async: Use priority >= 900 for synchronous processing. Voice Cloning: Use voice_sample parameter (Premium/Ultra only).

**Tool-ID:** `po_tts_generate_speech` • **Cost:** 50 credits • **MCP:** `po_tts_generate_speech` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | Yes | Text to convert to speech (max 50.000 characters) (default: "Hello, this is a test.") |
| `voice` | string | Yes | Voice name from /voices_info endpoint (required) (default: "Anneliese") |
| `language` | string | Yes | Language code (required): de, en, es, es-MX, fr, it, ja, pt, pt-PT, pt-BR, pl, tr, ru, nl, cs, ar, zh-cn, hu, ko, hi, bg, da, el, et, fi, he, hr, id, lt, lv, ms, no, ro, sk, sl, sr, sv, th, uk, vi (default: "de") |
| `quality` | string | No | Quality tier: basic (fast), premium (balanced), ultra (best quality). Default: premium (allowed: basic, premium, ultra) (default: "premium") |
| `output_format` | string | No | Audio format: mp3 (compressed), wav (lossless), ogg (open source). Default: mp3. WAV/OGG require Premium or Ultra. (allowed: mp3, wav, ogg) (default: "mp3") |
| `output` | string | No | Response format: url (download URL), base64 (audio as Base64 string), inline (direct audio stream). Default: url (allowed: url, base64, inline) (default: "url") |
| `priority` | integer | No | Processing priority: >= 900 = synchronous (waits for result). Default: 999 (default: "999") |
| `speed` | string | No | Speech speed: 0.9 (slower) to 1.1 (faster). Default: 1.0 (default: "1.0") |
| `temproature` | string | No | Sampling temproature: 0.1 (deterministic) to 1.0 (creative). Default: 0.9 (default: "0.9") |
| `top_p` | string | No | Top-P nucleus sampling: 0.1 to 1.0. Default: 0.7 (default: "0.7") |
| `repetition_penalty` | string | No | Repetition penalty: 0.9 to 1.99. Higher = less repetition. Default: 1.1 (default: "1.1") |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output_files": [],
        "output": {
            "audio_duration_seconds": 150,
            "mime_type": "application/pdf",
            "language": "en_US",
            "voice": "example",
            "text_length": 1
        }
    }
}
```

### List available TTS voices

`POST https://api.paperoffice.ai/latest/voice/voices`

Returns all available TTS voices grouped by language. Each voice includes: name (use as voice parameter), gender, tier (basic/all), and sample URL for preview. 848 voices across 39 languages. Use the name field from the response as the voice parameter in TTS requests.

**Tool-ID:** `po_tts_get_available_voices` • **Cost:** 1 credits • **MCP:** `po_tts_get_available_voices` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9439
    },
    "job": {
        "api_job_name": "voice___voices",
        "app": "voice",
        "action": "voices",
        "default_credits": 1,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "7.71ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

---

## Security AI — Fake Email

### Add domain

`POST https://api.paperoffice.ai/latest/fakeemail/stats`

Add Custom domain Add a domain to the disposable or whitelist database. --- When to Use - Report new disposable domains - Whitelist trusted domains - Customize detection for your use case --- Parameters JSON Body | Parameter | Type | Required | Description | |-----------|------|----------|-------.

**Tool-ID:** `po_email_detector_add_domain` • **Cost:** 10 credits • **MCP:** `po_email_detector_add_domain` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `domain` | string | Yes | domain-Name (e.g. spam-provider.com) |
| `type` | string | No | listntyp (allowed: disposable, whitelist) (default: "disposable") |

**Example Response:**

```json
{
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    },
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9539
    },
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "job": {
        "api_job_name": "fakeemail___stats",
        "app": "fakeemail",
        "action": "stats",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "rate_limited": true,
        "credits_billed": 0
    }
}
```

### Check email

`POST https://api.paperoffice.ai/latest/fakeemail/check`

Check Single Email Check if a single email address is fake, disposable, or temporary. --- When to Use - User registration validation - Lead verification - Single email verification --- Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | email |.

**Tool-ID:** `po_email_detector_check_email` • **Cost:** 10 credits • **MCP:** `po_email_detector_check_email` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | No | Email address to check |

**Example Response:**

```json
{
    "status": {
        "code": 400,
        "message": "Parameter \"email\" required",
        "success": false
    },
    "processing_time": "12.91ms"
}
```

### Check emails

`POST https://api.paperoffice.ai/latest/fakeemail/check_bulk`

Bulk Check Multiple Emails Check up to 100 email addresses in a single request. --- When to Use - Clean email lists - Validate imported contacts - Bulk lead verification --- Parameters JSON Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | emails |.

**Tool-ID:** `po_email_detector_bulk_check_emails` • **Cost:** 10 credits • **MCP:** `po_email_detector_bulk_check_emails` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `emails` | array | Yes | List of email addresses for verification (max. 100) |

**Example Response:**

```json
{
    "status": {
        "code": 400,
        "message": "Parameter \"emails\" (array) required in JSON body",
        "success": false
    },
    "processing_time": "80.77ms"
}
```

### Get statistics

`POST https://api.paperoffice.ai/latest/fakeemail/stats`

Get Detection Statistics Retrieve statistics about your fake email detection usage. --- When to Use - Monitor detection rates - Track usage patterns - Generate reports --- Parameters No parameters required. --- Response json { "stats": { "total_checks": 15420, "fake_detected": 2341, "legitimate":.

**Tool-ID:** `po_email_detector_get_statistics` • **Cost:** 10 credits • **MCP:** `po_email_detector_get_statistics` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    },
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9539
    },
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "job": {
        "api_job_name": "fakeemail___stats",
        "app": "fakeemail",
        "action": "stats",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "rate_limited": true,
        "credits_billed": 0
    }
}
```

---

## Security AI — Fingerprint

### Detect IP VPN usage

`POST https://api.paperoffice.ai/latest/ip2location/vpn`

Detect VPN, proxy, and anonymization services. Returns: - is_vpn - VPN detected - is_proxy - Proxy server detected - is_tor - TOR exit node - is_datacenter - Datacenter IP cloud hosting - is_relay - Apple Private Relay - score - Risk percentage 0-100% - last_crawl - Last database update Use for: .

**Tool-ID:** `po_ip_geolocation_vpn_detection` • **Cost:** 10 credits • **MCP:** `po_ip_geolocation_vpn_detection` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | No | Query parameter: ip |

**Example Response:**

```json
{
    "ip": {
        "ip": "203.0.113.42",
        "location": {
            "timezone": {
                "name": "Europe/Madrid",
                "offsethours": 1
            },
            "geo_lat": 40.4167,
            "geo_lon": -3.70329,
            "city": {
                "name": "Madrid",
                "zip": "28070",
                "district": ""
            },
            "region": {
                "code": "MD",
                "name": "Madrid"
            },
            "continent": {
                "name": "Europe",
                "code": "EU"
            },
            "country": {
                "name": "Spain",
                "code": "ES",
                "currency": "EUR",
                "primary_language": "es",
                "spoken_languages": [
                    "es",
                    "eu",
                    "ca",
                    "gl"
                ],
                "capital": "Madrid",
                "callingcode": "+34",
                "vat": {
                    "standard_rate": 21,
                    "reduced_rates": [
                        10,
                        4
                    ],
                    "prefix": "ES",
                    "regex": "^ES[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                    "digital_services_rate": 21,
                    "b2b_reverse_charge": true,
                    "tax_free_threshold": 0
                },
                "economy": {
                    "currency_details": {
                        "code": "EUR",
                        "symbol": "€",
                        "position": "after",
                        "decimal": ",",
                        "thousand": ".",
                        "decimals": 2
                    },
                    "economic_zones": [
                        "EU",
                        "EEA",
                        "SEPA",
                        "Schengen"
                    ],
                    "risk_rating": "A",
                    "gdp_per_capita": 28905.45
                },
                "legal": {
                    "legal_system": "Civil Law",
                    "data_protection": "GDPR",
                    "business_registration_required": true,
                    "electronic_signature": "eIDAS",
                    "age_of_majority": 18,
                    "vat_registration_required": true
                },
                "address": {
                    "postal_code_regex": "^[0-9]{5}$",
                    "format": "{{recipient}}\n{{street}} {{house}}\n{{postal}} {{city}}",
                    "required_fields": [
                        "street",
                        "postal",
                        "city"
                    ],
                    "state_required": true,
                    "phone": {
                        "mobile_prefix": [
                            "6",
                            "7"
                        ],
                        "area_code_required": true,
                        "example": "+34 600 123 456",
                        "regex": "^\\+34[6-7][0-9]{8}$"
                    }
                },
                "business": {
                    "working_days": [
                        "mon",
                        "tue",
                        "wed",
                        "thu",
                        "fri"
                    ],
                    "usual_hours": "09:00-18:00",
                    "bank_details": {
                        "iban_prefix": "ES",
                        "iban_length": 24,
                        "swift_format": "^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}[A-Z0-9]{11}$",
                        "local_format": "BBBBBBBBCCCCCCCCCCCC"
                    },
                    "payment_methods": {
                        "popular": [
                            "sepa",
                            "bizum",
                            "cards",
                            "paypal"
                        ],
                        "local": [
                            "bizum"
                        ]
                    }
                },
                "demographics": {
                    "population": 47351567,
                    "capital_population": 3233527,
                    "urbanization": 80.3,
                    "median_age": 45.3,
                    "languages": {
                        "official": [
                            "es"
                        ],
                        "business": [
                            "es",
                            "en"
                        ]
                    }
                },
                "geography": {
                    "neighbors": [
                        "PT",
                        "FR",
                        "AD",
                        "GI"
                    ],
                    "has_coast": true,
                    "climate_zone": "Mediterranean",
                    "timezone": {
                        "winter": "UTC+1",
                        "summer": "UTC+2",
                        "dst_start": "last Sunday March",
                        "dst_end": "last Sunday October"
                    },
                    "coordinates": {
                        "latitude": 40.4168,
                        "longitude": -3.7038
                    }
                },
                "holidays": {
                    "national_fixed": [
                        {
                            "date": "01-01",
                            "name": "Año Nuevo"
                        },
                        {
                            "date": "05-01",
                            "name": "Día del Trabajo"
                        },
                        {
                            "date": "10-12",
                            "name": "Día de la Hispanidad"
                        },
                        {
                            "date": "12-25",
                            "name": "Navidad"
                        }
                    ],
                    "national_floating": [
                        {
                            "name": "Viernes Santo",
                            "calc": "easter-2"
                        },
                        {
                            "name": "Lunes de Pascua",
                            "calc": "easter+1"
                        }
                    ],
                    "regional_specific": {
                        "AN": [
                            {
                                "date": "02-28",
                                "name": "Día de Andalucía"
                            }
                        ],
                        "CT": [
                            {
                                "date": "09-11",
                                "name": "Día de Cataluña"
                            }
                        ],
                        "MD": [
                            {
                                "date": "05-02",
                                "name": "Día de la Comunidad de Madrid"
                            }
                        ]
                    }
                },
                "document_validation": {
                    "tax_number": {
                        "format": "^[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                        "example": "A1234567B"
                    },
                    "vat_id": {
                        "format": "^ES[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                        "example": "ESA1234567B"
                    },
                    "id_card": {
                        "format": "^[0-9]{8}[A-Z]$",
                        "example": "12345678Z",
                        "valid_years": 10
                    },
                    "passport": {
                        "format": "^[A-Z0-9]{9}$",
                        "example": "X12345678",
                        "valid_years": 10
                    }
                },
                "ecommerce": {
                    "returns_period": 14,
                    "cancellation_period": 14,
                    "required_legal_texts": [
                        "imprint",
                        "privacy_policy",
                        "terms_conditions",
                        "cancellation_policy",
                        "shipping_info"
                    ],
                    "price_display": {
                        "must_include_vat": true,
                        "shipping_info_required": true,
                        "basic_price_required": true
                    },
                    "payment_deadline": {
                        "b2c": 14,
                        "b2b": 30
                    }
                },
                "important_contacts": {
                    "emergency": {
                        "general_emergency": "112",
                        "police": "091",
                        "fire_brigade": "080",
                        "ambulance": "061",
                        "poison_control": "+34 915 620 420",
                        "maritime_emergency": "+34 900 202 202",
                        "mountain_rescue": "112",
                        "gas_emergency": "+34 900 924 622",
                        "power_outage": "+34 900 500 049"
                    },
                    "health": {
                        "medical_on_call": "061",
                        "pharmacy_emergency": "N/A",
                        "mental_health_crisis": "+34 917 007 079",
                        "drug_addiction": "+34 900 161 515",
                        "aids_counseling": "+34 915 912 445",
                        "cancer_information": "+34 800 003 003"
                    },
                    "government": {
                        "tax_office_general": "+34 915 548 700",
                        "customs_info": "+34 915 506 400",
                        "federal_police": "+34 900 202 202",
                        "pension_service": "+34 901 166 565",
                        "employment_agency": "+34 900 801 137",
                        "social_security": "+34 901 502 050",
                        "immigration_office": "+34 902 008 210"
                    },
                    "consumer": {
                        "consumer_protection": "+34 915 326 320",
                        "data_protection": "dpd@agpd.es",
                        "banking_supervision": "+34 913 388 830",
                        "energy_advice": "+34 900 648 804",
                        "travel_security": "+34 915 205 948",
                        "food_safety": "+34 913 224 000"
                    },
                    "assistance": {
                        "roadside_assistance": {
                            "mapfre": "+34 918 366 160",
                            "axa": "+34 902 404 084"
                        },
                        "missing_persons": {
                            "hotline": "+34 116 000",
                            "children_emergency": "+34 116 111"
                        },
                        "violence": {
                            "domestic_violence": "+34 016",
                            "child_protection": "+34 116 111"
                        }
                    },
                    "fraud_prevention": {
                        "anti_fraud": "+34 902 007 290",
                        "credit_card_blocking": "+34 900 111 000",
                        "cyber_crime": "+34 915 822 640",
                        "identity_theft": "+34 900 202 202"
                    },
                    "transportation": {
                        "renfe": "+34 912 320 320",
                        "iberia": "+34 901 111 500",
                        "airport_barcelona": "+34 913 211 000",
                        "airport_madrid": "+34 913 936 000",
                        "public_transport_madrid": "+34 915 214 260"
                    },
                    "utilities": {
                        "telefonica_support": "+34 900 104 709",
                        "vodafone_support": "+34 123",
                        "orange_support": "+34 1470"
                    }
                },
                "iseumember": true
            }
        },
        "provider": {
            "as": "AS8708 RCS & RDS",
            "asname": "RCS-RDS",
            "isp": "RCS & RDS",
            "org": "RCS & RDS Residential"
        },
        "status": "success",
        "language": {
            "by_browser": false,
            "by_country": "es"
        },
        "locale": {
            "by_browser": false
        },
        "country_details": {
            "additional_data": "Extended country details loaded successfully"
        }
    },
    "processing_time": "42.44ms",
    "vpn": {
        "is_vpn": false,
        "is_proxy": false,
        "is_relay": false,
        "is_datacenter": false,
        "is_tor": false,
        "score": "3.72%",
        "ip": "203.0.113.42",
        "last_paperofficeai_overseer_crawl": "2026-04-08 02:02:42"
    }
}
```

### Find Similar Devices

`POST https://api.paperoffice.ai/latest/fingerprint/similar`

Find Similar Devices V2! Uses vector embeddings to find devices with similar fingerprint components. Use Cases: - Cross-browser detection same user, different browser - Device clustering - Fraud detection Response: json { "status": "success", "visitor_id": "abc123.", "similar_devices": { "visit.

**Tool-ID:** `po_fingerprint_find_similar_devices_v2` • **Cost:** 10 credits • **MCP:** `po_fingerprint_find_similar_devices_v2` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | Visitor-Reference device ID (32-character SHA-256 hash) |
| `threshold` | number | No | {"threshold_similarity":"Threshold for similarity (0.0-1.0)","note":""} (default: 0.7) |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "devices": [
                []
            ],
            "total": 1
        }
    }
}
```

### Get fingerprint API stats

`GET https://api.paperoffice.ai/latest/fingerprint/stats`

Get API Statistics V2 Enhanced! Check available features, storage info, and detailed metrics. Response: json { "status": "success", "version": "2.0.0", "stats": { "totalFingerprints": 12345, "todayNew": 150, "todayActive": 890, "vpnDetected": 23, "botsDetected": 5, "avgConfidence": 87.5 }, "featu.

**Tool-ID:** `po_fingerprint_api_stats` • **Cost:** Free • **MCP:** `po_fingerprint_api_stats` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "features": {
        "canvas": true,
        "webgl": true,
        "audio": true,
        "fonts": true,
        "behavioral": true,
        "botDetection": true,
        "ja4": true,
        "http2": true,
        "ip2location": true,
        "vpnDetection": true,
        "vectorEmbeddings": true,
        "similaritySearch": true,
        "ipClustering": true,
        "velocityChecks": true,
        "deviceGraph": true,
        "fraudDetection": true
    },
    "processing_time": "28.06ms",
    "retention": "180_days",
    "stats": {
        "totalFingerprints": 868,
        "todayNew": 2,
        "todayActive": 61,
        "vpnDetected": 37,
        "botsDetected": 66,
        "avgConfidence": 27.5,
        "avgVisits": 1103.6
    },
    "status": "success",
    "storage": "mariadb_11.8_vector",
    "version": "2.0.0"
}
```

### Get fingerprint device details

`POST https://api.paperoffice.ai/latest/fingerprint/device`

Get Device Details Retrieve details about a known device. Response: json { "status": "success", "device": { "visitorId": "abc123.", "firstSeen": "2025-12-19T10:00:00Z", "lastSeen": "2025-12-19T18:30:00Z", "visits": 42, "browser": "Chrome", "platform": "Windows", "country": "DE" } }

**Tool-ID:** `po_fingerprint_get_device_details` • **Cost:** 10 credits • **MCP:** `po_fingerprint_get_device_details` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | Visitor-Device ID (32 characters) |

### Get Linked Devices

`POST https://api.paperoffice.ai/latest/fingerprint/linked`

Get Linked Devices via IP Clustering V2! Finds all devices that have been seen on the same IP address same network/household. Use Cases: - Household detection - account sharing detection - Family plan verification Response: json { "status": "success", "visitor_id": "abc123.", "same_network": "d.

**Tool-ID:** `po_fingerprint_get_linked_devices_v2` • **Cost:** 10 credits • **MCP:** `po_fingerprint_get_linked_devices_v2` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | Visitor-ID for network connection lookup (32 characters) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "fingerprint___linked",
        "app": "fingerprint",
        "action": "linked",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.49ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Identify device (fingerprint v2)

`POST https://api.paperoffice.ai/latest/fingerprint/identify`

Identify a Device V2! Main endpoint for device identification. Uses vector embeddings, IP clustering, and velocity checks. V2 Features: - Vector embeddings for accurate device matching - Automatic IP clustering for household detection - Velocity tracking for fraud detection - Device linking and s.

**Tool-ID:** `po_fingerprint_identify_device_v2` • **Cost:** 10 credits • **MCP:** `po_fingerprint_identify_device_v2` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `components` | object | No | Client-side fingerprint components from the JavaScript SDK (Canvas, WebGL, Audio, Fonts, Behavioral) |
| `include` | string | No | Comma-separated Enrichment Modules (e.g., anonywithy, currency) or core for minimal Response |
| `language` | string | No | Language code for enriched data (ISO 639-1) (default: "en") |
| `visitorId` | string | No | Visitor-ID pre-calculated by the client |
| `confidence` | number | No | Client-seitig berechneter confidence-Score (0-100) (default: 0) |
| `botDetection` | object | No | Client-seitige Bot-detectionsdaten with signals-Array |

**Example Response:**

```json
{
    "anonymity": {
        "is_vpn": false,
        "is_proxy": false,
        "is_tor": false,
        "is_relay": false,
        "is_datacenter": false,
        "score": "8.13%",
        "type": null,
        "details": null
    },
    "bot": {
        "is_bot": false,
        "score": 30,
        "signals": [
            "suspicious_ua"
        ],
        "threshold": 70,
        "server_evaluated": true
    },
    "confidence": {
        "score": 0.3,
        "level": "low"
    },
    "country": {
        "code": "ES",
        "name": "Spain",
        "vat": {
            "standard_rate": 21,
            "reduced_rates": [
                10,
                4
            ],
            "prefix": "ES",
            "regex": "^ES[A-Z0-9]{1}[0-9]{7}[A-Z]$",
            "digital_services_rate": 21,
            "b2b_reverse_charge": true,
            "tax_free_threshold": 0
        },
        "economy": {
            "currency_details": {
                "code": "EUR",
                "symbol": "€",
                "position": "after",
                "decimal": ",",
                "thousand": ".",
                "decimals": 2
            },
            "economic_zones": [
                "EU",
                "EEA",
                "SEPA",
                "Schengen"
            ],
            "risk_rating": "A",
            "gdp_per_capita": 28905.45
        },
        "legal": {
            "legal_system": "Civil Law",
            "data_protection": "GDPR",
            "business_registration_required": true,
            "electronic_signature": "eIDAS",
            "age_of_majority": 18,
            "vat_registration_required": true
        },
        "address": {
            "postal_code_regex": "^[0-9]{5}$",
            "format": "{{recipient}}\n{{street}} {{house}}\n{{postal}} {{city}}",
            "required_fields": [
                "street",
                "postal",
                "city"
            ],
            "state_required": true,
            "phone": {
                "mobile_prefix": [
                    "6",
                    "7"
                ],
                "area_code_required": true,
                "example": "+34 600 123 456",
                "regex": "^\\+34[6-7][0-9]{8}$"
            }
        },
        "business": {
            "working_days": [
                "mon",
                "tue",
                "wed",
                "thu",
                "fri"
            ],
            "usual_hours": "09:00-18:00",
            "bank_details": {
                "iban_prefix": "ES",
                "iban_length": 24,
                "swift_format": "^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}[A-Z0-9]{11}$",
                "local_format": "BBBBBBBBCCCCCCCCCCCC"
            },
            "payment_methods": {
                "popular": [
                    "sepa",
                    "bizum",
                    "cards",
                    "paypal"
                ],
                "local": [
                    "bizum"
                ]
            }
        },
        "demographics": {
            "population": 47351567,
            "capital_population": 3233527,
            "urbanization": 80.3,
            "median_age": 45.3,
            "languages": {
                "official": [
                    "es"
                ],
                "business": [
                    "es",
                    "en"
                ]
            }
        },
        "geography": {
            "neighbors": [
                "PT",
                "FR",
                "AD",
                "GI"
            ],
            "has_coast": true,
            "climate_zone": "Mediterranean",
            "timezone": {
                "winter": "UTC+1",
                "summer": "UTC+2",
                "dst_start": "last Sunday March",
                "dst_end": "last Sunday October"
            },
            "coordinates": {
                "latitude": 40.4168,
                "longitude": -3.7038
            }
        },
        "holidays": {
            "national_fixed": [
                {
                    "date": "01-01",
                    "name": "Año Nuevo"
                },
                {
                    "date": "05-01",
                    "name": "Día del Trabajo"
                },
                {
                    "date": "10-12",
                    "name": "Día de la Hispanidad"
                },
                {
                    "date": "12-25",
                    "name": "Navidad"
                }
            ],
            "national_floating": [
                {
                    "name": "Viernes Santo",
                    "calc": "easter-2"
                },
                {
                    "name": "Lunes de Pascua",
                    "calc": "easter+1"
                }
            ],
            "regional_specific": {
                "AN": [
                    {
                        "date": "02-28",
                        "name": "Día de Andalucía"
                    }
                ],
                "CT": [
                    {
                        "date": "09-11",
                        "name": "Día de Cataluña"
                    }
                ],
                "MD": [
                    {
                        "date": "05-02",
                        "name": "Día de la Comunidad de Madrid"
                    }
                ]
            }
        },
        "document_validation": {
            "tax_number": {
                "format": "^[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                "example": "A1234567B"
            },
            "vat_id": {
                "format": "^ES[A-Z0-9]{1}[0-9]{7}[A-Z]$",
                "example": "ESA1234567B"
            },
            "id_card": {
                "format": "^[0-9]{8}[A-Z]$",
                "example": "12345678Z",
                "valid_years": 10
            },
            "passport": {
                "format": "^[A-Z0-9]{9}$",
                "example": "X12345678",
                "valid_years": 10
            }
        },
        "ecommerce": {
            "returns_period": 14,
            "cancellation_period": 14,
            "required_legal_texts": [
                "imprint",
                "privacy_policy",
                "terms_conditions",
                "cancellation_policy",
                "shipping_info"
            ],
            "price_display": {
                "must_include_vat": true,
                "shipping_info_required": true,
                "basic_price_required": true
            },
            "payment_deadline": {
                "b2c": 14,
                "b2b": 30
            }
        },
        "important_contacts": {
            "emergency": {
                "general_emergency": "112",
                "police": "091",
                "fire_brigade": "080",
                "ambulance": "061",
                "poison_control": "+34 915 620 420",
                "maritime_emergency": "+34 900 202 202",
                "mountain_rescue": "112",
                "gas_emergency": "+34 900 924 622",
                "power_outage": "+34 900 500 049"
            },
            "health": {
                "medical_on_call": "061",
                "pharmacy_emergency": "N/A",
                "mental_health_crisis": "+34 917 007 079",
                "drug_addiction": "+34 900 161 515",
                "aids_counseling": "+34 915 912 445",
                "cancer_information": "+34 800 003 003"
            },
            "government": {
                "tax_office_general": "+34 915 548 700",
                "customs_info": "+34 915 506 400",
                "federal_police": "+34 900 202 202",
                "pension_service": "+34 901 166 565",
                "employment_agency": "+34 900 801 137",
                "social_security": "+34 901 502 050",
                "immigration_office": "+34 902 008 210"
            },
            "consumer": {
                "consumer_protection": "+34 915 326 320",
                "data_protection": "dpd@agpd.es",
                "banking_supervision": "+34 913 388 830",
                "energy_advice": "+34 900 648 804",
                "travel_security": "+34 915 205 948",
                "food_safety": "+34 913 224 000"
            },
            "assistance": {
                "roadside_assistance": {
                    "mapfre": "+34 918 366 160",
                    "axa": "+34 902 404 084"
                },
                "missing_persons": {
                    "hotline": "+34 116 000",
                    "children_emergency": "+34 116 111"
                },
                "violence": {
                    "domestic_violence": "+34 016",
                    "child_protection": "+34 116 111"
                }
            },
            "fraud_prevention": {
                "anti_fraud": "+34 902 007 290",
                "credit_card_blocking": "+34 900 111 000",
                "cyber_crime": "+34 915 822 640",
                "identity_theft": "+34 900 202 202"
            },
            "transportation": {
                "renfe": "+34 912 320 320",
                "iberia": "+34 901 111 500",
                "airport_barcelona": "+34 913 211 000",
                "airport_madrid": "+34 913 936 000",
                "public_transport_madrid": "+34 915 214 260"
            },
            "utilities": {
                "telefonica_support": "+34 900 104 709",
                "vodafone_support": "+34 123",
                "orange_support": "+34 1470"
            }
        }
    },
    "currency": {
        "local": "EUR",
        "base": "EUR",
        "rates": {
            "EUR": 1,
            "USD": 1.157377,
            "GBP": 0.873024,
            "CHF": 0.922364,
            "JPY": 183.799212,
            "CNY": 7.970332,
            "INR": 108.483763,
            "BRL": 6.011696,
            "CAD": 1.608943,
            "AUD": 1.67364
        },
        "all_rates_count": 172,
        "timestamp": 1775654344
    },
    "device": {
        "browser": "Unknown browser",
        "browser_version": null,
        "platform": "Unknown system",
        "type": "desktop"
    },
    "first_seen": "2026-01-31 16:34:14",
    "ip": {
        "address": "203.0.113.42",
        "country": "ES",
        "city": "Madrid",
        "region": "MD",
        "isp": "RCS & RDS",
        "lat": 40.4167,
        "lon": -3.70329,
        "vpn": false,
        "proxy": false,
        "datacenter": false,
        "tor": false,
        "relay": false
    },
    "is_new": false,
    "last_seen": "2026-04-08T15:19:04+02:00",
    "linked_devices": [],
    "processing_time": "5.8ms",
    "risk": {
        "score": 0,
        "level": "low",
        "factors": []
    },
    "similar_devices": [],
    "status": "success",
    "ultimate_id": null,
    "velocity": {
        "suspicious": false,
        "reason": null,
        "travel_speed": 0
    },
    "visitor_id": "44256a8eadf880a0660a905910f03b4d",
    "visits": 655072,
    "weather": {
        "location": "Madrid",
        "region": "Madrid",
        "timezone": "Europe/Madrid",
        "localtime": "2026-04-07 23:59",
        "temp_c": 14.4,
        "temp_f": 57.9,
        "condition": "Partly cloudy",
        "humidity": 82,
        "wind_kph": 22,
        "wind_dir": "W",
        "feelslike_c": 12.8,
        "feelslike_f": 55,
        "uv": 0,
        "cloud": 50,
        "is_day": null,
        "air_quality": {
            "us_epa_index": 1,
            "gb_defra_index": 2,
            "pm2_5": 15.35,
            "pm10": 34.65
        }
    }
}
```

### Verify fingerprint

`POST https://api.paperoffice.ai/latest/fingerprint/verify`

Verify Fingerprint Check if current visitor matches a known fingerprint. Response: json { "status": "success", "verified": true, "matchScore": 85, "confidence": "high", "visitorId": "abc123.", "lastSeen": "2025-12-19T18:30:00Z", "visits": 42 }

**Tool-ID:** `po_fingerprint_verify_fingerprint` • **Cost:** 10 credits • **MCP:** `po_fingerprint_verify_fingerprint` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `visitorId` | string | No | Expected visitor ID to verify against (default: "abc123def456...") |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "verified": true,
            "confidence": 1
        }
    }
}
```

---

## Workflow AI — HITL

### Create HITL Config

`POST https://api.paperoffice.ai/latest/hitl_config/create`

Create HITL review configuration with trigger rules, review fields, SLA and assignment settings.

**Tool-ID:** `po_hitl_config_create` • **Cost:** Free • **MCP:** `po_hitl_config_create` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Name (Required) |
| `document_type` | string | No |  |
| `workspace_id` | string | No |  |
| `trigger_rules` | array | Yes | Trigger Rules (Mandatory, min. 1). Each rule needs: id, action (hitl / escalate / reject_auto). For field_level/document_level: field, oproator, value. |
| `review_fields` | array | No |  |
| `binary_checks` | array | No |  |
| `reject_reasons` | array | No |  |
| `sla_config` | object | Yes | SLA (max_review_time_minutes Required) |
| `assignment_config` | object | Yes | mode Required |
| `result_config` | object | No |  |
| `instruction_text` | string | No |  |
| `credits_pro_review` | integer | No |  |
| `match_mode` | string | No | (allowed: any, all) |

**Example Response:**

```json
{
    "status": "success",
    "config": []
}
```

### Delete HITL Config

`POST https://api.paperoffice.ai/latest/hitl_config/delete`

Soft-delete HITL configuration (sets is_active=0).

**Tool-ID:** `po_hitl_config_delete` • **Cost:** Free • **MCP:** `po_hitl_config_delete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `uuid` | string | Yes | Config-UUID (Required) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Get Document Field Keys

`GET https://api.paperoffice.ai/latest/hitl_config/field_keys`

Get available document meta field keys for review field config.

**Tool-ID:** `po_hitl_config_field_keys` • **Cost:** Free • **MCP:** `po_hitl_config_field_keys` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9680
    },
    "job": {
        "api_job_name": "hitl_config___field_keys",
        "app": "hitl_config",
        "action": "field_keys",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.21ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get HITL Config

`GET https://api.paperoffice.ai/latest/hitl_config/get`

Get single HITL configuration by UUID or ID.

**Tool-ID:** `po_hitl_config_get` • **Cost:** Free • **MCP:** `po_hitl_config_get` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `uuid` | string | No |  |
| `config_id` | integer | No |  |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9680
    },
    "job": {
        "api_job_name": "hitl_config___get",
        "app": "hitl_config",
        "action": "get",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "7.94ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get HITL config analytics

`POST https://api.paperoffice.ai/latest/hitl_config/analytics`

Detailed analytics for a HITL config.

**Tool-ID:** `po_hitl_config_analytics` • **Cost:** Free • **MCP:** `po_hitl_config_analytics` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `config_uuid` | string | Yes | Config-UUID (Required) |
| `date_from` | string | No |  |
| `date_to` | string | No |  |

**Example Response:**

```json
{
    "daily": [],
    "data": {
        "total_reviews": 0,
        "approved": 0,
        "rejected": 0,
        "escalated": 0,
        "approve_rate": null,
        "reject_rate": null,
        "escalate_rate": null,
        "avg_duration_seconds": 0,
        "median_duration_seconds": null,
        "p95_duration_seconds": null,
        "sla_compliance_rate": null,
        "sla_met": 0,
        "sla_breached": 0,
        "gold_accuracy": null,
        "gold_total": 0,
        "gold_correct": 0,
        "total_credits": 0,
        "avg_credits": 0,
        "total_postpones": 0
    },
    "period": {
        "days": 30,
        "since": "2026-03-09 15:21:09"
    },
    "processing_time": "118.92ms",
    "reject_reasons": [],
    "status": "success",
    "top_reviewers": []
}
```

### Get HITL reviewer performance stats

`POST https://api.paperoffice.ai/latest/hitl_config/reviewer_stats`

Per-reviewer performance stats for a HITL config.

**Tool-ID:** `po_hitl_config_reviewer_stats` • **Cost:** Free • **MCP:** `po_hitl_config_reviewer_stats` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `config_uuid` | string | Yes | Config-UUID (Required) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "hitl_config___reviewer_stats",
        "app": "hitl_config",
        "action": "reviewer_stats",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.59ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List Config Reviewers

`GET https://api.paperoffice.ai/latest/hitl_config/list_reviewers`

List reviewers assigned to account HITL configs.

**Tool-ID:** `po_hitl_config_list_reviewers` • **Cost:** Free • **MCP:** `po_hitl_config_list_reviewers` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `config_uuid` | string | No | Optional: Config-UUID To Reviewer a specific HITL-Config zu filter |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9680
    },
    "job": {
        "api_job_name": "hitl_config___list_reviewers",
        "app": "hitl_config",
        "action": "list_reviewers",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.9ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List HITL Configs

`GET https://api.paperoffice.ai/latest/hitl_config/list`

List all HITL configurations for the account.

**Tool-ID:** `po_hitl_config_list` • **Cost:** Free • **MCP:** `po_hitl_config_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `include_inactive` | boolean | No |  |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9680
    },
    "job": {
        "api_job_name": "hitl_config___list",
        "app": "hitl_config",
        "action": "list",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "7.84ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Update HITL Config

`POST https://api.paperoffice.ai/latest/hitl_config/update`

Update HITL configuration. Partial updates supported.

**Tool-ID:** `po_hitl_config_update` • **Cost:** Free • **MCP:** `po_hitl_config_update` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `uuid` | string | Yes | Config-UUID (Required) |
| `name` | string | No |  |
| `trigger_rules` | array | No |  |
| `review_fields` | array | No |  |
| `binary_checks` | array | No |  |
| `reject_reasons` | array | No |  |
| `sla_config` | object | No |  |
| `assignment_config` | object | No |  |
| `result_config` | object | No |  |
| `instruction_text` | string | No |  |
| `credits_pro_review` | integer | No |  |
| `match_mode` | string | No | (allowed: any, all) |
| `is_active` | boolean | No |  |

**Example Response:**

```json
{
    "status": "success",
    "config": []
}
```

### Create Reviewer Profile

`POST https://api.paperoffice.ai/latest/hitl_review/create_profile`

Create or upsert a reviewer profile with language skills, tier and capacity settings.

**Tool-ID:** `po_hitl_create_reviewer_profile` • **Cost:** Free • **MCP:** `po_hitl_create_reviewer_profile` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `account_id` | integer | Yes | account-ID of the Reviewers (Required) |
| `native_languages` | array | No | Muttersprachen e.g. [de,tr] |
| `fluent_languages` | array | No | Spoken languages e.g. [en] |
| `basic_languages` | array | No | Grundkenntnisse e.g. [fr] |
| `reviewer_tier` | string | No | (allowed: exprot, standard, probation, suspended) |
| `max_concurrent_tasks` | integer | No |  |
| `is_active` | boolean | No |  |

**Example Response:**

```json
{
    "account_id": 1,
    "message": "Reviewer-Profil stored",
    "processing_time": "91.66ms",
    "status": "success"
}
```

### Get HITL consensus details

`POST https://api.paperoffice.ai/latest/hitl_review/consensus_details`

Retrieve all individual reviews for a task with side-by-side field comparison for supervisors.

**Tool-ID:** `po_hitl_consensus_details` • **Cost:** Free • **MCP:** `po_hitl_consensus_details` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_uuid` | string | Yes | UUID of the Tasks (Required) |

**Example Response:**

```json
{
    "status": "success",
    "task_data_summary": [],
    "reviews": [],
    "consensus": [],
    "field_comparison": [],
    "reviews_required": 1,
    "task_status": "example"
}
```

### Get HITL review dashboard

`GET https://api.paperoffice.ai/latest/hitl_review/dashboard`

Aggregated HITL review statistics incl. awaiting_reviews, consensus metrics.

**Tool-ID:** `po_hitl_dashboard` • **Cost:** 10 credits • **MCP:** `po_hitl_dashboard` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9680
    },
    "job": {
        "api_job_name": "hitl_review___dashboard",
        "app": "hitl_review",
        "action": "dashboard",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "7.98ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get HITL review statistics

`GET https://api.paperoffice.ai/latest/hitl_review/stats`

Alias for dashboard. Returns identical statistics.

**Tool-ID:** `po_hitl_get_stats` • **Cost:** 10 credits • **MCP:** `po_hitl_get_stats` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9680
    },
    "job": {
        "api_job_name": "hitl_review___stats",
        "app": "hitl_review",
        "action": "stats",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.28ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Get HITL task details

`POST https://api.paperoffice.ai/latest/hitl_review/get`

Retrieve full details of a single HITL review task by UUID.

**Tool-ID:** `po_hitl_get_task` • **Cost:** Free • **MCP:** `po_hitl_get_task` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_uuid` | string | Yes | UUID of the Tasks (Required) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9489
    },
    "job": {
        "api_job_name": "hitl_review___get",
        "app": "hitl_review",
        "action": "get",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.2ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List Review Queue

`GET https://api.paperoffice.ai/latest/hitl_review/list`

HITL review queue with personalized ordering by language match and SLA urgency.

**Tool-ID:** `po_hitl_list_reviews` • **Cost:** 10 credits • **MCP:** `po_hitl_list_reviews` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | No | Status-Filter: pending, in_progress, awaiting_reviews, completed, rejected, all |
| `priority` | integer | No | prioritys-Filter: urgent, high, normal, low |
| `search` | string | No | Freitext-Search |
| `reviewer_account_id` | integer | No | account ID for prosonalized sorting |
| `page` | integer | No | page (Standard: 1) |
| `limit` | integer | No | per page (Standard: 50, Max: 200) |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9680
    },
    "job": {
        "api_job_name": "hitl_review___list",
        "app": "hitl_review",
        "action": "list",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.26ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List Reviewer Profiles

`GET https://api.paperoffice.ai/latest/hitl_review/list_reviewers`

List all reviewer profiles from SOT including language skills, tier, accuracy scores.

**Tool-ID:** `po_hitl_list_reviewers` • **Cost:** Free • **MCP:** `po_hitl_list_reviewers` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9680
    },
    "job": {
        "api_job_name": "hitl_review___list_reviewers",
        "app": "hitl_review",
        "action": "list_reviewers",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.25ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Submit HITL consensus review

`POST https://api.paperoffice.ai/latest/hitl_review/submit_review`

Submit a review decision (approve/reject/escalate) for a HITL task. Part of 3-reviewer consensus workflow.

**Tool-ID:** `po_hitl_submit_review` • **Cost:** Free • **MCP:** `po_hitl_submit_review` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_uuid` | string | Yes | UUID to reviewenthe Tasks (Required) |
| `decision` | string | Yes | Review-decision (Required) (allowed: approve, reject, escalate) |
| `field_results` | object | No | field-Korrekturen as Key-Value |
| `check_results` | object | No | Binary-Check results |
| `reject_reason_id` | string | No | Ablehnungsgrand-ID (Required at reject if no reject_comment) |
| `reject_comment` | string | No | Rejection comment |
| `escalation_comment` | string | No | Eskalationsgrund |
| `comment` | string | No | General Reviewer comment |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "review_uuid": "example",
    "reviews_completed": 1,
    "reviews_required": 1,
    "consensus_reached": true,
    "new_status": "example",
    "kappa": 1
}
```

### Update Reviewer Profile

`POST https://api.paperoffice.ai/latest/hitl_review/update_profile`

Update an existing reviewer profile (upsert semantics).

**Tool-ID:** `po_hitl_update_reviewer_profile` • **Cost:** Free • **MCP:** `po_hitl_update_reviewer_profile` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `account_id` | integer | Yes | account-ID of the Reviewers (Required) |
| `native_languages` | array | No |  |
| `fluent_languages` | array | No |  |
| `basic_languages` | array | No |  |
| `reviewer_tier` | string | No | (allowed: exprot, standard, probation, suspended) |
| `max_concurrent_tasks` | integer | No |  |
| `is_active` | boolean | No |  |

**Example Response:**

```json
{
    "account_id": 1,
    "message": "Reviewer-Profil stored",
    "processing_time": "126.61ms",
    "status": "success"
}
```

---

## Workflow AI — Job Management

### Download Job Result

`GET https://api.paperoffice.ai/latest/job/download/{download_token}`

Download the result file of a completed job. The download_token is returned in the job result from /job/get/{job_id} when the job status is "completed". The token is temporary and expires. Supported result types: images (PNG/JPG/WebP), PDFs, audio files (MP3/WAV), documents (DOCX/XLSX). The response Content-Type header indicates the file format.

**Tool-ID:** `po_jobs_download_result` • **Cost:** Free

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `download_token` | string | Yes | Temporary download token from the job result (returned by /job/get/{job_id}) |

**Example Response:**

```json
{
    "content_type": "application/octet-stream",
    "content_length": 102400,
    "note": "Binary file response — consume as stream, not JSON. Check Content-Type header."
}
```

### Get job status and result

`GET https://api.paperoffice.ai/latest/job/get/{job_id}`

Retrieve the status and result of a processing job. Polling: call this endpoint every 5-10 seconds until job_status is "completed" or "failed". When completed, the response contains the job result with download URLs (for file outputs) or inline data (for text outputs). The async workflow is: 1) POST /job/add/{pipeline} → get job_id, 2) GET /job/get/{job_id} → poll status, 3) GET /job/download/{token} → download result file. Note: Synchronous jobs return results directly in the /job/add response. Jobs exceeding 45s timeout return HTTP 408 with the job_id for async retrieval.

**Tool-ID:** `po_jobs_get_job_status_result` • **Cost:** 10 credits • **MCP:** `po_jobs_get_job_status_result` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | string | Yes | The job ID returned by a previous tool call (format: poai-job_XXX_TIMESTAMP_HASH) |

### Get pricelist

`GET https://api.paperoffice.ai/latest/job/pricelist`

Get API Pricelist Returns all available API methods with their credit costs. Cost: 10 credits Response: json { "pricelist": { "ip2location___full": { "credits": 0.01, "unit": "request", "description": "Full IP geolocation" }, "paperoffice_imagestudio___generate___basic": { "credits": 5, "unit": "image", "description": "Image Generation Basic" } } }

**Tool-ID:** `po_jobs_get_pricelist` • **Cost:** 10 credits • **MCP:** `po_jobs_get_pricelist` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9680
    },
    "job": {
        "api_job_name": "job___pricelist",
        "app": "job",
        "action": "pricelist",
        "default_credits": 10,
        "ocr_mode": "basic",
        "text_length": 0,
        "audio_duration_seconds": 0,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.94ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Ping management endpoint

`GET https://api.paperoffice.ai/latest/health`

Simple Ping Basic connectivity check. Returns "pong" if API is reachable. No Authentication Required Response: json { "status": "pong", "timestamp": 1736942400 }

**Tool-ID:** `po_jobs_ping` • **Cost:** 10 credits • **MCP:** `po_jobs_ping` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "message": "api-worker is running stable inside limits",
    "processing_time": "3.94ms",
    "success": true
}
```

---

## Workflow AI — Orchestration

### Decide on approval

`POST https://api.paperoffice.ai/latest/approvals/decide`

Makes an approval decision (approved or rejected) for an approval step.

**Tool-ID:** `po_approval_decide` • **Cost:** 10 credits • **MCP:** `po_approval_decide` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `approval_id` | string | Yes | Approval-ID (e.g. appr_abc123) |
| `decision` | string | Yes | decision: approved or rejected (allowed: approved, rejected) |
| `comment` | string | No | comment on the decision (possibly required in case of rejection) |
| `user_id` | string | No | Approver user_id (optional, agent acts on behalf of users) |
| `step_order` | integer | No | Step Number (optional, for Admin/Agent access to a specific step) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully"
}
```

### Get Approval Status

`POST https://api.paperoffice.ai/latest/approvals/status`

Returns the complete status of an approval request, including all steps, audit trail, and deadline information.

**Tool-ID:** `po_approval_status` • **Cost:** 10 credits • **MCP:** `po_approval_status` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `approval_id` | string | Yes | Approval-ID |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9439
    },
    "job": {
        "api_job_name": "approvals___status",
        "app": "approvals",
        "action": "status",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "8.06ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### List Approvals

`POST https://api.paperoffice.ai/latest/approvals/list`

List all release requests for the account, optionally filtered by status.

**Tool-ID:** `po_approval_list` • **Cost:** 10 credits • **MCP:** `po_approval_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | No | Status-Filter (allowed: pending, in_progress, approved, rejected, expired, cancelled) |
| `limit` | integer | No | (default: 50) |
| `offset` | integer | No | (default: 0) |

**Example Response:**

```json
{
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9439
    },
    "job": {
        "api_job_name": "approvals___list",
        "app": "approvals",
        "action": "list",
        "default_credits": 10,
        "rate_limited": true,
        "credits_billed": 0
    },
    "processing_time": "7.79ms",
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    }
}
```

### Submit document for approval

`POST https://api.paperoffice.ai/latest/approvals/submit`

Submit a document for approval. Define the approver, type (sequential/parallel/arbitrary), and deadline.

**Tool-ID:** `po_approval_submit` • **Cost:** 10 credits • **MCP:** `po_approval_submit` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_id` | integer | No | Document ID for the approval |
| `document_pofid` | string | No | Alternative: POFDocument ID |
| `approval_type` | string | No | sequential = one after another, parallel = all simultaneously, any = one approval suffices (allowed: sequential, parallel, any) (default: "sequential") |
| `approvers` | array | Yes | list the approvers |
| `deadline_hours` | integer | No | Deadline in hours (default: 48) |
| `escalation_user_id` | string | No | User-ID for Escalation at Deadline Breach |
| `message` | string | No | message an the approvers |
| `title` | string | No | Title the approval request |
| `require_comment_on_reject` | boolean | No | comment at rejection erzwingen (default: false) |

**Example Response:**

```json
{
    "status": "success",
    "message": "Operation completed successfully",
    "id": 12345,
    "created_at": "2026-04-16T10:00:00Z"
}
```

### Explain workflow (AI)

`POST https://api.paperoffice.ai/latest/workflow_ai/explain`

Explain Workflow: Obtain a natural language description of the functionality and steps of a specified workflow.

**Tool-ID:** `po_workflow_ai_explain_workflow` • **Cost:** 10 credits • **MCP:** `po_workflow_ai_explain_workflow` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workflow` | object | Yes | Workflow-object the erklaert should be |
| `language` | string | No | Ausgabesprache (allowed: de, en) (default: "de") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "explanation": "example",
            "steps_explained": [
                []
            ],
            "complexity_rating": "example"
        }
    }
}
```

### Generate workflow

`POST https://api.paperoffice.ai/latest/workflow_ai/generate`

Generate Workflow with AI Let AI create a workflow from a natural language description. --- When to Use - Quickly create new workflows - Get AI suggestions for automation - Convert requirements to workflows --- Parameters | Parameter | Type | Required | Description | |-----------|------|---------.

**Tool-ID:** `po_workflow_ai_generate_workflow` • **Cost:** 100 credits • **MCP:** `po_workflow_ai_generate_workflow` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `prompt` | string | Yes | description the desired Workflows in natural language |
| `include_human_tasks` | boolean | No | Human-in-the-Loop Steps einbeziehen (default: true) |
| `add_error_handling` | boolean | No | automatic error handling (default: true) |
| `model` | string | No | LLM Model for Generation (allowed: basic, premium, ultra) (default: "ultra") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "generation_id": "00000000-0000-0000-0000-000000000001",
    "generation_time_ms": 17502,
    "message": "Workflow erfolgreich generiert",
    "processing_time": "17634.34ms",
    "status": "success",
    "workflow": {
        "name": "document_management_explanation_workflow",
        "description": "A workflow for creating, reviewing, and approving a definition of document management using the PaperOffice AI Pipelines.",
        "trigger_type": "trigger_document_uploaded",
        "is_active": true,
        "nodes": [
            {
                "id": 1,
                "type": "trigger_document_uploaded",
                "label": "Trigger_document_uploaded",
                "position": {
                    "x": 100,
                    "y": 200
                },
                "data": {
                    "label": "Trigger_document_uploaded"
                },
                "config": {
                    "workspace_filter": null,
                    "folder_filter": null
                }
            },
            {
                "id": 2,
                "type": "notify",
                "label": "Notify",
                "position": {
                    "x": 500,
                    "y": 200
                },
                "data": {
                    "label": "Notify"
                },
                "config": {
                    "recipients": [
                        15
                    ],
                    "title": "Workflow Notification",
                    "message": "An event has occurred.",
                    "priority": "high",
                    "channels": [
                        "sse",
                        "bell"
                    ]
                }
            },
            {
                "id": 3,
                "type": "review",
                "label": "Review",
                "position": {
                    "x": 900,
                    "y": 200
                },
                "data": {
                    "label": "Review"
                },
                "config": {
                    "title": "Manual Audit required",
                    "reviewer_role": "",
                    "reviewer_users": [
                        15
                    ],
                    "timeout_hours": 24,
                    "allow_comments": true,
                    "allow_attachments": true,
                    "review_options": [
                        "approve",
                        "reject",
                        "request_changes"
                    ]
                }
            },
            {
                "id": 4,
                "type": "notify",
                "label": "Notify",
                "position": {
                    "x": 1300,
                    "y": 200
                },
                "data": {
                    "label": "Notify"
                },
                "config": {
                    "recipients": [
                        15
                    ],
                    "title": "Workflow Notification",
                    "message": "An event has occurred.",
                    "priority": "high",
                    "channels": [
                        "sse",
                        "bell"
                    ]
                }
            },
            {
                "id": "3_changes_requested_fallback",
                "type": "notify",
                "label": "Aenderungen angefordert",
                "position": {
                    "x": 1200,
                    "y": 450
                },
                "data": {
                    "label": "Aenderungen angefordert"
                },
                "config": {
                    "title": "Aenderungen angefordert",
                    "message": "The path 'changes_requested' was triggered at 'Review'.",
                    "channels": [
                        "in_app"
                    ]
                }
            }
        ],
        "connections": [
            {
                "id": "edge_0",
                "source": 1,
                "target": 2,
                "sourceHandle": "output",
                "targetHandle": "input"
            },
            {
                "id": "edge_1",
                "source": 2,
                "target": 3,
                "sourceHandle": "output",
                "targetHandle": "input"
            },
            {
                "id": "edge_2",
                "source": 3,
                "target": 4,
                "sourceHandle": "completed",
                "targetHandle": "input"
            },
            {
                "id": "edge_repair_3",
                "source": 3,
                "target": "3_changes_requested_fallback",
                "sourceHandle": "changes_requested",
                "targetHandle": "input",
                "label": null
            }
        ]
    }
}
```

### Optimize workflow (AI)

`POST https://api.paperoffice.ai/latest/workflow_ai/optimize`

Optimize Workflow AI analyzes and suggests optimizations. --- Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | template_id | string | ✅ | Workflow to optimize | --- Response json { "success": true, "suggestions": { "type": "merge_steps", "."

**Tool-ID:** `po_workflow_ai_optimize_workflow` • **Cost:** 10 credits • **MCP:** `po_workflow_ai_optimize_workflow` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workflow` | object | Yes | Workflow-object the optimiert should be |
| `goal` | string | No | Optimierungsziel (allowed: efficiency, cost, reliability) (default: "efficiency") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

### Suggest next workflow step (AI)

`POST https://api.paperoffice.ai/latest/workflow_ai/suggest_next`

Suggest Next Step AI suggests what step to add next. --- Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | current_steps | array | ✅ | Existing steps | | goal | string | ❌ | What to achieve | --- Response json { "success": true, "suggesti.

**Tool-ID:** `po_workflow_ai_suggest_next_step` • **Cost:** 10 credits • **MCP:** `po_workflow_ai_suggest_next_step` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `nodes` | array | No | current Workflow-Nodes |
| `connections` | array | No | current Connections |
| `context` | string | No | Additionalr Kontext for the suggestions (default: "") |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "suggestions": [
                {
                    "node_type": "example",
                    "label": "example",
                    "description": "example",
                    "confidence": 1
                }
            ]
        }
    }
}
```

### Validate workflow

`POST https://api.paperoffice.ai/latest/workflow_ai/validate`

Validate Workflow Check workflow for errors and issues. --- Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | template_id | string | ✅ | Workflow to validate | --- Response json { "success": true, "valid": true, "warnings": , "errors": }

**Tool-ID:** `po_workflow_ai_validate_workflow` • **Cost:** 10 credits • **MCP:** `po_workflow_ai_validate_workflow` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workflow` | object | Yes | Workflow-object with nothe and connections. Node-Typen: start, end, approval, condition, notification, webhook, delay, document_action, ai_classify, form. |
| `priority` | integer | No | Optional. 900 = SYNC (result returned inline, ~20s SLA, best for development/testing). <900 = ASYNC (returns job_id, then poll GET /job/get/{job_id} for the result). If omitted, the tier-default from the bearer-token plan applies (e.g. APP-T1=0, APP-T6=200, API-T6=200). Priority higher than the tier-default consumes priority-boost credits. See collection description for the full priority table. |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "is_valid": true,
            "errors": [
                []
            ],
            "warnings": [
                []
            ],
            "suggestions": [
                "example"
            ]
        }
    }
}
```

---

## Workflow AI — Tasks

### Create Substitute

`POST https://api.paperoffice.ai/latest/substitutes/create`

Create a new delegation rule with a time period and permissions.

**Tool-ID:** `po_substitutes_create` • **Cost:** 10 credits • **MCP:** `po_substitutes_create` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `substitute_user_id` | integer | Yes | User-ID of the substitute, the substitution vianimmt |
| `start_date` | string | No | Start date the substitution (ISO 8601, optional) |
| `end_date` | string | No | End date the substitution (ISO 8601, optional) |
| `substitute_id` | integer | No | Substitute id |
| `valid_from` | string | No | Valid from |
| `valid_until` | string | No | Valid until |
| `scope` | string | No | Scope |
| `scope_filter` | object | No | Scope filter |
| `can_approve` | boolean | Yes | Can approve |
| `notify_original` | boolean | Yes | Notify original |
| `reason` | string | No | Reason |

**Example Response:**

```json
{
    "success": false,
    "error": "SQLSTATE[23000]: Integrity constraint violation: 1048 Column 'valid_from' cannot be null"
}
```

### Delete Substitute

`POST https://api.paperoffice.ai/latest/substitutes/delete`

Remove an existing delegation rule.

**Tool-ID:** `po_substitutes_delete` • **Cost:** 10 credits • **MCP:** `po_substitutes_delete` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | Yes | ID of the substitution rule, the deleted should be |
| `substitute_id` | integer | No | Substitute id |

**Example Response:**

```json
{
    "success": false,
    "error": "ID_REQUIRED"
}
```

### List active substitutes

`GET https://api.paperoffice.ai/latest/substitutes/get_active`

Get active substitutes.

**Tool-ID:** `po_substitutes_get_active` • **Cost:** 10 credits • **MCP:** `po_substitutes_get_active` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `user_id` | integer | Yes | User-ID of the Users these active substitution abgefragt is (Required) |

**Example Response:**

```json
{
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    },
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "job": {
        "api_job_name": "substitutes___get_active",
        "app": "substitutes",
        "action": "get_active",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "user_id": "1",
        "rate_limited": true,
        "credits_billed": 0
    }
}
```

### List Substitutes

`GET https://api.paperoffice.ai/latest/substitutes/list`

List configured substitutes.

**Tool-ID:** `po_substitutes_list` • **Cost:** 10 credits • **MCP:** `po_substitutes_list` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `user_id` | integer | No | User id |
| `include_inactive` | boolean | No | Include inactive |

**Example Response:**

```json
{
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    },
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "job": {
        "api_job_name": "substitutes___list",
        "app": "substitutes",
        "action": "list",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "rate_limited": true,
        "credits_billed": 0
    }
}
```

### List substitutes delegated to me

`GET https://api.paperoffice.ai/latest/substitutes/list_delegated_to_me`

Delegations where I at the substitute.

**Tool-ID:** `po_substitutes_list_delegated` • **Cost:** 10 credits • **MCP:** `po_substitutes_list_delegated` via `mcp.paperoffice.ai`

**Example Response:**

```json
{
    "status": {
        "code": 429,
        "message": "Rate Limit Exceeded",
        "success": false
    },
    "credits": {
        "total_monthly": 50000,
        "remaining_monthly": 9580
    },
    "requests": {
        "message": "Rate limit for SECOND exceeded. Please wait 1 seconds before retrying.",
        "next_possible_request_seconds": 1
    },
    "job": {
        "api_job_name": "substitutes___list_delegated_to_me",
        "app": "substitutes",
        "action": "list_delegated_to_me",
        "default_credits": 10,
        "token": "po_sk_EXAMPLE_TOKEN",
        "rate_limited": true,
        "credits_billed": 0
    }
}
```

### Update Substitute

`POST https://api.paperoffice.ai/latest/substitutes/update`

Updates an existing delegation rule (period, permissions, status).

**Tool-ID:** `po_substitutes_update` • **Cost:** 10 credits • **MCP:** `po_substitutes_update` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | Yes | ID of the substitution rule, the updates should be |
| `substitute_id` | integer | No | Substitute id |
| `valid_from` | string | Yes | Valid from |
| `valid_until` | string | Yes | Valid until |
| `scope` | string | Yes | Scope |
| `scope_filter` | object | Yes | Scope filter |
| `can_approve` | boolean | Yes | Can approve |
| `notify_original` | boolean | Yes | Notify original |
| `reason` | string | Yes | Reason |
| `is_active` | boolean | Yes | Is active |

**Example Response:**

```json
{
    "success": false,
    "error": "ID_REQUIRED"
}
```

### Claim task

`POST https://api.paperoffice.ai/latest/workflow_tasks/claim`

Takes on a task

**Tool-ID:** `po_tasks_claim_task` • **Cost:** 10 credits • **MCP:** `po_tasks_claim_task` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_id` | string | No | ID of the task (default: "") |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "claimed": true,
            "task_id": "example",
            "claimed_by": "example"
        }
    }
}
```

### Complete task

`POST https://api.paperoffice.ai/latest/workflow_tasks/complete`

Mark a task as completed

**Tool-ID:** `po_tasks_complete_task` • **Cost:** 10 credits • **MCP:** `po_tasks_complete_task` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_id` | string | No | ID of the task (default: "") |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "completed": true,
            "task_id": "example",
            "decision": "example",
            "workflow_continued": true
        }
    }
}
```

### Get task details

`POST https://api.paperoffice.ai/latest/workflow_tasks/get`

Task Details

**Tool-ID:** `po_tasks_get_task_details` • **Cost:** 10 credits • **MCP:** `po_tasks_get_task_details` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_id` | string | No | ID of the task |

### List my tasks

`POST https://api.paperoffice.ai/latest/workflow_tasks/list`

List all tasks of the current user

**Tool-ID:** `po_tasks_list_my_tasks` • **Cost:** 10 credits • **MCP:** `po_tasks_list_my_tasks` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | No | Filter after Status (allowed: pending, in_progress, completed, rejected, expired, escalated) |
| `priority` | string | No | Task priority. Determines display order and SLA for Kanban/To-Do views. (allowed: low, normal, high, urgent) |
| `step_type` | string | No | Filter after Step-type (e.g. approval, review, manual_input) |
| `limit` | integer | No | Max. Tasks (default: 50) |
| `offset` | integer | No | Pagination-Offset (default: 0) |

**Execution Mode:** `priority>=900` SYNC (inline result), `priority<900` ASYNC (returns `job_id`).

**Example Response:**

```json
{
    "limit": 50,
    "offset": 0,
    "processing_time": "21.3ms",
    "status": "success",
    "tasks": [],
    "total": 0
}
```

### Mark Task Read

`POST https://api.paperoffice.ai/latest/workflow_tasks/mark_read`

Mark a task as read

**Tool-ID:** `po_tasks_mark_as_read` • **Cost:** 10 credits • **MCP:** `po_tasks_mark_as_read` via `mcp.paperoffice.ai`

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_id` | string | No | ID of the task (default: "") |

**Example Response:**

```json
{
    "status": "success",
    "job_id": "job_01HXY1234ABCDEF",
    "message": "Operation completed successfully",
    "pipeline": "example-pipeline",
    "operation": "example",
    "processing_time": "example",
    "server": "example",
    "timing": {
        "actual_ms": 150,
        "expected_ms": 150,
        "timeout_ms": 150,
        "speed_factor": 1,
        "performance": "example"
    },
    "result": {
        "status": "completed",
        "message": "Operation completed successfully",
        "duration_ms": "example",
        "output": {
            "marked": true,
            "task_id": "example"
        }
    }
}
```

---

## Further Reading

- **Postman Collection:** https://api.paperoffice.ai/latest/docs/postman
- **Pricing:** https://app.paperoffice.ai/en/pricing/calculator
- **Pricing Tiers (API):** https://api.paperoffice.ai/latest/billing/pricing/tiers
- **MCP Server:** https://mcp.paperoffice.ai/mcp
- **Get API Token:** https://paperoffice.ai

*Generated 2026-04-19 from live SOT (MariaDB `api_tools`).*