{
  "openapi": "3.1.0",
  "info": {
    "title": "Claudiverse Tanks API",
    "version": "1.0.0",
    "summary": "Parametric stainless-steel tank quotes, CAD artifacts, and order capture for AI agents.",
    "description": "Instant quotes, CAD artifacts (STEP/STL/DXF), and order capture for custom 304-stainless rectangular tanks. Every price returned by this API is a NON-BINDING ESTIMATE: final price and lead time are confirmed by a human before any payment is requested. No payment is processed through this API. Register self-serve at POST /api/agents/register; docs at https://claudiverse.cc/auth.md; a remote MCP server with the same capabilities is at https://claudiverse.cc/mcp (Streamable HTTP).",
    "contact": {
      "name": "Claudiverse operator (abuse / revocation / higher volume)",
      "email": "abuse@claudiverse.cc"
    },
    "license": {
      "name": "Proprietary — API offered as-is; quotes are non-binding estimates",
      "url": "https://claudiverse.cc/auth.md"
    }
  },
  "servers": [{ "url": "https://claudiverse.cc" }],
  "paths": {
    "/api/agents/register": {
      "post": {
        "operationId": "registerAgent",
        "summary": "Register a new agent (free, self-serve)",
        "security": [{}],
        "description": "Returns an agent_id and a bearer token shown exactly once; only the token's SHA-256 hash is stored. Max 10 registrations per IP per UTC day.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/RegisterRequest" },
              "example": {
                "name": "my-agent",
                "contact_email": "operator@example.com",
                "description": "quotes tanks for an irrigation startup"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent created; token shown once.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RegisterResponse" },
                "example": {
                  "agent_id": "agt_6428a461cff7",
                  "token": "cv_<48 hex — shown only once>",
                  "scopes": ["quote:read", "cad:read", "order:create"],
                  "rate_limits": { "quotes_per_day": 200, "orders_per_day": 20 },
                  "docs": "https://claudiverse.cc/auth.md",
                  "note": "Store this token now; it is shown only once."
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/agents/me": {
      "get": {
        "operationId": "getMe",
        "summary": "Verify your token and see today's usage",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Token is valid.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MeResponse" },
                "example": {
                  "agent_id": "agt_6428a461cff7",
                  "name": "my-agent",
                  "scopes": ["quote:read", "cad:read", "order:create"],
                  "usage_today": { "quotes": 1, "orders": 0 },
                  "rate_limits": { "quotes_per_day": 200, "orders_per_day": 20 }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/tanks/catalog": {
      "get": {
        "operationId": "getCatalog",
        "summary": "Product catalog + coordinate convention",
        "description": "Faces, FPT fitting sizes, dimension limits, material, baffle rules, and the coordinate convention for fitting X/Y placement. Read this before placing fittings in a quote. Public; sending an invalid bearer token returns 401.",
        "security": [{}, { "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Catalog.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Catalog" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/tanks/quote": {
      "post": {
        "operationId": "getQuote",
        "summary": "Instant quote + CAD artifact links",
        "description": "Public (no auth required). If a valid bearer token is sent, usage is attributed to your agent and the 200 quotes/day limit applies. price_usd is a non-binding estimate. Artifact paths are relative to https://claudiverse.cc.",
        "security": [{}, { "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/QuoteRequest" },
              "example": {
                "length": 24,
                "width": 12,
                "height": 18,
                "fittings": [{ "face": "top", "size": "2", "x": 18, "y": 7 }]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote with price breakdown, capacity, and artifact links.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/QuoteResponse" },
                "example": {
                  "calibrated": true,
                  "currency": "USD",
                  "dimensions_in": { "length": 24.0, "width": 12.0, "height": 18.0 },
                  "wall_in": 0.075,
                  "metrics_mm": {
                    "material_area_mm2": 1197316.96,
                    "cut_length_mm": 11109.96,
                    "weld_length_mm": 5486.4,
                    "baffles": 0,
                    "n_blanks": 6
                  },
                  "breakdown_usd": {
                    "material": 458.57,
                    "cutting": 164.43,
                    "scs_setup": 47.46,
                    "welding": 274.32,
                    "handling": 25.0,
                    "fittings": 40.31,
                    "subtotal": 1010.09,
                    "margin_pct": 0.35
                  },
                  "price_usd": 1363.62,
                  "note": "SCS material/cut/setup calibrated (304 SS, 14 ga); weld, handling, and margin are shop estimates.",
                  "capacity": { "gallons": 21.84, "liters": 82.67 },
                  "fittings": [
                    { "face": "top", "size": "2", "label": "2\" FPT", "x": 18.0, "y": 7.0 }
                  ],
                  "baffles": 0,
                  "artifacts": {
                    "step": "/api/tanks/artifact/aca7a636649b/tank.step",
                    "stl": "/api/tanks/artifact/aca7a636649b/tank.stl",
                    "quote_json": "/api/tanks/artifact/aca7a636649b/quote.json",
                    "manifest_csv": "/api/tanks/artifact/aca7a636649b/flats/manifest.csv",
                    "blanks": [
                      "/api/tanks/artifact/aca7a636649b/flats/top.dxf",
                      "/api/tanks/artifact/aca7a636649b/flats/bottom.dxf",
                      "/api/tanks/artifact/aca7a636649b/flats/front.dxf",
                      "/api/tanks/artifact/aca7a636649b/flats/back.dxf",
                      "/api/tanks/artifact/aca7a636649b/flats/left.dxf",
                      "/api/tanks/artifact/aca7a636649b/flats/right.dxf"
                    ]
                  },
                  "config_id": "aca7a636649b",
                  "units_requested": "in"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/InvalidConfig" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/tanks/artifact/{config_id}/{path}": {
      "get": {
        "operationId": "getArtifact",
        "summary": "Download a CAD artifact from a quote",
        "description": "STEP/STL/DXF/CSV/JSON artifact download. Use the paths returned in a quote's artifacts block (e.g. tank.step, flats/top.dxf). Public; sending an invalid bearer token returns 401.",
        "security": [{}, { "bearerAuth": [] }],
        "parameters": [
          {
            "name": "config_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "aca7a636649b"
          },
          {
            "name": "path",
            "in": "path",
            "required": true,
            "description": "Artifact path within the config, e.g. tank.step or flats/top.dxf",
            "schema": { "type": "string" },
            "example": "tank.step"
          }
        ],
        "responses": {
          "200": {
            "description": "The artifact file.",
            "content": {
              "application/octet-stream": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/tanks/order": {
      "post": {
        "operationId": "createOrder",
        "summary": "Place an order (capture + human review; no payment)",
        "description": "Requires a bearer token with the order:create scope. The server re-quotes config itself, so the stored price is authoritative. The order is stored as pending_review; a human contacts contact_email to confirm final price and lead time BEFORE any payment is requested. 20 orders/day per token. If the quote engine is unreachable the order is NOT stored (502).",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/OrderRequest" },
              "example": {
                "config": {
                  "length": 24,
                  "width": 12,
                  "height": 18,
                  "fittings": [{ "face": "top", "size": "2", "x": 18, "y": 7 }]
                },
                "contact_email": "operator@example.com",
                "notes": "ship to AZ; agent will coordinate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order captured, pending human review.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OrderResponse" },
                "example": {
                  "order_id": "ord_9b3d30a9f829",
                  "status": "pending_review",
                  "price_usd": 1363.62,
                  "estimate_disclaimer": "This price is a non-binding estimate. Final price and lead time are confirmed by a human before any payment is requested.",
                  "quote": { "price_usd": 1363.62, "config_id": "aca7a636649b" },
                  "status_url": "https://claudiverse.cc/api/tanks/order/ord_9b3d30a9f829"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": {
            "description": "Token lacks the order:create scope.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "422": { "$ref": "#/components/responses/InvalidConfig" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": {
            "description": "Quote engine unreachable or errored; order NOT stored.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": { "error": "engine_unreachable", "detail": "Quote engine unreachable. Retry later." }
              }
            }
          }
        }
      }
    },
    "/api/tanks/order/{id}": {
      "get": {
        "operationId": "getOrderStatus",
        "summary": "Order status (owner token only)",
        "description": "Returns 404 for unknown ids AND for orders placed by a different agent (ids don't leak).",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^ord_[0-9a-f]{12}$" },
            "example": "ord_9b3d30a9f829"
          }
        ],
        "responses": {
          "200": {
            "description": "Order status.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OrderStatusResponse" },
                "example": {
                  "order_id": "ord_9b3d30a9f829",
                  "status": "pending_review",
                  "price_usd": 1363.62,
                  "estimate_disclaimer": "This price is a non-binding estimate. Final price and lead time are confirmed by a human before any payment is requested.",
                  "created_at": "2026-06-10T01:19:01.020Z",
                  "updated_at": "2026-06-10T01:19:01.020Z"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Agent token from POST /api/agents/register: Authorization: Bearer cv_<48 hex>"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed body or invalid field.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "error": "invalid_email", "detail": "contact_email must be a valid email address." }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, malformed, unknown, or revoked token.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "error": "unauthorized", "detail": "Unknown or revoked token." }
          }
        }
      },
      "NotFound": {
        "description": "Not found (or not yours).",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "error": "not_found", "detail": "No such order for this agent." }
          }
        }
      },
      "InvalidConfig": {
        "description": "The engine rejected the config (out-of-range dims, fitting too close to an edge, etc.). The detail carries the engine's design-for-manufacture explanation.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "error": "invalid_config",
              "detail": "{\"detail\":\"fitting 0 (2\\\" FPT) on top: x=0.3in too close to an edge\"}"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Daily limit reached (limits reset at 00:00 UTC).",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "error": "rate_limited", "detail": "Daily quote limit (200) reached. Resets at 00:00 UTC." }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error", "detail"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Machine-actionable code: invalid_json | invalid_name | invalid_email | invalid_config | unauthorized | forbidden | not_found | rate_limited | engine_unreachable | engine_error | engine_not_configured | method_not_allowed | internal"
          },
          "detail": { "type": "string" }
        }
      },
      "RegisterRequest": {
        "type": "object",
        "required": ["name", "contact_email"],
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 80 },
          "contact_email": { "type": "string", "format": "email" },
          "description": { "type": "string", "maxLength": 500 }
        }
      },
      "RegisterResponse": {
        "type": "object",
        "required": ["agent_id", "token", "scopes", "rate_limits"],
        "properties": {
          "agent_id": { "type": "string", "pattern": "^agt_[0-9a-f]{12}$" },
          "token": { "type": "string", "description": "Bearer token cv_<48 hex>. Shown ONCE; only its SHA-256 hash is stored." },
          "scopes": { "type": "array", "items": { "type": "string" } },
          "rate_limits": { "$ref": "#/components/schemas/RateLimits" },
          "docs": { "type": "string", "format": "uri" },
          "note": { "type": "string" }
        }
      },
      "MeResponse": {
        "type": "object",
        "properties": {
          "agent_id": { "type": "string" },
          "name": { "type": "string" },
          "scopes": { "type": "array", "items": { "type": "string" } },
          "usage_today": {
            "type": "object",
            "properties": {
              "quotes": { "type": "integer" },
              "orders": { "type": "integer" }
            }
          },
          "rate_limits": { "$ref": "#/components/schemas/RateLimits" }
        }
      },
      "RateLimits": {
        "type": "object",
        "properties": {
          "quotes_per_day": { "type": "integer" },
          "orders_per_day": { "type": "integer" }
        }
      },
      "Fitting": {
        "type": "object",
        "required": ["face", "size", "x", "y"],
        "properties": {
          "face": { "type": "string", "enum": ["top", "bottom", "front", "back", "left", "right"] },
          "size": { "type": "string", "description": "FPT size from the catalog: \"0.5\" | \"1.5\" | \"2\" | \"3\"" },
          "x": { "type": "number", "description": "Along the face's x_axis from the 0,0 corner, in request units" },
          "y": { "type": "number", "description": "Along the face's y_axis from the 0,0 corner, in request units" }
        }
      },
      "QuoteRequest": {
        "type": "object",
        "required": ["length", "width", "height"],
        "properties": {
          "length": { "type": "number", "description": "X axis. 4-96 in (or mm equivalent)" },
          "width": { "type": "number", "description": "Y axis" },
          "height": { "type": "number", "description": "Z axis, vertical" },
          "units": { "type": "string", "enum": ["in", "mm"], "default": "in" },
          "fittings": { "type": "array", "items": { "$ref": "#/components/schemas/Fitting" } },
          "baffles": {
            "description": "Anti-slosh baffles: omit or \"auto\" (default, by longest horizontal span), \"none\", or an integer count as a string.",
            "type": ["string", "integer"]
          }
        }
      },
      "QuoteResponse": {
        "type": "object",
        "description": "Engine quote. price_usd is a NON-BINDING estimate. Artifact paths are relative to the server URL.",
        "properties": {
          "calibrated": { "type": "boolean" },
          "currency": { "type": "string" },
          "dimensions_in": {
            "type": "object",
            "properties": {
              "length": { "type": "number" },
              "width": { "type": "number" },
              "height": { "type": "number" }
            }
          },
          "wall_in": { "type": "number" },
          "metrics_mm": {
            "type": "object",
            "properties": {
              "material_area_mm2": { "type": "number" },
              "cut_length_mm": { "type": "number" },
              "weld_length_mm": { "type": "number" },
              "baffles": { "type": "integer" },
              "n_blanks": { "type": "integer" }
            }
          },
          "breakdown_usd": {
            "type": "object",
            "properties": {
              "material": { "type": "number" },
              "cutting": { "type": "number" },
              "scs_setup": { "type": "number" },
              "welding": { "type": "number" },
              "handling": { "type": "number" },
              "fittings": { "type": "number" },
              "subtotal": { "type": "number" },
              "margin_pct": { "type": "number" }
            }
          },
          "price_usd": { "type": "number" },
          "note": { "type": "string" },
          "capacity": {
            "type": "object",
            "properties": {
              "gallons": { "type": "number" },
              "liters": { "type": "number" }
            }
          },
          "fittings": { "type": "array", "items": { "type": "object" } },
          "baffles": { "type": "integer" },
          "artifacts": {
            "type": "object",
            "properties": {
              "step": { "type": "string" },
              "stl": { "type": "string" },
              "quote_json": { "type": "string" },
              "manifest_csv": { "type": "string" },
              "blanks": { "type": "array", "items": { "type": "string" } }
            }
          },
          "config_id": { "type": "string" },
          "units_requested": { "type": "string" }
        }
      },
      "OrderRequest": {
        "type": "object",
        "required": ["config", "contact_email"],
        "properties": {
          "config": { "$ref": "#/components/schemas/QuoteRequest" },
          "contact_email": { "type": "string", "format": "email", "description": "Where order updates go" },
          "notes": { "type": "string", "maxLength": 2000 }
        }
      },
      "OrderResponse": {
        "type": "object",
        "required": ["order_id", "status", "price_usd", "estimate_disclaimer"],
        "properties": {
          "order_id": { "type": "string", "pattern": "^ord_[0-9a-f]{12}$" },
          "status": { "type": "string", "enum": ["pending_review"] },
          "price_usd": { "type": "number", "description": "Non-binding estimate from the server-side re-quote" },
          "estimate_disclaimer": { "type": "string" },
          "quote": { "$ref": "#/components/schemas/QuoteResponse" },
          "status_url": { "type": "string", "format": "uri" }
        }
      },
      "OrderStatusResponse": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" },
          "status": { "type": "string", "description": "pending_review now; confirmed/in_production/shipped lifecycle planned" },
          "price_usd": { "type": "number" },
          "estimate_disclaimer": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "Catalog": {
        "type": "object",
        "description": "Faces, fitting sizes, dimension limits, material, baffle rules, and the coordinate convention (axis map + per-face x_axis/y_axis/normal + fitting_xy note).",
        "properties": {
          "faces": { "type": "array", "items": { "type": "string" } },
          "fittings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "size": { "type": "string" },
                "label": { "type": "string" }
              }
            }
          },
          "dim_limits_in": {
            "type": "object",
            "properties": {
              "min": { "type": "number" },
              "max": { "type": "number" }
            }
          },
          "material": { "type": "string" },
          "dimensions": { "type": "array", "items": { "type": "string" } },
          "baffles": { "type": "object" },
          "coordinate_system": { "type": "object" }
        }
      }
    }
  }
}