{
  "openapi": "3.0.3",
  "info": {
    "title": "AICommerce WP REST API",
    "description": "REST API for the AICommerce WP plugin. Makes WooCommerce stores discoverable by AI agents through structured data, feeds, and crawler management.\n",
    "version": "1.0.0",
    "contact": {
      "name": "Tyralix Support",
      "url": "https://tyralix.com"
    },
    "license": {
      "name": "GPL-2.0-or-later",
      "url": "https://www.gnu.org/licenses/gpl-2.0.html"
    }
  },
  "servers": [
    {
      "url": "/wp-json/aicommerce/v1",
      "description": "WordPress REST API namespace"
    }
  ],
  "tags": [
    {
      "name": "Public",
      "description": "Unauthenticated endpoints"
    },
    {
      "name": "Score",
      "description": "AI Readiness Score endpoints"
    },
    {
      "name": "Schema",
      "description": "JSON-LD schema endpoints"
    },
    {
      "name": "Settings",
      "description": "Plugin settings management"
    },
    {
      "name": "Feeds",
      "description": "Feed generation and monitoring (Pro)"
    },
    {
      "name": "Crawler",
      "description": "Crawler monitoring and rules (Pro)"
    },
    {
      "name": "Onboarding",
      "description": "Setup wizard"
    }
  ],
  "components": {
    "securitySchemes": {
      "cookieAuth": {
        "type": "apiKey",
        "in": "cookie",
        "name": "wordpress_logged_in"
      },
      "nonceAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-WP-Nonce"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "example": "not_found"
          },
          "message": {
            "type": "string",
            "example": "Product not found."
          },
          "data": {
            "type": "object",
            "properties": {
              "status": {
                "type": "integer",
                "example": 404
              }
            }
          }
        }
      },
      "ScoreResult": {
        "type": "object",
        "properties": {
          "overall": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "example": 85
          },
          "grade": {
            "type": "string",
            "enum": [
              "A+",
              "A",
              "B",
              "C",
              "D",
              "F"
            ],
            "example": "A"
          },
          "breakdown": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "from_cache": {
            "type": "boolean"
          }
        }
      },
      "StoreScore": {
        "type": "object",
        "properties": {
          "overall_score": {
            "type": "integer",
            "example": 82
          },
          "grade": {
            "type": "string",
            "example": "A"
          },
          "product_count": {
            "type": "integer",
            "example": 150
          },
          "issues": {
            "type": "integer",
            "description": "Products scoring below 70",
            "example": 12
          }
        }
      },
      "Settings": {
        "type": "object",
        "properties": {
          "schema_enabled": {
            "type": "boolean"
          },
          "conflict_suppress": {
            "type": "boolean"
          },
          "default_brand": {
            "type": "string"
          },
          "same_as_links": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          }
        }
      },
      "FeedInfo": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "example": "google"
          },
          "name": {
            "type": "string",
            "example": "Google Shopping Feed"
          },
          "extension": {
            "type": "string",
            "example": "xml"
          },
          "filename": {
            "type": "string",
            "example": "google-feed.xml"
          }
        }
      }
    },
    "parameters": {
      "ProductId": {
        "name": "product_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "minimum": 1
        },
        "description": "WooCommerce product ID"
      },
      "FeedType": {
        "name": "type",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^[a-z]+$"
        },
        "description": "Feed type slug (google, openai, bing, perplexity)"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "description": "Maximum requests per window",
        "schema": {
          "type": "integer",
          "example": 60
        }
      },
      "X-RateLimit-Remaining": {
        "description": "Remaining requests in current window",
        "schema": {
          "type": "integer",
          "example": 57
        }
      },
      "X-RateLimit-Reset": {
        "description": "Unix timestamp when the window resets",
        "schema": {
          "type": "integer"
        }
      }
    }
  },
  "security": [
    {
      "cookieAuth": [],
      "nonceAuth": []
    }
  ],
  "paths": {
    "/status": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "Health check",
        "description": "Returns plugin version, active modules, and environment info.",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plugin_version": {
                      "type": "string",
                      "example": "1.0.0"
                    },
                    "modules": {
                      "type": "object",
                      "properties": {
                        "schema": {
                          "type": "boolean"
                        },
                        "feeds": {
                          "type": "boolean"
                        },
                        "crawler": {
                          "type": "boolean"
                        }
                      }
                    },
                    "wp_version": {
                      "type": "string"
                    },
                    "wc_version": {
                      "type": "string",
                      "nullable": true
                    },
                    "php_version": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/manifest": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "AI commerce manifest",
        "description": "Returns the /.well-known/ai-commerce.json manifest data.",
        "security": [],
        "responses": {
          "200": {
            "description": "Manifest data"
          },
          "404": {
            "description": "Manifest not available",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/openapi": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "OpenAPI specification",
        "description": "Returns this OpenAPI spec as JSON (or YAML fallback).",
        "security": [],
        "responses": {
          "200": {
            "description": "OpenAPI spec"
          },
          "404": {
            "description": "Spec file not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/score": {
      "get": {
        "tags": [
          "Score"
        ],
        "summary": "Store-level AI readiness score",
        "description": "Aggregate score across all products.",
        "responses": {
          "200": {
            "description": "Store score",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreScore"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/score/{product_id}": {
      "get": {
        "tags": [
          "Score"
        ],
        "summary": "Product AI readiness score",
        "description": "Returns cached score or calculates a fresh one.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProductId"
          },
          {
            "name": "force",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Skip cache and recalculate"
          }
        ],
        "responses": {
          "200": {
            "description": "Score result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScoreResult"
                }
              }
            }
          },
          "404": {
            "description": "Product not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/score/refresh": {
      "post": {
        "tags": [
          "Score"
        ],
        "summary": "Refresh all product scores",
        "description": "Clears the score cache and schedules async recalculation.",
        "responses": {
          "200": {
            "description": "Refresh scheduled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/score/batch": {
      "post": {
        "tags": [
          "Score"
        ],
        "summary": "Batch score lookup",
        "description": "Get scores for up to 100 products in one request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "product_ids"
                ],
                "properties": {
                  "product_ids": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    },
                    "maxItems": 100,
                    "example": [
                      42,
                      43,
                      44
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch results keyed by product ID",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "$ref": "#/components/schemas/ScoreResult"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Batch too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/schema/{product_id}": {
      "get": {
        "tags": [
          "Schema"
        ],
        "summary": "Preview product schema",
        "description": "Returns the generated JSON-LD schema objects for a product.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProductId"
          }
        ],
        "responses": {
          "200": {
            "description": "Schema preview",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "product_id": {
                      "type": "integer"
                    },
                    "schemas": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Product not found"
          }
        }
      }
    },
    "/validate/{product_id}": {
      "get": {
        "tags": [
          "Schema"
        ],
        "summary": "Validate product schema",
        "description": "Runs validation checks on the generated schema.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProductId"
          }
        ],
        "responses": {
          "200": {
            "description": "Validation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "product_id": {
                      "type": "integer"
                    },
                    "validation": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Product not found"
          }
        }
      }
    },
    "/settings": {
      "get": {
        "tags": [
          "Settings"
        ],
        "summary": "Get plugin settings",
        "responses": {
          "200": {
            "description": "Current settings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Settings"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Settings"
        ],
        "summary": "Update plugin settings",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Settings"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Settings saved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "updated": {
                      "$ref": "#/components/schemas/Settings"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/feeds": {
      "get": {
        "tags": [
          "Feeds"
        ],
        "summary": "List registered feed formats",
        "responses": {
          "200": {
            "description": "Feed list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "feeds": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FeedInfo"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/feeds/generate": {
      "post": {
        "tags": [
          "Feeds"
        ],
        "summary": "Trigger feed generation",
        "description": "Schedules async generation of all feeds. Requires Pro.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "force": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Generation scheduled"
          },
          "403": {
            "description": "Pro required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/feeds/status": {
      "get": {
        "tags": [
          "Feeds"
        ],
        "summary": "Feed generation status",
        "responses": {
          "200": {
            "description": "Status of all feeds"
          }
        }
      }
    },
    "/feeds/{type}/regenerate": {
      "post": {
        "tags": [
          "Feeds"
        ],
        "summary": "Regenerate a specific feed",
        "description": "Requires Pro license.",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeedType"
          }
        ],
        "responses": {
          "202": {
            "description": "Regeneration scheduled"
          },
          "403": {
            "description": "Pro required"
          },
          "404": {
            "description": "Feed type not found"
          }
        }
      }
    },
    "/feeds/{type}/health": {
      "get": {
        "tags": [
          "Feeds"
        ],
        "summary": "Feed health check",
        "description": "Validates feed file integrity. Requires Pro.",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeedType"
          }
        ],
        "responses": {
          "200": {
            "description": "Health report"
          },
          "403": {
            "description": "Pro required"
          },
          "404": {
            "description": "Feed type not found"
          }
        }
      }
    },
    "/crawler/logs": {
      "get": {
        "tags": [
          "Crawler"
        ],
        "summary": "Get crawler visit logs",
        "description": "Requires Pro license.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Log entries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "logs": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Pro required"
          }
        }
      }
    },
    "/crawler/stats": {
      "get": {
        "tags": [
          "Crawler"
        ],
        "summary": "Crawler visit statistics",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Statistics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stats": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/crawler/rules": {
      "get": {
        "tags": [
          "Crawler"
        ],
        "summary": "Get crawler rules",
        "responses": {
          "200": {
            "description": "Current rules and blocked bots",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rules": {
                      "type": "object"
                    },
                    "blocked_bots": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Crawler"
        ],
        "summary": "Update crawler rules",
        "description": "Block/unblock bots or update robots.txt rules. Requires Pro.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "block_bot": {
                    "type": "string",
                    "description": "Bot family to block"
                  },
                  "unblock_bot": {
                    "type": "string",
                    "description": "Bot family to unblock"
                  },
                  "bot_name": {
                    "type": "string",
                    "description": "Bot user-agent name for robots rule"
                  },
                  "allow": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "disallow": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rules updated"
          },
          "403": {
            "description": "Pro required"
          }
        }
      }
    },
    "/onboarding/complete": {
      "post": {
        "tags": [
          "Onboarding"
        ],
        "summary": "Mark onboarding complete",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}