{
  "openapi": "3.1.0",
  "info": {
    "title": "Knot API",
    "description": "An API to interact with the Knot merchant connectivity platform.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://secure.development.knotapi.com",
      "description": "Development server"
    }
  ],
  "security": [
    {
      "basicAuth": []
    }
  ],
  "x-mint": {
    "mcp": {
      "enabled": true,
      "name": "knot"
    }
  },
  "paths": {
    "/card": {
      "post": {
        "operationId": "card_switch",
        "summary": "Switch Card",
        "description": "Switch a card in a user's merchant account.",
        "requestBody": {
          "description": "The input parameters required for switching a card.",
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "title": "CardSwitcher",
                    "type": "object",
                    "properties": {
                      "user": {
                        "type": "object",
                        "description": "",
                        "properties": {
                          "name": {
                            "type": "object",
                            "description": "",
                            "properties": {
                              "first_name": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "User's first name.",
                                "example": "Ada"
                              },
                              "last_name": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "User's last name.",
                                "example": "Lovelace"
                              }
                            },
                            "required": [
                              "first_name",
                              "last_name"
                            ]
                          },
                          "phone_number": {
                            "type": "string",
                            "description": "User's phone number in E.164 format.",
                            "example": "+11234567890"
                          },
                          "address": {
                            "type": "object",
                            "description": "",
                            "properties": {
                              "street": {
                                "type": "string",
                                "maxLength": 46,
                                "description": "First line of the user's billing address.",
                                "example": "100 Main Street"
                              },
                              "street2": {
                                "type": "string",
                                "maxLength": 46,
                                "description": "Second line of the user's billing address (e.g apt. #).",
                                "example": "#100"
                              },
                              "city": {
                                "type": "string",
                                "maxLength": 32,
                                "description": "City portion of the user's billing address.",
                                "example": "New York"
                              },
                              "region": {
                                "type": "string",
                                "description": "Region portion of the user's billing address, usually a state abbreviation. Must be an ISO 3166-2 sub-division code.",
                                "example": "NY"
                              },
                              "postal_code": {
                                "type": "string",
                                "maxLength": 10,
                                "minLength": 5,
                                "description": "Postal code of the user's billing address.",
                                "example": "12345"
                              },
                              "country": {
                                "type": "string",
                                "description": "Country portion of the user's billing address. Must be an ISO 3166-1 alpha-2 code.",
                                "example": "US"
                              }
                            },
                            "required": [
                              "street",
                              "city",
                              "region",
                              "postal_code",
                              "country"
                            ]
                          }
                        },
                        "required": [
                          "name",
                          "phone_number",
                          "address"
                        ]
                      },
                      "card": {
                        "type": "object",
                        "description": "",
                        "properties": {
                          "number": {
                            "type": "string",
                            "description": "User's valid card number without spaces or hyphens.",
                            "example": "4242424242424242"
                          },
                          "expiration": {
                            "type": "string",
                            "description": "User's card expiration date. Must be MM/YYYY or MM/YY format (e.g. 08/2027).",
                            "example": "08/2025"
                          },
                          "cvv": {
                            "type": "string",
                            "maxLength": 4,
                            "description": "User's card verification value.",
                            "example": "123"
                          }
                        },
                        "required": [
                          "number",
                          "expiration",
                          "cvv"
                        ]
                      },
                      "task_id": {
                        "type": "string",
                        "description": "`task_id` value provided in the [`AUTHENTICATED`](/link/webhook-events/authenticated) webhook.",
                        "example": "123456"
                      }
                    },
                    "required": ["user", "card", "task_id"]
                  },
                  {
                    "title": "CardUpdater",
                    "type": "object",
                    "properties": {
                      "user": {
                        "type": "object",
                        "description": "",
                        "properties": {
                          "name": {
                            "type": "object",
                            "description": "",
                            "properties": {
                              "first_name": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "User's first name.",
                                "example": "Ada"
                              },
                              "last_name": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "User's last name.",
                                "example": "Lovelace"
                              }
                            },
                            "required": [
                              "first_name",
                              "last_name"
                            ]
                          },
                          "phone_number": {
                            "type": "string",
                            "description": "User's phone number in E.164 format.",
                            "example": "+11234567890"
                          },
                          "address": {
                            "type": "object",
                            "description": "",
                            "properties": {
                              "street": {
                                "type": "string",
                                "maxLength": 46,
                                "description": "First line of the user's billing address.",
                                "example": "100 Main Street"
                              },
                              "street2": {
                                "type": "string",
                                "maxLength": 46,
                                "description": "Second line of the user's billing address (e.g apt. #).",
                                "example": "#100"
                              },
                              "city": {
                                "type": "string",
                                "maxLength": 32,
                                "description": "City portion of the user's billing address.",
                                "example": "New York"
                              },
                              "region": {
                                "type": "string",
                                "description": "Region portion of the user's billing address, usually a state abbreviation. Must be an ISO 3166-2 sub-division code.",
                                "example": "NY"
                              },
                              "postal_code": {
                                "type": "string",
                                "maxLength": 10,
                                "minLength": 5,
                                "description": "Postal code of the user's billing address.",
                                "example": "12345"
                              },
                              "country": {
                                "type": "string",
                                "description": "Country portion of the user's billing address. Must be an ISO 3166-1 alpha-2 code.",
                                "example": "US"
                              }
                            },
                            "required": [
                              "street",
                              "city",
                              "region",
                              "postal_code",
                              "country"
                            ]
                          }
                        },
                        "required": [
                          "name",
                          "phone_number",
                          "address"
                        ]
                      },
                      "card": {
                        "type": "object",
                        "description": "",
                        "properties": {
                          "number": {
                            "type": "string",
                            "description": "User's valid card number without spaces or hyphens.",
                            "example": "4242424242424242"
                          },
                          "expiration": {
                            "type": "string",
                            "description": "User's card expiration date. Must be MM/YYYY or MM/YY format (e.g. 08/2027).",
                            "example": "08/2025"
                          },
                          "cvv": {
                            "type": "string",
                            "maxLength": 4,
                            "description": "User's card verification value.",
                            "example": "123"
                          }
                        },
                        "required": [
                          "number",
                          "expiration",
                          "cvv"
                        ]
                      },
                      "external_user_id": {
                        "type": "string",
                        "description": "Your unique identifier for the user.",
                        "example": "abc123"
                      },
                      "merchant_id": {
                        "type": "integer",
                        "description": "Unique identifier for the merchant.",
                        "example": 46
                      },
                      "card_name": {
                        "type": "string",
                        "description": "Name of the card. Learn more [here](/sdk/ios#customerconfiguration).",
                        "example": "My Credit Card"
                      },
                      "customer_name": {
                        "type": "string",
                        "description": "Name of the customer. Learn more [here](/sdk/ios#customerconfiguration).",
                        "example": "John Doe"
                      }
                    },
                    "required": ["user", "card", "external_user_id", "merchant_id"]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Success message.",
                      "example": "Success"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UserFieldRequired": {
                    "summary": "User object field required",
                    "value": {
                      "error_type": "INVALID_REQUEST",
                      "error_code": "INVALID_FIELD",
                      "error_message": "The user.phone number is required."
                    }
                  },
                  "CardNumberNotNumeric": {
                    "summary": "Card number not numeric.",
                    "value": {
                      "error_type": "INVALID_REQUEST",
                      "error_code": "INVALID_FIELD",
                      "error_message": "The card.number must be numeric."
                    }
                  },
                  "CardNumberTooLong": {
                    "summary": "Card number too long.",
                    "value": {
                      "error_type": "INVALID_REQUEST",
                      "error_code": "INVALID_FIELD",
                      "error_message": "The card.number is too long for card type."
                    }
                  },
                  "CardNumberTooShort": {
                    "summary": "Card number too short.",
                    "value": {
                      "error_type": "INVALID_REQUEST",
                      "error_code": "INVALID_FIELD",
                      "error_message": "The card.number is too short for card type."
                    }
                  },
                  "CardNumberInvalid": {
                    "summary": "Card number invalid.",
                    "value": {
                      "error_type": "INVALID_REQUEST",
                      "error_code": "INVALID_FIELD",
                      "error_message": "The card.number is invalid and does not pass the Luhn check."
                    }
                  },
                  "CVVNotNumeric": {
                    "summary": "CVV not numeric",
                    "value": {
                      "error_type": "INVALID_REQUEST",
                      "error_code": "INVALID_FIELD",
                      "error_message": "The card.cvv must be numeric."
                    }
                  },
                  "CVVTooLong": {
                    "summary": "CVV to long.",
                    "value": {
                      "error_type": "INVALID_REQUEST",
                      "error_code": "INVALID_FIELD",
                      "error_message": "The card.cvv is too long for card type."
                    }
                  },
                  "CVVTooShort": {
                    "summary": "CVV to short.",
                    "value": {
                      "error_type": "INVALID_REQUEST",
                      "error_code": "INVALID_FIELD",
                      "error_message": "The card.cvv is too short for card type."
                    }
                  },
                  "CardExpirationInvalid": {
                    "summary": "Card expiration invalid.",
                    "value": {
                      "error_type": "INVALID_REQUEST",
                      "error_code": "INVALID_FIELD",
                      "error_message": "The card.expiration should be in MM/YYYY or MM/YY format."
                    }
                  },
                  "CardExpired": {
                    "summary": "Card expired.",
                    "value": {
                      "error_type": "INVALID_REQUEST",
                      "error_code": "INVALID_FIELD",
                      "error_message": "The card is expired."
                    }
                  },
                  "OngoingOperation": {
                    "summary": "There is an existing operation",
                    "value": {
                      "error_type": "MERCHANT_ACCOUNT_ERROR",
                      "error_code": "ONGOING_OPERATION",
                      "error_message": "An existing operation is in progress."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "AuthFailed": {
                    "summary": "Auth failed",
                    "value": {
                      "error_type": "INVALID_INPUT",
                      "error_code": "INVALID_API_KEYS",
                      "error_message": "Invalid client_id or secret provided."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NoAccess": {
                    "summary": "No access",
                    "value": {
                      "error_type": "INVALID_REQUEST",
                      "error_code": "NO_ACCESS",
                      "error_message": "Please contact Knot for access to this endpoint."
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Merchant": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique identifier for the merchant.",
            "example": 4
          },
          "name": {
            "type": "string",
            "description": "Name of the merchant.",
            "example": "Walmart"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error_type": {
            "type": "string",
            "description": "Type of error.",
            "example": "INVALID_REQUEST"
          },
          "error_code": {
            "type": "string",
            "description": "Error code.",
            "example": "INVALID_FIELD"
          },
          "error_message": {
            "type": "string",
            "description": "Detailed error message.",
            "example": "The user.name.first_name must not be greater than 255 characters."
          }
        }
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  }
}