{
  "openapi": "3.1.1",
  "info": {
    "title": "Reverse Video Search \u2014 Image Search API",
    "version": "1.0.0",
    "description": "Documents the existing account-authenticated endpoint. Searches spend credits and store images/results. No dedicated agent API keys or MCP transport.",
    "termsOfService": "https://reverse-video-search.com/terms"
  },
  "servers": [
    {
      "url": "https://reverse-video-search.com"
    }
  ],
  "externalDocs": {
    "url": "https://reverse-video-search.com/developers"
  },
  "components": {
    "securitySchemes": {
      "accountSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "Existing session access token supplied by the account owner; never put it in a URL."
      }
    }
  },
  "paths": {
    "/api/search/single-image": {
      "post": {
        "operationId": "searchImage",
        "summary": "Reverse-search an image or extracted video frame",
        "description": "Spends account credits. Obtain authorization for the cost before calling. Does not accept videos. Do not automatically retry ambiguous failures; inspect account history first.",
        "security": [
          {
            "accountSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "providers"
                ],
                "oneOf": [
                  {
                    "required": [
                      "image_url"
                    ],
                    "not": {
                      "required": [
                        "image"
                      ]
                    }
                  },
                  {
                    "required": [
                      "image"
                    ],
                    "not": {
                      "required": [
                        "image_url"
                      ]
                    }
                  }
                ],
                "properties": {
                  "image_url": {
                    "type": "string",
                    "format": "uri",
                    "pattern": "^https?://",
                    "description": "Publicly reachable image URL; internal addresses are rejected."
                  },
                  "image": {
                    "type": "string",
                    "pattern": "^data:image/[a-zA-Z]+;base64,[A-Za-z0-9+/]+={0,2}$"
                  },
                  "providers": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 3,
                    "items": {
                      "type": "string",
                      "enum": [
                        "serpapi_reverse",
                        "yandex_reverse",
                        "bing_reverse"
                      ]
                    }
                  },
                  "force": {
                    "type": "boolean",
                    "default": false,
                    "description": "Bypasses duplicate detection and can charge again. Duplicate detection is not an idempotency guarantee."
                  }
                }
              },
              "example": {
                "image_url": "https://example.com/frame.png",
                "providers": [
                  "serpapi_reverse"
                ],
                "force": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search completed (possibly partial_failure), or a duplicate was found. Inspect payload and each provider status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "meta",
                    "payload"
                  ],
                  "properties": {
                    "error": {
                      "type": "null"
                    },
                    "meta": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "payload": {
                      "oneOf": [
                        {
                          "type": "object",
                          "required": [
                            "id",
                            "status",
                            "results",
                            "total_charged"
                          ],
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "status": {
                              "enum": [
                                "completed",
                                "partial_failure"
                              ]
                            },
                            "image_url": {
                              "type": "string",
                              "format": "uri"
                            },
                            "image_hash": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "balance_after": {
                              "type": "number"
                            },
                            "total_charged": {
                              "type": "number"
                            },
                            "results": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "required": [
                                  "provider",
                                  "status"
                                ],
                                "properties": {
                                  "provider": {
                                    "type": "string"
                                  },
                                  "status": {
                                    "type": "string",
                                    "enum": [
                                      "ok",
                                      "empty",
                                      "error"
                                    ]
                                  },
                                  "matches": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "additionalProperties": true
                                    }
                                  },
                                  "match_count": {
                                    "type": "integer"
                                  },
                                  "credits_charged": {
                                    "type": "number"
                                  },
                                  "credits_refunded": {
                                    "type": "number"
                                  },
                                  "error": {
                                    "type": "string"
                                  },
                                  "fallback_provider": {
                                    "type": "string"
                                  }
                                }
                              }
                            }
                          }
                        },
                        {
                          "type": "object",
                          "required": [
                            "duplicate",
                            "existing"
                          ],
                          "properties": {
                            "duplicate": {
                              "const": true
                            },
                            "existing": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "kind": {
                                  "const": "single_image"
                                },
                                "total_matches": {
                                  "type": "integer"
                                },
                                "image_url": {
                                  "type": "string"
                                },
                                "providers": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                }
                              }
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "No valid providers or unsafe image URL",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "type"
                      ],
                      "properties": {
                        "type": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or expired account session",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "type"
                      ],
                      "properties": {
                        "type": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "type"
                      ],
                      "properties": {
                        "type": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Provider not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "type"
                      ],
                      "properties": {
                        "type": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "type"
                      ],
                      "properties": {
                        "type": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server failure; do not blindly retry a credit-spending request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "type"
                      ],
                      "properties": {
                        "type": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}