{
  "openapi": "3.1.0",
  "info": {
    "title": "Acme Orders (demo)",
    "version": "1.0.0",
    "description": "A small internal orders service used by the governed-writes example. Reads are autonomous, notes are autonomous writes, and refunds require a human approver."
  },
  "servers": [{"url": "http://127.0.0.1:8090"}],
  "security": [{"bearerAuth": []}],
  "paths": {
    "/orders": {
      "get": {
        "operationId": "listOrders",
        "x-dt-tool-name": "list_orders",
        "summary": "List recent orders, optionally filtered by status.",
        "parameters": [
          {"name": "status", "in": "query", "required": false, "schema": {"type": "string", "enum": ["processing", "shipped", "delivered", "refunded"]}}
        ],
        "x-dt-policy": "read",
        "responses": {
          "200": {
            "description": "Orders",
            "content": {"application/json": {"schema": {"type": "object", "properties": {"orders": {"type": "array", "items": {"$ref": "#/components/schemas/OrderSummary"}}}}}}
          }
        }
      }
    },
    "/orders/{order_id}": {
      "get": {
        "operationId": "getOrder",
        "x-dt-tool-name": "get_order",
        "summary": "Get one order with its items, notes and refunds.",
        "parameters": [{"$ref": "#/components/parameters/OrderId"}],
        "x-dt-policy": "read",
        "x-dt-redact": ["/customer/email"],
        "responses": {
          "200": {"description": "Order", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}}}},
          "404": {"description": "Unknown order", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}
        }
      }
    },
    "/orders/{order_id}/notes": {
      "post": {
        "operationId": "addOrderNote",
        "x-dt-tool-name": "add_order_note",
        "summary": "Add an internal support note to an order. Visible to staff only.",
        "parameters": [{"$ref": "#/components/parameters/OrderId"}],
        "x-dt-policy": "autonomous",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {
            "type": "object",
            "required": ["body"],
            "additionalProperties": false,
            "properties": {"body": {"type": "string", "minLength": 1, "maxLength": 2000}}
          }}}
        },
        "responses": {
          "201": {"description": "Note added", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Note"}}}},
          "404": {"description": "Unknown order", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}
        }
      }
    },
    "/orders/{order_id}/refunds": {
      "post": {
        "operationId": "issueRefund",
        "x-dt-tool-name": "issue_refund",
        "summary": "Refund money to the customer's original payment method. Moves real money; cannot be undone.",
        "parameters": [{"$ref": "#/components/parameters/OrderId"}],
        "x-dt-policy": "approval",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {
            "type": "object",
            "required": ["amount_cents", "reason"],
            "additionalProperties": false,
            "properties": {
              "amount_cents": {"type": "integer", "minimum": 1, "description": "Amount to refund, in cents. Cannot exceed the remaining refundable amount."},
              "reason": {"type": "string", "minLength": 1, "maxLength": 500, "description": "Why the refund is owed, as you would write it in the order history."},
              "notify_customer": {"type": "boolean", "default": true}
            }
          }}}
        },
        "responses": {
          "201": {"description": "Refund issued", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Refund"}}}},
          "404": {"description": "Unknown order", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
          "422": {"description": "Refund rejected", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {"type": "http", "scheme": "bearer"}
    },
    "parameters": {
      "OrderId": {"name": "order_id", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^A-[0-9]{4}$"}}
    },
    "schemas": {
      "Customer": {
        "type": "object",
        "properties": {"name": {"type": "string"}, "email": {"type": "string"}, "tier": {"type": "string"}}
      },
      "OrderSummary": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "status": {"type": "string"},
          "total_cents": {"type": "integer"},
          "customer_name": {"type": "string"}
        }
      },
      "Note": {
        "type": "object",
        "properties": {"id": {"type": "string"}, "body": {"type": "string"}, "created_at": {"type": "string"}}
      },
      "Refund": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "order_id": {"type": "string"},
          "amount_cents": {"type": "integer"},
          "reason": {"type": "string"},
          "notify_customer": {"type": "boolean"},
          "created_at": {"type": "string"}
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "status": {"type": "string"},
          "placed_at": {"type": "string"},
          "total_cents": {"type": "integer"},
          "refundable_cents": {"type": "integer"},
          "customer": {"$ref": "#/components/schemas/Customer"},
          "items": {"type": "array", "items": {"type": "object", "properties": {"sku": {"type": "string"}, "name": {"type": "string"}, "price_cents": {"type": "integer"}}}},
          "notes": {"type": "array", "items": {"$ref": "#/components/schemas/Note"}},
          "refunds": {"type": "array", "items": {"$ref": "#/components/schemas/Refund"}}
        }
      },
      "Error": {
        "type": "object",
        "properties": {"error": {"type": "string"}, "detail": {"type": "string"}}
      }
    }
  }
}