{
  "openapi": "3.0.0",
  "info": {
    "title": "Pixel Office Autonomous Developer Services & Utility APIs",
    "version": "1.0.0",
    "description": "Standardized machine-readable APIs enabling autonomous LLM agents, GPTs, and automated workflows to invoke premium developer utilities, compliance tools, and legal generators.\n\n### Machine-to-Machine Payment Protocol (PixelPay)\nSeveral endpoints in this directory require a micropayment of **$1.99 USD** (or equivalent in USDC/Sats). These endpoints enforce payment verification on direct A2A (Agent-to-Agent) calls.\n\n**Integration Flow for AI Agents:**\n1. Call any premium endpoint (e.g., `/api/gdpr/scan`) directly.\n2. If no valid `X-Payment-Reference` is provided, the server returns a **`402 Payment Required`** status code with a JSON payload containing:\n   - Solana merchant wallet address and reference key.\n   - A BOLT11 Bitcoin Lightning invoice hash.\n   - A `pay_url` for Solana Pay deep linking.\n   - A `verify_url` endpoint.\n3. The calling Agent should parse the `402` payload and make a transfer of the specified amount to the merchant wallet.\n4. Call `/api/pay/verify-crypto?method=solana&ref=<REFERENCE>&slug=<TOOL_SLUG>` to poll status until settled.\n5. Retry the original request, adding the header `X-Payment-Reference: <REFERENCE>` to authorize the operation.",
    "contact": {
      "name": "Pixel Office Support",
      "url": "https://pixeloffice.eu",
      "email": "support@pixeloffice.eu"
    }
  },
  "servers": [
    {
      "url": "https://api.pixeloffice.eu",
      "description": "Production Server"
    }
  ],
  "security": [
    {
      "PixelPayRef": []
    }
  ],
  "paths": {
    "/api/gdpr/scan": {
      "post": {
        "summary": "GDPR Consent Scanner",
        "description": "Scans a target website url using headless Puppeteer to identify tracking cookies, tracking pixels, and scripts, validating compliance with EU GDPR cookie consent requirements.",
        "operationId": "scanGdprCompliance",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GdprScanRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "GDPR scan successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GdprScanResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input URL or validation failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required - Premium endpoint needs authorization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server processing error"
          }
        }
      }
    },
    "/api/policy/generate": {
      "post": {
        "summary": "Global Policy Forge",
        "description": "Generates complete, professional, legally compliant legal documents (Terms of Service, Privacy Policies, Refund Policies, or Cookie Policies) tailored to your business profile using the Gemini 2.5 engine.",
        "operationId": "generatePolicy",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PolicyGenerateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Policy document successfully generated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyGenerateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error"
          }
        }
      }
    },
    "/api/favicon/generate": {
      "post": {
        "summary": "Universal Icon Forge",
        "description": "Processes a base64-encoded logo source image, resizing and compiling a full set of browser favicons, Apple touch icons, and Android app icons inside a downloadable ZIP archive.",
        "operationId": "generateFavicons",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FaviconGenerateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Favicon archive successfully generated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaviconGenerateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error"
          }
        }
      }
    },
    "/api/whistleblowing/create-portal": {
      "post": {
        "summary": "Whistleblowing Safe Haven",
        "description": "Configures and registers a secure anonymous whistleblowing portal mapping configuration to help companies comply with the EU Whistleblower Protection Directive.",
        "operationId": "createWhistleblowerPortal",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WhistleblowingCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Whistleblower portal registration successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WhistleblowingCreateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error"
          }
        }
      }
    },
    "/api/invoice": {
      "post": {
        "summary": "AI Invoice PDF Creator & ZUGFeRD XML Invoice Generator",
        "description": "Generates responsive HTML invoices and standard compliance PDFs containing structured business information, ARES/VIES lookup support, and integrated QR payment codes.",
        "operationId": "generateInvoice",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvoiceCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invoice HTML and PDF generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceCreateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing required data fields"
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredResponse"
                }
              }
            }
          },
          "500": {
            "description": "PDF rendering error"
          }
        }
      }
    },
    "/api/playable-ads/generate-zip": {
      "post": {
        "summary": "Playable Ads ZIP Generator",
        "description": "Compiles raw interactive HTML game/ad code into an offline-ready structured ZIP archive optimized for publishing on major advertising networks.",
        "operationId": "generatePlayableAdsZip",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlayableAdsZipRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "ZIP archive created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Unique ID of the generated archive. Downloadable at /downloads/playable-ad-{id}.zip"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing HTML content"
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredResponse"
                }
              }
            }
          },
          "500": {
            "description": "Zipping failed"
          }
        }
      }
    },
    "/api/tts": {
      "post": {
        "summary": "Edge Text-to-Speech Engine",
        "description": "Converts plain text strings into rich audio speech files (returned as a base64 encoded audio track or URL stream).",
        "operationId": "generateTtsSpeech",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "description": "Text to synthesize into speech"
                  },
                  "voice": {
                    "type": "string",
                    "description": "Voice identifier model (e.g. cs-CZ-VlastaNeural)",
                    "default": "cs-CZ-VlastaNeural"
                  }
                },
                "required": ["text"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audio track synthesized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "audioUrl": { "type": "string", "description": "Stream url for the generated speech mp3" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/voice-agent/chat": {
      "post": {
        "summary": "AI Voice Agent Chatbot Interface",
        "description": "Sends speech recordings to be transcribed by Gemini, processed through AI persona rules, and spoken back using the TTS Edge processor.",
        "operationId": "voiceAgentChat",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "audio": {
                    "type": "string",
                    "description": "Base64 encoded audio stream recording"
                  },
                  "mimeType": {
                    "type": "string",
                    "description": "Mime type format, e.g. audio/webm, audio/wav, audio/mp3",
                    "default": "audio/webm"
                  },
                  "agentId": {
                    "type": "string",
                    "description": "Persona ID support voice agent (e.g. klara or male)",
                    "default": "klara"
                  },
                  "lang": {
                    "type": "string",
                    "description": "Two letter language code",
                    "default": "cs"
                  }
                },
                "required": ["audio"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Conversational reply synthesized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "userText": { "type": "string", "description": "Gemini transcription result of the user audio input" },
                    "replyText": { "type": "string", "description": "Gemini text response" },
                    "audio": { "type": "string", "description": "Base64 synthesized audio response track (mp3)" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/pay/request-crypto": {
      "post": {
        "summary": "Create PixelPay Payment Reference",
        "description": "Initializes a payment session for a tool unlock, returning standard transaction parameters for Solana Pay and BOLT11 Bitcoin Lightning protocols.",
        "operationId": "requestPayment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string",
                    "description": "The unique slug ID of the micro project (e.g. gdpr-cookie-consent-scanner)"
                  },
                  "widgetName": {
                    "type": "string",
                    "description": "Human readable name of the micro application"
                  },
                  "amount": {
                    "type": "integer",
                    "description": "Micropayment amount in USD cents (default: 199 for 1.99 USDC)",
                    "default": 199
                  }
                },
                "required": ["slug"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment reference created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PayRequestResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/pay/verify-crypto": {
      "get": {
        "summary": "Verify PixelPay Settlement Status",
        "description": "Polls the status of a payment reference to confirm if transaction was successfully settled on chain.",
        "operationId": "verifyPayment",
        "parameters": [
          {
            "name": "method",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["solana", "lightning"]
            },
            "description": "Select the checking method"
          },
          {
            "name": "ref",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Reference tracking token (e.g. SOLANA_MOCK_REF_... or Lightning hash)"
          },
          {
            "name": "slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Identifier slug of the tool being unlocked"
          }
        ],
        "responses": {
          "200": {
            "description": "Verification status check complete",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "description": "True if payment transaction verified" },
                    "slug": { "type": "string" },
                    "txid": { "type": "string", "description": "Transaction signature hash (Solana only)" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/chat": {
      "post": {
        "summary": "Direct AI Karel Chat Assistant",
        "description": "Sends messages directly to the Pixel Office main autonomous consultant (Karel) to answer questions, explain systems, or assist with integration steps.",
        "operationId": "chatWithKarel",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "Chat question or instructions"
                  }
                },
                "required": ["message"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Response reply received",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reply": { "type": "string", "description": "Text output from Karel" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agents": {
      "get": {
        "summary": "List AI Specialist Agents",
        "description": "Returns a comprehensive list of all active AI specialist agent slots (e.g. Karel, Robert, Clara) deployed within the Pixel Office ecosystem.",
        "operationId": "listAgents",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string" },
                      "name": { "type": "string" },
                      "role": { "type": "string" },
                      "description": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agents/{id}/ask": {
      "post": {
        "summary": "Send Query to Specific AI Specialist Agent",
        "description": "Queries a specific specialized AI agent from the list by ID (e.g., Robert the lawyer, Karel the developer).",
        "operationId": "querySpecialistAgent",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent identifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "Message query content to send to agent"
                  }
                },
                "required": ["message"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent reply response received",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "reply": { "type": "string", "description": "The response text from target agent" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PixelPayRef": {
        "type": "apiKey",
        "name": "X-Payment-Reference",
        "in": "header",
        "description": "Micropayment transaction settlement reference code obtained via Solana Pay or Bitcoin Lightning."
      }
    },
    "schemas": {
      "GdprScanRequest": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The full website URL to audit (e.g., https://example.com)"
          }
        },
        "required": ["url"]
      },
      "GdprScanResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "scanResults": {
            "type": "object",
            "properties": {
              "cookies": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" },
                    "domain": { "type": "string" },
                    "value": { "type": "string" },
                    "expires": { "type": "number" },
                    "httpOnly": { "type": "boolean" },
                    "secure": { "type": "boolean" }
                  }
                }
              },
              "trackers": {
                "type": "array",
                "items": { "type": "string" }
              },
              "complianceScore": { "type": "integer", "minimum": 0, "maximum": 100 },
              "warnings": {
                "type": "array",
                "items": { "type": "string" }
              }
            }
          }
        }
      },
      "PolicyGenerateRequest": {
        "type": "object",
        "properties": {
          "companyName": {
            "type": "string",
            "description": "Legal company name to generate legal documentation for"
          },
          "websiteUrl": {
            "type": "string",
            "format": "uri",
            "description": "Target website URL using standard protocol"
          },
          "policyType": {
            "type": "string",
            "enum": ["terms", "privacy", "cookie", "refund"],
            "default": "terms",
            "description": "Legal document document type"
          },
          "country": {
            "type": "string",
            "default": "Česká republika",
            "description": "Jurisdiction region"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Contact support email to embed in documents"
          },
          "collectPersonalData": {
            "type": "boolean",
            "default": false,
            "description": "Embed personal data policies if true"
          },
          "useCookies": {
            "type": "boolean",
            "default": false,
            "description": "Embed cookie policy clauses if true"
          }
        },
        "required": ["companyName", "websiteUrl"]
      },
      "PolicyGenerateResponse": {
        "type": "object",
        "properties": {
          "policyType": { "type": "string" },
          "content": {
            "type": "string",
            "description": "Generated legal terms formatted as complete Markdown text blocks"
          }
        }
      },
      "FaviconGenerateRequest": {
        "type": "object",
        "properties": {
          "image": {
            "type": "string",
            "description": "Source image contents encoded as raw base64 or prefixed data-url stream"
          }
        },
        "required": ["image"]
      },
      "FaviconGenerateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "downloadUrl": {
            "type": "string",
            "description": "Relative URL path to download compiled zip archive (e.g. /downloads/favicon-pack-...)"
          },
          "id": { "type": "string" }
        }
      },
      "WhistleblowingCreateRequest": {
        "type": "object",
        "properties": {
          "companyName": {
            "type": "string",
            "description": "Corporate organization name"
          },
          "customSubdomain": {
            "type": "string",
            "pattern": "^[a-z0-9-]+$",
            "description": "URL-safe alphanumeric subdomain prefix"
          },
          "contactEmail": {
            "type": "string",
            "format": "email",
            "description": "Official reviewer reviewer notifications address"
          }
        },
        "required": ["companyName", "customSubdomain", "contactEmail"]
      },
      "WhistleblowingCreateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "portalId": { "type": "string" },
          "portalUrl": { "type": "string", "description": "Access URL of the generated safe whistleblowing portal website" },
          "companyName": { "type": "string" },
          "subdomain": { "type": "string" }
        }
      },
      "InvoiceCreateRequest": {
        "type": "object",
        "properties": {
          "lang": {
            "type": "string",
            "default": "en",
            "description": "Two letter translation language key"
          },
          "invoiceData": {
            "type": "object",
            "properties": {
              "number": { "type": "string", "description": "Unique invoice identifier number" },
              "issueDate": { "type": "string", "format": "date" },
              "dueDate": { "type": "string", "format": "date" },
              "seller": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "ico": { "type": "string", "description": "Company ID (ARES)" },
                  "dic": { "type": "string", "description": "VAT ID (VIES)" },
                  "address": { "type": "string" },
                  "bankAccount": { "type": "string" },
                  "iban": { "type": "string" },
                  "swift": { "type": "string" }
                },
                "required": ["name", "address"]
              },
              "buyer": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "ico": { "type": "string" },
                  "dic": { "type": "string" },
                  "address": { "type": "string" }
                },
                "required": ["name", "address"]
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" },
                    "quantity": { "type": "number" },
                    "unitPrice": { "type": "number" },
                    "vatRate": { "type": "number", "description": "VAT rate percentage" }
                  },
                  "required": ["name", "quantity", "unitPrice"]
                }
              },
              "currency": { "type": "string", "default": "EUR" },
              "total": { "type": "number" }
            },
            "required": ["number", "seller", "buyer", "items", "currency", "total"]
          }
        },
        "required": ["invoiceData"]
      },
      "InvoiceCreateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "invoiceUrl": { "type": "string", "description": "Visual HTML rendering URL of invoice sheet" },
          "pdfUrl": { "type": "string", "description": "Download URL of the ZUGFeRD PDF invoice" },
          "invoiceNumber": { "type": "string" },
          "total": { "type": "number" },
          "currency": { "type": "string" }
        }
      },
      "PlayableAdsZipRequest": {
        "type": "object",
        "properties": {
          "htmlContent": {
            "type": "string",
            "description": "Full source code HTML structure of visual ad page"
          },
          "brandName": {
            "type": "string",
            "description": "Target client brand name"
          }
        },
        "required": ["htmlContent"]
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "status": { "type": "integer" },
          "message": { "type": "string" },
          "expectedSchema": { "type": "object" },
          "validationErrors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": { "type": "string" },
                "message": { "type": "string" }
              }
            }
          },
          "llm_instruction": { "type": "string" }
        }
      },
      "PaymentRequiredResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "example": "Payment Required" },
          "status": { "type": "integer", "example": 402 },
          "message": { "type": "string", "example": "This premium API endpoint requires a micropayment of 1.99 USDC." },
          "solana": {
            "type": "object",
            "properties": {
              "address": { "type": "string", "example": "GPyvv7eQqyaeu9cnqseE33xtyQjgKxeAevfBmFpdztjB" },
              "reference": { "type": "string", "example": "SOLANA_MOCK_REF_A1B2C3D4E5F6" },
              "pay_url": { "type": "string", "example": "solana:GPyvv7eQqyaeu9cnqseE33xtyQjgKxeAevfBmFpdztjB?amount=1.99&reference=SOLANA_MOCK_REF_A1B2C3D4E5F6" },
              "is_mock": { "type": "boolean", "example": true }
            }
          },
          "verify_url": { "type": "string", "example": "https://api.pixeloffice.eu/api/pay/verify-crypto" }
        }
      },
      "PayRequestResponse": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "amount_usd": { "type": "number" },
          "solana": {
            "type": "object",
            "properties": {
              "address": { "type": "string" },
              "reference": { "type": "string" },
              "pay_url": { "type": "string" }
            }
          },
          "lightning": {
            "type": "object",
            "properties": {
              "invoice": { "type": "string" },
              "payment_hash": { "type": "string" }
            }
          },
          "verify_url": { "type": "string" }
        }
      }
    }
  }
}