{
  "openapi": "3.1.0",
  "info": {
    "title": "Agentic Gift Shop Agent API",
    "version": "0.1.3",
    "description": "Authenticated API for approved agents to browse products, create personalization previews, build carts, create WooCommerce orders, generate hosted payment links, and track fulfillment. Product image objects include public messaging_src URLs that can be fetched by messaging platforms without API auth."
  },
  "servers": [
    {
      "url": "https://store.agenticgiftshop.com/wp-json/agentic-gift-shop/v1/agent"
    }
  ],
  "components": {
    "securitySchemes": {
      "AgentBearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "AGS agent API token"
      }
    },
    "schemas": {
      "EditorState": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "activePrintArea": { "type": "string" },
          "layers": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/EditorLayer" }
          }
        }
      },
      "EditorLayer": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "type": { "type": "string", "enum": ["text", "image"] },
          "text": { "type": "string" },
          "attachment_id": { "type": "integer" },
          "x": { "type": "number", "minimum": 0, "maximum": 1 },
          "y": { "type": "number", "minimum": 0, "maximum": 1 },
          "width": { "type": "number", "minimum": 0, "maximum": 1 },
          "height": { "type": "number", "minimum": 0, "maximum": 1 },
          "rotation": { "type": "number", "minimum": -180, "maximum": 180 },
          "font": { "type": "string" },
          "fontSize": { "type": "number" },
          "color": { "type": "string" },
          "align": { "type": "string", "enum": ["left", "center", "right"] },
          "removeBackground": { "type": "boolean" }
        },
        "required": ["type"]
      },
      "PersonalizationRequest": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "options": {
            "type": "object",
            "description": "Product options such as color and size. Use values from product.personalization.options."
          },
          "print_area": {
            "type": "string",
            "description": "A valid value from product.personalization.print_areas."
          },
          "editor_state": { "$ref": "#/components/schemas/EditorState" },
          "recipient_name": { "type": "string" },
          "gift_message": { "type": "string" },
          "design_notes": { "type": "string" },
          "reference_image_id": { "type": "integer" },
          "client_preview_url": { "type": "string", "format": "uri" }
        }
      },
      "Address": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "email": { "type": "string", "format": "email" },
          "phone": { "type": "string" },
          "first_name": { "type": "string" },
          "last_name": { "type": "string" },
          "company": { "type": "string" },
          "address_1": { "type": "string" },
          "address_2": { "type": "string" },
          "city": { "type": "string" },
          "state": { "type": "string" },
          "postcode": { "type": "string" },
          "country": { "type": "string" }
        }
      }
    }
  },
  "security": [
    {
      "AgentBearerAuth": []
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "security": [],
        "responses": {
          "200": { "description": "Service health" }
        }
      }
    },
    "/auth/whoami": {
      "get": {
        "summary": "Inspect the current API key",
        "responses": {
          "200": { "description": "Key metadata and scopes" },
          "401": { "description": "Missing or invalid token" }
        }
      }
    },
    "/products": {
      "get": {
        "summary": "List products",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }
        ],
        "responses": {
          "200": { "description": "Product list" }
        }
      }
    },
    "/public-images/{encoded}/{signature}.jpg": {
      "get": {
        "summary": "Public messaging-safe product image proxy",
        "security": [],
        "parameters": [
          { "name": "encoded", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "signature", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Public image file for messaging platforms",
            "content": {
              "image/jpeg": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          },
          "403": { "description": "Invalid signature" }
        }
      }
    },
    "/products/{product_id}": {
      "get": {
        "summary": "Get product detail, personalization schema, variants, sizing, supplier data, and agent workflow",
        "parameters": [
          { "name": "product_id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Product detail" },
          "404": { "description": "Product not found" }
        }
      }
    },
    "/products/{product_id}/personalization/preview": {
      "post": {
        "summary": "Generate a customer-shareable personalized preview image",
        "parameters": [
          { "name": "product_id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PersonalizationRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Preview URL and normalized personalization state" },
          "400": { "description": "Invalid options or editor state" }
        }
      }
    },
    "/media": {
      "post": {
        "summary": "Upload a customer image for personalization layers",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "filename": { "type": "string" },
                  "mime_type": { "type": "string", "enum": ["image/jpeg", "image/png", "image/webp"] },
                  "data": { "type": "string", "description": "Base64 image data, optionally as a data URL." }
                },
                "required": ["filename", "data"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Media attachment id and URL" }
        }
      }
    },
    "/carts": {
      "post": {
        "summary": "Create an agent cart",
        "responses": {
          "200": { "description": "Cart" }
        }
      }
    },
    "/carts/{cart_id}": {
      "get": {
        "summary": "Get cart",
        "parameters": [
          { "name": "cart_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Cart" },
          "404": { "description": "Cart not found" }
        }
      },
      "patch": {
        "summary": "Update cart customer or metadata",
        "parameters": [
          { "name": "cart_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Updated cart" }
        }
      }
    },
    "/carts/{cart_id}/items": {
      "post": {
        "summary": "Add a personalized item to a cart",
        "parameters": [
          { "name": "cart_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  { "$ref": "#/components/schemas/PersonalizationRequest" },
                  {
                    "type": "object",
                    "properties": {
                      "product_id": { "type": "integer" },
                      "quantity": { "type": "integer", "minimum": 1 }
                    },
                    "required": ["product_id", "quantity"]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated cart" }
        }
      }
    },
    "/carts/{cart_id}/items/{item_id}": {
      "patch": {
        "summary": "Update cart item",
        "parameters": [
          { "name": "cart_id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Updated cart" }
        }
      },
      "delete": {
        "summary": "Remove cart item",
        "parameters": [
          { "name": "cart_id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Updated cart" }
        }
      }
    },
    "/carts/{cart_id}/order": {
      "post": {
        "summary": "Create WooCommerce order and hosted payment URL from cart",
        "parameters": [
          { "name": "cart_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "billing": { "$ref": "#/components/schemas/Address" },
                  "shipping": { "$ref": "#/components/schemas/Address" }
                },
                "required": ["billing"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Order and payment URL" }
        }
      }
    },
    "/orders/{order_id}": {
      "get": {
        "summary": "Get order, payment, fulfillment, and shipment status",
        "parameters": [
          { "name": "order_id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Order detail" }
        }
      }
    },
    "/orders/{order_id}/payment-link": {
      "post": {
        "summary": "Get or refresh hosted payment URL",
        "parameters": [
          { "name": "order_id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Payment link" }
        }
      }
    },
    "/orders/{order_id}/fulfillment/refresh": {
      "post": {
        "summary": "Refresh Printify fulfillment status",
        "parameters": [
          { "name": "order_id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Refreshed order and supplier status" }
        }
      }
    }
  }
}