{
  "openapi": "3.1.0",
  "info": {
    "title": "LVL Agent Commerce API",
    "version": "1.0.0",
    "description": "Discover catalog, quote merch, create agent orders, verify payment, and fulfill via Printify POD. Cheaper shortcut than building POD from scratch.",
    "contact": {
      "url": "https://factory.lvlltd.com"
    }
  },
  "servers": [
    {
      "url": "https://factory.lvlltd.com"
    }
  ],
  "paths": {
    "/api/agent/card": {
      "get": {
        "summary": "Agent capability card",
        "operationId": "getAgentCard",
        "responses": {
          "200": {
            "description": "Capability card JSON"
          }
        }
      }
    },
    "/api/store/catalog": {
      "get": {
        "summary": "Merch catalog + agent block",
        "operationId": "getCatalog",
        "responses": {
          "200": {
            "description": "Catalog"
          }
        }
      }
    },
    "/api/agent/quote": {
      "post": {
        "summary": "Quote a SKU (face + $0.50 agent fee)",
        "operationId": "createQuote",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sku"
                ],
                "properties": {
                  "sku": {
                    "type": "string"
                  },
                  "quantity": {
                    "type": "integer",
                    "default": 1
                  },
                  "size": {
                    "type": "string",
                    "default": "M"
                  },
                  "country": {
                    "type": "string",
                    "default": "US"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote"
          }
        }
      }
    },
    "/api/agent/orders": {
      "post": {
        "summary": "Create agent order (idempotent with external_ref)",
        "operationId": "createOrder",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sku",
                  "ship_to"
                ],
                "properties": {
                  "sku": {
                    "type": "string"
                  },
                  "quantity": {
                    "type": "integer"
                  },
                  "size": {
                    "type": "string"
                  },
                  "variant_id": {
                    "type": "integer"
                  },
                  "buyer_ref": {
                    "type": "string"
                  },
                  "external_ref": {
                    "type": "string"
                  },
                  "rail": {
                    "type": "string"
                  },
                  "ship_to": {
                    "type": "object",
                    "required": [
                      "first_name",
                      "last_name",
                      "email",
                      "country",
                      "region",
                      "address1",
                      "city",
                      "zip"
                    ],
                    "properties": {
                      "first_name": {
                        "type": "string"
                      },
                      "last_name": {
                        "type": "string"
                      },
                      "email": {
                        "type": "string"
                      },
                      "phone": {
                        "type": "string"
                      },
                      "country": {
                        "type": "string"
                      },
                      "region": {
                        "type": "string"
                      },
                      "address1": {
                        "type": "string"
                      },
                      "address2": {
                        "type": "string"
                      },
                      "city": {
                        "type": "string"
                      },
                      "zip": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order created"
          },
          "404": {
            "description": "SKU not found"
          }
        }
      }
    },
    "/api/agent/orders/{id}": {
      "get": {
        "summary": "Get order status",
        "operationId": "getOrder",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order"
          }
        }
      }
    },
    "/api/agent/orders/{id}/pay": {
      "post": {
        "summary": "Verify payment and submit Printify fulfillment",
        "operationId": "payAndFulfill",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "method": {
                    "type": "string",
                    "enum": [
                      "crypto",
                      "demo",
                      "stripe"
                    ]
                  },
                  "tx_hash": {
                    "type": "string"
                  },
                  "rail": {
                    "type": "string"
                  },
                  "confirm": {
                    "type": "boolean"
                  },
                  "stripe_session_id": {
                    "type": "string"
                  },
                  "force_simulate_printify": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Paid + fulfillment result"
          }
        }
      }
    },
    "/api/agent/status": {
      "get": {
        "summary": "Agent health + Printify readiness",
        "operationId": "agentStatus",
        "responses": {
          "200": {
            "description": "Status"
          }
        }
      }
    },
    "/api/agent/design": {
      "post": {
        "summary": "Create design brief ticket (creative workflow)",
        "operationId": "agentDesign",
        "responses": {
          "201": {
            "description": "Design package"
          }
        }
      }
    },
    "/api/pay/options": {
      "get": {
        "summary": "Multi-rail settlement options",
        "operationId": "payOptions",
        "responses": {
          "200": {
            "description": "Rails"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "summary": "LLM discovery document",
        "operationId": "llmsTxt",
        "responses": {
          "200": {
            "description": "text/plain"
          }
        }
      }
    },
    "/well-known/agent.json": {
      "get": {
        "summary": "Well-known agent card (app route)",
        "operationId": "wellKnownAgentApp",
        "responses": {
          "200": {
            "description": "JSON"
          }
        }
      }
    },
    "/.well-known/agent.json": {
      "get": {
        "summary": "Well-known agent card",
        "operationId": "wellKnownAgent",
        "responses": {
          "200": {
            "description": "JSON"
          }
        }
      }
    }
  }
}