{
  "openapi": "3.1.0",
  "info": {
    "title": "Pixelixe API",
    "version": "2.0.0",
    "description": "The Pixelixe API allows developers to search and manage design documents, automate image generation from templates, and apply filters and processing operations to images over HTTP.",
    "termsOfService": "https://pixelixe.com/terms.html",
    "contact": {
      "name": "Pixelixe API Support",
      "url": "https://pixelixe.com/docs/v2/",
      "email": "inquiries@pixelixe.com"
    },
    "license": {
      "name": "Commercial License",
      "url": "https://pixelixe.com/terms.html"
    }
  },
  "servers": [
    {
      "url": "https://studio.pixelixe.com",
      "description": "Production server"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Your Pixelixe API key, prefixed with 'Bearer '. Example: 'Authorization: Bearer YOUR_API_KEY'."
      }
    },
    "schemas": {
      "AuthResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "message": {
            "type": "string",
            "example": "Authenticated successfully"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "error"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "DocumentSearchResponse": {
        "type": "object",
        "properties": {
          "api_key": {
            "type": "string"
          },
          "documents": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "Document summary (name, width, height, document_uid, urls, available_modifications, etc.)",
              "additionalProperties": true
            }
          }
        }
      },
      "AutomationModification": {
        "type": "object",
        "description": "One modification to apply to a template element.",
        "properties": {
          "element_name": {
            "type": "string"
          },
          "image_url": {
            "type": "string",
            "format": "uri"
          },
          "type": {
            "type": "string",
            "description": "text | shape | icon | image"
          },
          "color": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "background-color": {
            "type": "string"
          },
          "border-color": {
            "type": "string"
          },
          "border-size": {
            "type": "string"
          },
          "font-family": {
            "type": "string"
          },
          "font-size": {
            "type": "string"
          },
          "text-align": {
            "type": "string"
          },
          "width": {
            "type": "string"
          },
          "height": {
            "type": "string"
          },
          "visible": {
            "type": "string",
            "description": "true | false"
          },
          "shape": {
            "type": "string"
          }
        },
        "required": ["element_name"]
      },
      "AutomationRequest": {
        "type": "object",
        "description": "JSON payload for the Image Automation API.",
        "properties": {
          "document_uid": {
            "type": "string",
            "description": "UID of the Document to use as template."
          },
          "template_name": {
            "type": "string",
            "description": "Name of the Document to use as template."
          },
          "api_key": {
            "type": "string",
            "description": "Your API key (same value as Authorization header)."
          },
          "format": {
            "type": "string",
            "description": "Expected output format.",
            "enum": ["image", "json", "base64", "pdf", "html"],
            "default": "image"
          },
          "image_type": {
            "type": "string",
            "description": "Output image type.",
            "enum": ["jpeg", "png"],
            "default": "png"
          },
          "custom_field": {
            "type": "string",
            "description": "Optional field returned in JSON response when format=json or html."
          },
          "modifications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AutomationModification"
            }
          }
        },
        "required": ["api_key"]
      },
      "AutomationJsonResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "created_at": {
            "type": "string"
          },
          "image_url": {
            "type": "string",
            "format": "uri"
          },
          "uid": {
            "type": "string"
          },
          "custom_field": {
            "type": "string"
          }
        }
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/api/authentication/v2": {
      "get": {
        "tags": ["Authentication"],
        "summary": "Test API key",
        "description": "Check whether your Pixelixe API key is valid.",
        "operationId": "testAuthentication",
        "responses": {
          "200": {
            "description": "Authentication succeeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/document/search/v2": {
      "get": {
        "tags": ["Editor API"],
        "summary": "Search documents",
        "description": "Retrieve all Documents attached to your Pixelixe account, or filter by document, user or size.",
        "operationId": "searchDocuments",
        "parameters": [
          {
            "name": "user_uid",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Unique user identifier to filter documents created by this user."
          },
          {
            "name": "document_uid",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Unique Document identifier to retrieve a specific document."
          },
          {
            "name": "created_by",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["owner", "api-editor"]
            },
            "description": "Filter by who created the document: account owner or API editor users."
          },
          {
            "name": "width",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Filter documents by width (pixels)."
          },
          {
            "name": "height",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Filter documents by height (pixels)."
          },
          {
            "name": "folder_path",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter documents in a specific folder."
          }
        ],
        "responses": {
          "200": {
            "description": "List of documents",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentSearchResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/graphic/automation/v2": {
      "post": {
        "tags": ["Image Automation"],
        "summary": "Generate an image from a template (Image Automation API)",
        "description": "Generate images such as social media visuals, banners and more from a saved Document template. You can change text, colors, images and other properties in one request.",
        "operationId": "imageAutomation",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AutomationRequest"
              },
              "example": {
                "document_uid": "32f59312815640e186cf17fe3fd5c1d9",
                "api_key": "YOUR_API_KEY",
                "format": "json",
                "image_type": "png",
                "custom_field": "INTERNAL_REFERENCE_123",
                "modifications": [
                  {
                    "element_name": "background-image",
                    "image_url": "https://any-website.com/img/any-image.jpg",
                    "width": "cover",
                    "height": "cover",
                    "visible": "true"
                  },
                  {
                    "element_name": "text-0",
                    "type": "text",
                    "text": "Enter custom text here",
                    "color": "red",
                    "font-size": "12px",
                    "visible": "true"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Image generated successfully. Response format depends on the 'format' parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationJsonResponse"
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "description": "Raw PNG image stream when format=image or base64."
                }
              },
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "description": "Raw PDF stream when format=pdf."
                }
              }
            }
          },
          "400": {
            "description": "Bad request or invalid JSON payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/photo/effect/v2": {
      "get": {
        "tags": ["Image Filters"],
        "summary": "Apply filters and photo effects",
        "description": "Apply built-in presets (Clarendon, Hefe, Lofi, Moon, Ludwig, Inkwell) or advanced photo effects (brighten, saturate, contrast, etc.) to an image.",
        "operationId": "photoEffect",
        "parameters": [
          {
            "name": "preset",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["clarendon", "hefe", "lofi", "moon", "ludwig", "inkwell"]
            },
            "description": "Optional preset filter to apply."
          },
          {
            "name": "imageUrl",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Public URL of the image to transform (jpeg, png, bmp, tiff or gif). Use URL-encoded value."
          },
          {
            "name": "imageType",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["png", "jpeg", "bmp"],
              "default": "png"
            },
            "description": "Output image type (png by default)."
          },
          {
            "name": "brighten",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Brighten amount, 0–100."
          },
          {
            "name": "darken",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Darken amount, 0–100."
          },
          {
            "name": "saturate",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Saturate amount, 0–100."
          },
          {
            "name": "desaturate",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Desaturate amount, 0–100."
          },
          {
            "name": "contrast",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Contrast adjustment, -1 to +1."
          },
          {
            "name": "opacity",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Opacity factor, 0–1."
          }
        ],
        "responses": {
          "200": {
            "description": "Filtered image returned as a binary stream.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}