{
  "openapi": "3.0.3",
  "info": {
    "title": "Orbicost Metrology & Urban Economics API",
    "version": "1.0.0",
    "description": "Standardized programmatic access to Orbicost cost-of-living metrology indices, comparative city calculations, and urban economic data across 93 global metropolitan centers.",
    "contact": {
      "name": "Orbicost Studio API Operations",
      "email": "ivanjakeo@gmail.com",
      "url": "https://orbicost.com"
    },
    "license": {
      "name": "Proprietary / Open Consumer Interface",
      "url": "https://orbicost.com/#legal"
    }
  },
  "x-service-info": {
    "name": "Orbicost",
    "description": "Intelligent Global Cost of Living Metrology, City Index & Relocation Intelligence Reports",
    "categories": [
      "finance",
      "travel",
      "relocation",
      "data",
      "analytics"
    ],
    "homepage": "https://orbicost.com",
    "terms_of_service": "https://orbicost.com/#legal",
    "pricing": {
      "model": "freemium",
      "currency": "USD",
      "free_tier": "Basic city lookups and index calculations are free",
      "paid_tiers": [
        {
          "name": "Premium Metrology Query",
          "price": "$0.10",
          "protocol": "x402"
        },
        {
          "name": "Agent Delegation Mandate",
          "price": "$5.00",
          "protocol": "ap2"
        },
        {
          "name": "Custom Relocation Dossier",
          "price": "$9.99",
          "protocol": "stripe"
        }
      ]
    }
  },
  "servers": [
    {
      "url": "https://orbicost.com/api",
      "description": "Orbicost Primary API Server"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Service Health Check",
        "description": "Returns current operational status of API services and database connections.",
        "operationId": "getHealthStatus",
        "responses": {
          "200": {
            "description": "System operational",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1": {
      "get": {
        "summary": "Orbicost Paid Metrology & Urban Economics API (x402 Protocol)",
        "description": "Standardized programmatic metrology index access monetized via HTTP 402 and x402 micropayments.",
        "operationId": "getMetrologyApiV1",
        "x-payment-info": {
          "intent": "charge",
          "method": "tempo",
          "amount": "10",
          "currency": "USD",
          "description": "Orbicost Metrology Urban Economics API Query via x402"
        },
        "responses": {
          "200": {
            "description": "Metrology payload returned when payment signature is verified"
          },
          "402": {
            "description": "Payment Required - returns x402 challenge parameters"
          }
        }
      }
    },
    "/checkout": {
      "post": {
        "summary": "Purchase Full Metropolitan Intelligence Report",
        "description": "Initiates purchase and generation of a comprehensive 99-price or 665-price urban relocation and cost-of-living report.",
        "operationId": "checkoutReport",
        "x-payment-info": {
          "intent": "charge",
          "method": "card",
          "amount": "1499",
          "currency": "USD",
          "description": "Full Metropolitan Living Cost & Relocation Intelligence Report (PDF + Excel)"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "city": {
                    "type": "string",
                    "example": "tokyo"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "pdf",
                      "excel"
                    ],
                    "example": "pdf"
                  },
                  "tier": {
                    "type": "string",
                    "enum": [
                      "basic",
                      "expert"
                    ],
                    "example": "expert"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout session created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "reportUrl": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/report/order": {
      "post": {
        "summary": "Order Relocation Comparative Analysis",
        "description": "Orders comparative expense metrics and currency parity benchmark for any two metropolitan centers.",
        "operationId": "orderReport",
        "x-payment-info": {
          "intent": "charge",
          "method": "stripe",
          "amount": "999",
          "currency": "USD",
          "description": "Standard City Economics & Expenditure Comparison Report"
        },
        "responses": {
          "200": {
            "description": "Order processed"
          }
        }
      }
    },
    "/ap2/payment": {
      "post": {
        "summary": "AP2 Mandate Autonomous Payment Settlement",
        "description": "Settles agent-mandated payment transactions per Agent Payments Protocol (AP2) v0.1.0.",
        "operationId": "settleAp2Payment",
        "x-payment-info": {
          "intent": "charge",
          "method": "tempo",
          "amount": "500",
          "currency": "USD",
          "description": "Autonomous Agent AP2 Payment Mandate Settlement"
        },
        "responses": {
          "200": {
            "description": "Mandate payment settled"
          }
        }
      }
    },
    "/session/metered": {
      "post": {
        "summary": "Open High-Throughput Metered Agent Session",
        "description": "Establishes a streaming machine payment session for automated continuous metrology querying.",
        "operationId": "openMeteredSession",
        "x-payment-info": {
          "intent": "session",
          "method": "lightning",
          "amount": "100",
          "currency": "USD",
          "description": "Machine Payment Micro-Session for real-time high-throughput API streams"
        },
        "responses": {
          "200": {
            "description": "Session established"
          }
        }
      }
    },
    "/x402": {
      "get": {
        "summary": "x402 Micropayment Protected Metrology Query",
        "description": "Autonomous AI agent endpoint monetized via x402 protocol using USDC micropayments.",
        "operationId": "queryMetrologyX402",
        "x-payment-info": {
          "intent": "charge",
          "method": "tempo",
          "amount": "10",
          "currency": "USD",
          "description": "Orbicost Metrology Agentic Machine Payment via x402"
        },
        "responses": {
          "200": {
            "description": "Data returned after successful x402 payment verification"
          },
          "402": {
            "description": "Payment Required - returns x402 challenge parameters"
          }
        }
      }
    }
  }
}