{
  "openapi": "3.1.0",
  "info": {
    "title": "Cancel Hansel API",
    "version": "0.1.0",
    "description": "Evidence and protection API for online reservation, event booking, venue booking, hospitality booking, marketplace booking, and talent booking platforms.",
    "contact": {
      "name": "Cancel Hansel Developer Support",
      "email": "access@hanselboyd.com",
      "url": "https://cancelhansel.com/developers"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://cancelhansel.com"
    }
  },
  "servers": [
    {
      "url": "https://api.cancelhansel.com",
      "description": "Production API"
    }
  ],
  "paths": {
    "/v1/health": {
      "get": {
        "summary": "Health check",
        "description": "Check the health and readiness of the Cancel Hansel API.",
        "operationId": "getHealth",
        "tags": ["Health"],
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": ["ok", "healthy"]
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/partners/register": {
      "post": {
        "summary": "Register a partner",
        "description": "Create a new partner account and receive initial API credentials.",
        "operationId": "registerPartner",
        "tags": ["Partners"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "businessType", "contactEmail"],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Company or platform name"
                  },
                  "businessType": {
                    "type": "string",
                    "description": "Type of business (e.g., Booking Marketplace, Venue Operator)"
                  },
                  "contactEmail": {
                    "type": "string",
                    "format": "email",
                    "description": "Primary contact email"
                  },
                  "website": {
                    "type": "string",
                    "format": "uri",
                    "description": "Company website"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Partner registered successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "partnerId": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": ["pending", "approved", "active"]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid partner registration data"
          }
        }
      }
    },
    "/v1/api-keys": {
      "post": {
        "summary": "Create API key",
        "description": "Generate a new scoped API key for partner integration.",
        "operationId": "createApiKey",
        "tags": ["Authentication"],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Descriptive name for the API key"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of scopes (e.g., bookings:write, webhooks:read)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API key created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apiKeyId": {
                      "type": "string"
                    },
                    "apiKey": {
                      "type": "string"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/bookings": {
      "post": {
        "summary": "Create booking",
        "description": "Create a new booking record with talent, organizer, event, and value metadata.",
        "operationId": "createBooking",
        "tags": ["Bookings"],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["talent", "organizer", "eventType", "eventDate", "bookingValue"],
                "properties": {
                  "talent": {
                    "type": "object",
                    "required": ["id", "name"],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      }
                    }
                  },
                  "organizer": {
                    "type": "object",
                    "required": ["id", "name"],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      }
                    }
                  },
                  "eventType": {
                    "type": "string",
                    "description": "Type of event (e.g., concert, wedding, conference)"
                  },
                  "eventDate": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Scheduled event date/time"
                  },
                  "bookingValue": {
                    "type": "number",
                    "description": "Total booking value"
                  },
                  "currency": {
                    "type": "string",
                    "default": "USD",
                    "description": "Currency code (ISO 4217)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Booking created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bookingId": {
                      "type": "string"
                    },
                    "partnerId": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": ["created", "protected", "canceled"]
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/bookings/{bookingId}": {
      "get": {
        "summary": "Get booking details",
        "description": "Retrieve full details of a specific booking record.",
        "operationId": "getBooking",
        "tags": ["Bookings"],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "bookingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Booking details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bookingId": {
                      "type": "string"
                    },
                    "partnerId": {
                      "type": "string"
                    },
                    "talent": {
                      "type": "object"
                    },
                    "organizer": {
                      "type": "object"
                    },
                    "eventType": {
                      "type": "string"
                    },
                    "eventDate": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "bookingValue": {
                      "type": "number"
                    },
                    "currency": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "protected": {
                      "type": "boolean"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Booking not found"
          }
        }
      }
    },
    "/v1/bookings/{bookingId}/protect": {
      "post": {
        "summary": "Protect booking",
        "description": "Mark a booking as protected and establish tamper-evident record.",
        "operationId": "protectBooking",
        "tags": ["Bookings"],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "bookingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Booking protected",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bookingId": {
                      "type": "string"
                    },
                    "protected": {
                      "type": "boolean"
                    },
                    "protectedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/bookings/{bookingId}/webhook-events": {
      "get": {
        "summary": "Get webhook events for booking",
        "description": "Retrieve all lifecycle events and webhook deliveries for a booking.",
        "operationId": "getWebhookEvents",
        "tags": ["Webhooks"],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "bookingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bookingId": {
                      "type": "string"
                    },
                    "webhookEvents": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhook-events/{eventId}/retry": {
      "post": {
        "summary": "Retry webhook delivery",
        "description": "Manually retry delivery of a failed webhook event.",
        "operationId": "retryWebhookEvent",
        "tags": ["Webhooks"],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "eventId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Retry initiated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "eventId": {
                      "type": "string"
                    },
                    "retryStatus": {
                      "type": "string",
                      "enum": ["pending", "delivered", "failed"]
                    },
                    "retryCount": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/bookings/{bookingId}/policy-evaluation": {
      "get": {
        "summary": "Get policy evaluation",
        "description": "Retrieve policy evaluation results for a booking's cancellation.",
        "operationId": "getPolicyEvaluation",
        "tags": ["Policy"],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "bookingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Policy evaluation results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bookingId": {
                      "type": "string"
                    },
                    "evaluationStatus": {
                      "type": "string"
                    },
                    "resolutionPath": {
                      "type": "string"
                    },
                    "evaluatedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key for authentication"
      }
    }
  },
  "tags": [
    {
      "name": "Health",
      "description": "API health and status"
    },
    {
      "name": "Partners",
      "description": "Partner registration and management"
    },
    {
      "name": "Authentication",
      "description": "API key and authentication management"
    },
    {
      "name": "Bookings",
      "description": "Booking record operations"
    },
    {
      "name": "Webhooks",
      "description": "Webhook event management"
    },
    {
      "name": "Policy",
      "description": "Policy evaluation operations"
    }
  ]
}