{
  "openapi": "3.1.0",
  "info": {
    "title": "Haggles API",
    "description": "Haggles facilitator protocol API (`/v1/*`), portal API (`/portal/v1/*`), and PayPal webhooks (SPEC.md section 5).",
    "version": "0.1.0",
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "components": {
    "schemas": {}
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "Liveness probe",
        "tags": [
          "system"
        ],
        "description": "Returns 200 OK whenever the API process is up (SPEC.md section 5.1).",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "anyOf": [
                        {
                          "type": "string",
                          "enum": [
                            "ok"
                          ]
                        },
                        {
                          "type": "string",
                          "enum": [
                            "not_ready"
                          ]
                        }
                      ]
                    },
                    "reason": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/ready": {
      "get": {
        "summary": "Readiness probe",
        "tags": [
          "system"
        ],
        "description": "Verifies PostgreSQL connectivity and that all required migrations have been applied (SPEC.md sections 5.1 and 9.3).",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "anyOf": [
                        {
                          "type": "string",
                          "enum": [
                            "ok"
                          ]
                        },
                        {
                          "type": "string",
                          "enum": [
                            "not_ready"
                          ]
                        }
                      ]
                    },
                    "reason": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "anyOf": [
                        {
                          "type": "string",
                          "enum": [
                            "ok"
                          ]
                        },
                        {
                          "type": "string",
                          "enum": [
                            "not_ready"
                          ]
                        }
                      ]
                    },
                    "reason": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/jwks.json": {
      "get": {
        "summary": "Public Ed25519 signing keys (JWKS)",
        "tags": [
          "protocol"
        ],
        "description": "Returns active and recently retired Ed25519 public keys used to verify payment tokens and receipts (SPEC.md section 4.6).",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "keys"
                  ],
                  "properties": {
                    "keys": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": {}
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments": {
      "post": {
        "summary": "Authorize a payment",
        "tags": [
          "protocol"
        ],
        "description": "Validates a 402 challenge, enforces the agent key's spending policy, places a hold on the buyer wallet, and issues a short-lived Ed25519 payment token (SPEC.md section 5.1).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "type": "object",
                "required": [
                  "challenge"
                ],
                "properties": {
                  "challenge": {
                    "type": "object",
                    "additionalProperties": {}
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "payment_id",
                    "token",
                    "amount",
                    "currency",
                    "expires_at"
                  ],
                  "properties": {
                    "payment_id": {
                      "type": "string"
                    },
                    "token": {
                      "type": "string"
                    },
                    "amount": {
                      "type": "string"
                    },
                    "currency": {
                      "type": "string",
                      "enum": [
                        "USD"
                      ]
                    },
                    "expires_at": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}": {
      "get": {
        "summary": "Read a payment",
        "tags": [
          "protocol"
        ],
        "description": "Returns a payment for the owning agent key or seller key. Sellers receive a pseudonymous agent_ref and never buyer identity (SPEC.md sections 5.1 and 8.4).",
        "parameters": [
          {
            "schema": {
              "minLength": 1,
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {}
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}/redeem": {
      "post": {
        "summary": "Redeem (capture) an authorized payment",
        "tags": [
          "protocol"
        ],
        "description": "Verifies the payment token, atomically transitions the payment from authorized to captured, credits the seller net of platform fee, and returns a signed receipt (SPEC.md section 5.1).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "type": "object",
                "required": [
                  "token",
                  "method",
                  "url",
                  "amount"
                ],
                "properties": {
                  "token": {
                    "minLength": 1,
                    "type": "string"
                  },
                  "method": {
                    "minLength": 1,
                    "type": "string"
                  },
                  "url": {
                    "minLength": 1,
                    "type": "string"
                  },
                  "amount": {
                    "minLength": 1,
                    "type": "string"
                  },
                  "route": {
                    "maxLength": 200,
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "minLength": 1,
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "payment_id",
                    "status",
                    "amount",
                    "seller_net",
                    "receipt"
                  ],
                  "properties": {
                    "payment_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "captured"
                      ]
                    },
                    "amount": {
                      "type": "string"
                    },
                    "seller_net": {
                      "type": "string"
                    },
                    "receipt": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}/refund": {
      "post": {
        "summary": "Refund a captured payment",
        "tags": [
          "protocol"
        ],
        "description": "Refunds a captured payment within 24 hours, returning the gross amount (including platform fee) to the buyer wallet's available balance (SPEC.md sections 5.1, 6.3, 7.4).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "type": "object",
                "required": [
                  "reason"
                ],
                "properties": {
                  "reason": {
                    "anyOf": [
                      {
                        "type": "string",
                        "enum": [
                          "handler_error"
                        ]
                      },
                      {
                        "type": "string",
                        "enum": [
                          "seller_initiated"
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "minLength": 1,
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "payment_id",
                    "status",
                    "amount",
                    "refunded_at"
                  ],
                  "properties": {
                    "payment_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "refunded"
                      ]
                    },
                    "amount": {
                      "type": "string"
                    },
                    "refunded_at": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallet": {
      "get": {
        "summary": "Read buyer wallet balance and policy allowance",
        "tags": [
          "protocol"
        ],
        "description": "Returns available and held USD balance plus remaining per-call, daily, and monthly policy allowances for the authenticated agent key (SPEC.md sections 5.1 and 10.2).",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "available",
                    "held",
                    "currency",
                    "allowance"
                  ],
                  "properties": {
                    "available": {
                      "type": "string"
                    },
                    "held": {
                      "type": "string"
                    },
                    "currency": {
                      "type": "string",
                      "enum": [
                        "USD"
                      ]
                    },
                    "allowance": {
                      "additionalProperties": false,
                      "type": "object",
                      "required": [
                        "per_call_max",
                        "daily_remaining",
                        "monthly_remaining"
                      ],
                      "properties": {
                        "per_call_max": {
                          "type": "string"
                        },
                        "daily_remaining": {
                          "type": "string"
                        },
                        "monthly_remaining": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/portal/v1/auth/paypal/start": {
      "get": {
        "summary": "Start Log in with PayPal authorization flow",
        "tags": [
          "portal"
        ],
        "description": "Generates a cryptographic OAuth2 state cookie and redirects (or returns the authorize URL) for Log in with PayPal (SPEC.md sections 5.2 and 8.3).",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/auth/paypal/callback": {
      "get": {
        "summary": "Complete Log in with PayPal authorization callback",
        "tags": [
          "portal"
        ],
        "description": "Verifies the OAuth2 state cookie, exchanges the authorization code with PayPal, fetches userinfo (`payer_id`, primary confirmed email, `verified_account`), and sets `hg_session` and `hg_csrf` cookies (SPEC.md sections 5.2 and 8.3).",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "code",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "state",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "error",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "error_description",
            "required": false
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/auth/logout": {
      "post": {
        "summary": "Log out current portal session",
        "tags": [
          "portal"
        ],
        "description": "Invalidates the current `hg_session` token and clears session/CSRF cookies (SPEC.md sections 5.2 and 8.3).",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/me": {
      "get": {
        "summary": "Read current authenticated account profile and roles",
        "tags": [
          "portal"
        ],
        "description": "Returns the authenticated account profile, enabled roles (`is_buyer`, `is_seller`), wallet ID, seller ID, and environment mode (SPEC.md sections 5.2 and 11.6).",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      },
      "patch": {
        "summary": "Update current account profile and Buyer/Seller roles",
        "tags": [
          "portal"
        ],
        "description": "Updates `display_name`, `is_buyer`, and `is_seller` roles, provisioning wallet/seller records as needed and enforcing non-zero balance role guards (SPEC.md sections 5.2, 11.3, 11.6).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "type": "object",
                "properties": {
                  "display_name": {
                    "maxLength": 100,
                    "type": "string"
                  },
                  "is_buyer": {
                    "type": "boolean"
                  },
                  "is_seller": {
                    "type": "boolean"
                  },
                  "revoke_all_sessions": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/buyer/summary": {
      "get": {
        "summary": "Buyer overview summary",
        "tags": [
          "portal"
        ],
        "description": "Returns available and held balance, in-flight hold count, today's spend, smallest daily key cap, 30-day spend, and recent payments (SPEC.md sections 5.2 and 11.4).",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/buyer/spend-series": {
      "get": {
        "summary": "Buyer daily spend time-series",
        "tags": [
          "portal"
        ],
        "description": "Returns daily spend totals over the requested number of UTC days (default 30, SPEC.md sections 5.2 and 11.4).",
        "parameters": [
          {
            "schema": {
              "minimum": 1,
              "maximum": 90,
              "default": 30,
              "type": "integer"
            },
            "in": "query",
            "name": "days",
            "required": false
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/buyer/keys": {
      "get": {
        "summary": "List buyer agent keys",
        "tags": [
          "portal"
        ],
        "description": "Lists all agent keys belonging to the authenticated buyer's wallet along with today's spend per key (SPEC.md sections 5.2 and 11.4).",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      },
      "post": {
        "summary": "Create a buyer agent key",
        "tags": [
          "portal"
        ],
        "description": "Issues a new `hgk_<env>_...` agent key with spending policy caps. Returns the full secret key once at creation (SPEC.md sections 5.2, 5.3, 8.1, 11.4).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "minLength": 1,
                    "maxLength": 60,
                    "type": "string"
                  },
                  "per_call_max": {
                    "type": "string"
                  },
                  "daily_max": {
                    "type": "string"
                  },
                  "monthly_max": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "allowed_sellers": {
                    "anyOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "allowed_hosts": {
                    "anyOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "expires_at": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/buyer/keys/{id}": {
      "get": {
        "summary": "Read a buyer agent key",
        "tags": [
          "portal"
        ],
        "description": "Returns a single agent key owned by the authenticated buyer (`404` if owned by another tenant, SPEC.md sections 5.2 and 8.4).",
        "parameters": [
          {
            "schema": {
              "minLength": 1,
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      },
      "patch": {
        "summary": "Update a buyer agent key policy",
        "tags": [
          "portal"
        ],
        "description": "Updates an agent key's name and spending policy fields (`404` if owned by another tenant, SPEC.md sections 5.2 and 8.4).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "type": "object",
                "properties": {
                  "name": {
                    "minLength": 1,
                    "maxLength": 60,
                    "type": "string"
                  },
                  "per_call_max": {
                    "type": "string"
                  },
                  "daily_max": {
                    "type": "string"
                  },
                  "monthly_max": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "allowed_sellers": {
                    "anyOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "allowed_hosts": {
                    "anyOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "expires_at": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "minLength": 1,
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/buyer/keys/{id}/revoke": {
      "post": {
        "summary": "Revoke a buyer agent key",
        "tags": [
          "portal"
        ],
        "description": "Immediately revokes an agent key so subsequent authorization requests fail with `401 key_revoked` (SPEC.md sections 5.2, 8.4, 8.8).",
        "parameters": [
          {
            "schema": {
              "minLength": 1,
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/buyer/payments": {
      "get": {
        "summary": "List buyer payments with filters and cursor pagination",
        "tags": [
          "portal"
        ],
        "description": "Lists payments for the authenticated buyer wallet filtered by key, seller, status, and date range (SPEC.md sections 5.2 and 11.4).",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "key",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "seller",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "status",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "from",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "to",
            "required": false
          },
          {
            "schema": {
              "minimum": 1,
              "maximum": 100,
              "default": 50,
              "type": "integer"
            },
            "in": "query",
            "name": "limit",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "cursor",
            "required": false
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/buyer/payments/{id}": {
      "get": {
        "summary": "Read a single buyer payment",
        "tags": [
          "portal"
        ],
        "description": "Returns detailed timeline and receipt for a single payment owned by the authenticated buyer (`404` if foreign, SPEC.md sections 5.2 and 8.4).",
        "parameters": [
          {
            "schema": {
              "minLength": 1,
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/buyer/topups": {
      "get": {
        "summary": "List buyer wallet top-ups",
        "tags": [
          "portal"
        ],
        "description": "Lists PayPal top-up orders for the authenticated buyer wallet with cursor pagination (SPEC.md sections 5.2, 7.1, 11.4).",
        "parameters": [
          {
            "schema": {
              "minimum": 1,
              "maximum": 100,
              "default": 50,
              "type": "integer"
            },
            "in": "query",
            "name": "limit",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "cursor",
            "required": false
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      },
      "post": {
        "summary": "Create a PayPal top-up order",
        "tags": [
          "portal"
        ],
        "description": "Validates top-up and max wallet balance limits, creates a `topups` record, and creates a PayPal Checkout Order v2 with `PayPal-Request-Id = top_<ULID>` (SPEC.md sections 5.2 and 7.1 step 1).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "type": "object",
                "required": [
                  "amount"
                ],
                "properties": {
                  "amount": {
                    "minLength": 1,
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/buyer/topups/{id}/capture": {
      "post": {
        "summary": "Capture an approved PayPal top-up order",
        "tags": [
          "portal"
        ],
        "description": "Captures the PayPal Checkout Order and credits the buyer wallet ONLY when PayPal confirms `COMPLETED` status (SPEC.md sections 5.2 and 7.1 steps 3-4).",
        "parameters": [
          {
            "schema": {
              "minLength": 1,
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/seller/summary": {
      "get": {
        "summary": "Seller overview summary",
        "tags": [
          "portal"
        ],
        "description": "Returns pending, processing, and paid-out balances, 24h call count, 30d net revenue, top endpoints, and recent calls (SPEC.md sections 5.2 and 11.5).",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/seller/revenue-series": {
      "get": {
        "summary": "Seller daily net revenue time-series",
        "tags": [
          "portal"
        ],
        "description": "Returns daily net revenue and call counts over the requested number of UTC days (default 30, SPEC.md sections 5.2 and 11.5).",
        "parameters": [
          {
            "schema": {
              "minimum": 1,
              "maximum": 90,
              "default": 30,
              "type": "integer"
            },
            "in": "query",
            "name": "days",
            "required": false
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/seller/endpoints": {
      "get": {
        "summary": "List auto-discovered seller endpoints",
        "tags": [
          "portal"
        ],
        "description": "Lists endpoints discovered on capture along with 30-day call count and net revenue (SPEC.md sections 2.1 D7, 5.2, 11.5).",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/seller/endpoints/{id}": {
      "patch": {
        "summary": "Update seller endpoint metadata",
        "tags": [
          "portal"
        ],
        "description": "Updates `display_name`, `description`, or `status` for a seller endpoint (`404` if owned by another tenant, SPEC.md sections 5.2, 8.4, 11.5).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "type": "object",
                "properties": {
                  "display_name": {
                    "anyOf": [
                      {
                        "maxLength": 120,
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "description": {
                    "anyOf": [
                      {
                        "maxLength": 500,
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "status": {
                    "anyOf": [
                      {
                        "type": "string",
                        "enum": [
                          "active"
                        ]
                      },
                      {
                        "type": "string",
                        "enum": [
                          "hidden"
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "minLength": 1,
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/seller/keys": {
      "get": {
        "summary": "List seller API keys",
        "tags": [
          "portal"
        ],
        "description": "Lists all seller API keys (`hgs_<env>_...`) belonging to the authenticated seller (SPEC.md sections 5.2 and 11.5).",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      },
      "post": {
        "summary": "Create a seller API key",
        "tags": [
          "portal"
        ],
        "description": "Issues a new `hgs_<env>_...` seller API key (max 2 active keys per seller) and returns the full secret key once (SPEC.md sections 5.2, 6.1, 11.5).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "minLength": 1,
                    "maxLength": 60,
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/seller/keys/{id}/revoke": {
      "post": {
        "summary": "Revoke a seller API key",
        "tags": [
          "portal"
        ],
        "description": "Immediately revokes a seller API key (`404` if owned by another tenant, SPEC.md sections 5.2 and 8.4).",
        "parameters": [
          {
            "schema": {
              "minLength": 1,
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/seller/calls": {
      "get": {
        "summary": "List seller calls with pseudonymous agent_ref",
        "tags": [
          "portal"
        ],
        "description": "Lists calls (payments) to the authenticated seller's endpoints with pseudonymous `agent_ref`, gross amount, platform fee, and seller net (SPEC.md sections 5.2, 8.4, 11.5).",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "endpoint",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "status",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "from",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "to",
            "required": false
          },
          {
            "schema": {
              "minimum": 1,
              "maximum": 100,
              "default": 50,
              "type": "integer"
            },
            "in": "query",
            "name": "limit",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "cursor",
            "required": false
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/seller/payouts": {
      "get": {
        "summary": "List seller payouts",
        "tags": [
          "portal"
        ],
        "description": "Lists payouts for the authenticated seller in reverse chronological order (SPEC.md sections 5.2, 7.2, 11.5).",
        "parameters": [
          {
            "schema": {
              "minimum": 1,
              "maximum": 100,
              "default": 50,
              "type": "integer"
            },
            "in": "query",
            "name": "limit",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "cursor",
            "required": false
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      },
      "post": {
        "summary": "Request an on-demand seller payout",
        "tags": [
          "portal"
        ],
        "description": "Initiates an on-demand payout to the seller's PayPal `payer_id` (max 1 request per hour, minimum $1.00 pending balance, floored to whole cents, SPEC.md sections 5.2 and 7.2).",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/portal/v1/seller/test-key": {
      "post": {
        "summary": "Issue a sandbox test agent key for seller setup",
        "tags": [
          "portal"
        ],
        "description": "Issues a sandbox-only agent key restricted to this seller (`allowed_sellers`) and capped at $0.50/day so the seller can test their first paid call without funding a separate buyer wallet (SPEC.md sections 5.2 and 11.5 step 4).",
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/webhooks/paypal": {
      "post": {
        "summary": "Receive and verify PayPal webhook notifications",
        "tags": [
          "webhooks"
        ],
        "description": "Verifies the PayPal webhook signature using the raw request body bytes, deduplicates by `paypal_event_id`, and reconciles top-up captures and seller payout items by re-fetching from PayPal (SPEC.md sections 5.2, 7.1, 7.2, 8.5).",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "verified",
                    "duplicate",
                    "event_id",
                    "event_type"
                  ],
                  "properties": {
                    "verified": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "duplicate": {
                      "type": "boolean"
                    },
                    "event_id": {
                      "type": "string"
                    },
                    "event_type": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.haggles.example.com",
      "description": "Haggles Facilitator API"
    }
  ],
  "tags": [
    {
      "name": "system",
      "description": "Health and readiness endpoints"
    },
    {
      "name": "protocol",
      "description": "Haggles HTTP 402 facilitator protocol endpoints"
    },
    {
      "name": "portal",
      "description": "Authenticated portal buyer and seller endpoints"
    },
    {
      "name": "webhooks",
      "description": "PayPal webhook receiver"
    }
  ]
}
