{
  "openapi": "3.1.0",
  "info": {
    "title": "DEPICTR Platform & Agent API",
    "version": "1.0.0",
    "description": "Autonomous agent and programmatic developer API for the DEPICTR Website as a Service platform. Enables subdomain verification, showcase exploration, menu extraction, and site lifecycle management. API Versioning: Major API revisions follow URI path versioning (/v1/). Backward-compatible enhancements occur with semantic minor releases. Deprecation Policy: Deprecated operations signal deprecation via the RFC 8594 Sunset and Deprecation headers at least 90 days before decommission.",
    "contact": {
      "name": "DEPICTR Developer Support",
      "email": "support@depictr.app",
      "url": "https://depictr.app/developers"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://depictr.app/terms"
    }
  },
  "servers": [
    {
      "url": "https://depictr.app",
      "description": "Primary Production Edge Network (v1)"
    }
  ],
  "paths": {
    "/api/check-subdomain": {
      "get": {
        "operationId": "checkSubdomainAvailability",
        "summary": "Check Subdomain Availability",
        "description": "Inspect whether a specified subdomain prefix on *.depictr.app is available for a new website registration or already claimed.",
        "parameters": [
          {
            "name": "subdomain",
            "in": "query",
            "required": true,
            "description": "The subdomain slug to verify (lowercase alphanumeric and hyphens).",
            "schema": {
              "type": "string",
              "example": "cupidspizzeria"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Subdomain availability verification status.",
            "headers": {
              "RateLimit-Limit": {
                "schema": {
                  "type": "integer",
                  "example": 120
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer",
                  "example": 119
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "available": {
                      "type": "boolean",
                      "example": true
                    },
                    "subdomain": {
                      "type": "string",
                      "example": "cupidspizzeria"
                    }
                  },
                  "required": [
                    "available"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request: Invalid or missing parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests: Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/showcase-sites": {
      "get": {
        "operationId": "listShowcaseSites",
        "summary": "List Showcase Websites",
        "description": "Retrieve a curated catalog of active, published websites built with DEPICTR across hospitality, trades, and retail.",
        "responses": {
          "200": {
            "description": "Array of published website records and metadata.",
            "headers": {
              "RateLimit-Limit": {
                "schema": {
                  "type": "integer",
                  "example": 120
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer",
                  "example": 119
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "sites": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "subdomain": {
                            "type": "string",
                            "example": "cupidspizzeria"
                          },
                          "name": {
                            "type": "string",
                            "example": "Cupid's Pizzeria"
                          },
                          "category": {
                            "type": "string",
                            "example": "restaurant"
                          },
                          "liveUrl": {
                            "type": "string",
                            "example": "https://cupidspizzeria.depictr.app"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/scrape-menu": {
      "post": {
        "operationId": "scrapeOnlineMenu",
        "summary": "Scrape and Normalize Online Restaurant Menu",
        "description": "Extract menu sections, items, and pricing from an external web URL (such as an Uber Eats store or website) into DEPICTR format.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://order.online/store/restaurant-123"
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted and structured menu items.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "menu": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request: Invalid or missing URL.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error processing menu scrape.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "description": "Standard typed error model across all DEPICTR REST endpoints.",
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable explanation of the error condition.",
            "example": "Rate limit exceeded. Please throttle requests."
          },
          "code": {
            "type": "string",
            "description": "Machine-readable standardized error code.",
            "example": "RATE_LIMIT_EXCEEDED"
          },
          "hint": {
            "type": "string",
            "description": "Actionable resolution guidance for client agents.",
            "example": "Wait until the Retry-After interval elapses before retrying."
          }
        },
        "required": [
          "error",
          "code"
        ]
      },
      "ProblemDetails": {
        "type": "object",
        "description": "RFC 9457 Problem Details for HTTP APIs.",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "A URI reference that identifies the problem type.",
            "example": "https://depictr.app/developers#errors"
          },
          "title": {
            "type": "string",
            "description": "Short human-readable summary of problem type.",
            "example": "Invalid Request Parameter"
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code.",
            "example": 400
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation specific to this occurrence.",
            "example": "Missing or invalid subdomain query parameter."
          },
          "instance": {
            "type": "string",
            "format": "uri",
            "description": "A URI reference identifying the specific occurrence.",
            "example": "/api/check-subdomain"
          }
        },
        "required": [
          "type",
          "title",
          "status"
        ]
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Standard session token or API key for protected DEPICTR operations."
      }
    }
  }
}