{
 "components": {
  "schemas": {
   "Error": {
    "properties": {
     "error": {
      "type": "string"
     },
     "message": {
      "type": "string"
     },
     "request_id": {
      "type": "string"
     }
    },
    "type": "object"
   },
   "Results": {
    "properties": {
     "results": {
      "items": {
       "properties": {
        "assets": {
         "description": "Algorand assets referencing the CID (up to 5)",
         "items": {
          "properties": {
           "asset": {
            "description": "ASA id",
            "type": "integer"
           },
           "depth": {
            "description": "0 = the asset's own URL, 1 = inside its metadata",
            "type": "integer"
           },
           "key": {
            "description": "where the asset references it (url, ARC-19, ARC-69 media...)",
            "type": "string"
           }
          },
          "type": "object"
         },
         "type": "array"
        },
        "cid": {
         "description": "IPFS CID (fetch via any IPFS gateway)",
         "type": "string"
        },
        "mime": {
         "type": "string"
        },
        "score": {
         "description": "cosine similarity, higher is closer",
         "type": "number"
        }
       },
       "type": "object"
      },
      "type": "array"
     }
    },
    "type": "object"
   }
  }
 },
 "info": {
  "description": "Semantic search over the images of Algorand NFTs (every image in Nodely's IPFS cache, embedded with Qwen3-VL-Embedding-2B): by text, by an uploaded image, or similar to a cached CID. Paid per call with x402 (exact scheme, USDC ASA 31566704 on Algorand, 0.005 USDC per call, payTo X4O2COYWOFR7XS3EOYEF6MG42Y4Q743SKZMULC776NODRTMMRIVTCOBANQ). An unpaid call answers 402 with the PAYMENT-REQUIRED offer; a bad request, an unknown CID and a failed search are never charged. The network fee is sponsored (extra.feePayer X4O2STHZWIA425GOSCKVW3KY6IAW3F6SSV5AZ23HOYFLKCDRTHKWUYNDLY): the payer signs only the USDC transfer, with fee 0.",
  "title": "Nodely NFT Image Search (x402)",
  "version": "1"
 },
 "openapi": "3.1.0",
 "paths": {
  "/v1/images/health": {
   "get": {
    "operationId": "imagesHealth",
    "responses": {
     "200": {
      "description": "OK"
     }
    },
    "summary": "Service and algod health (free)",
    "tags": [
     "status"
    ]
   }
  },
  "/v1/images/pricing": {
   "get": {
    "operationId": "imagesPricing",
    "responses": {
     "200": {
      "description": "OK"
     }
    },
    "summary": "Paid resources and their prices (free)",
    "tags": [
     "status"
    ]
   }
  },
  "/v1/images/search": {
   "get": {
    "description": "Semantic search over the images of every Algorand NFT cached by Nodely's IPFS cache: a text query (any language) is embedded with Qwen3-VL-Embedding-2B and answered with the nearest images, their IPFS CIDs, cosine scores and the Algorand assets (ASA ids) that reference them.",
    "operationId": "imagesSearch",
    "parameters": [
     {
      "description": "Text query, 1-1000 characters.",
      "example": "a pixel art frog wearing a crown",
      "in": "query",
      "name": "q",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "description": "Number of results, 1-100 (default 20).",
      "example": "10",
      "in": "query",
      "name": "k",
      "schema": {
       "type": "string"
      }
     },
     {
      "description": "0 = leave out the referencing Algorand assets (faster).",
      "in": "query",
      "name": "assets",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "example": {
         "results": [
          {
           "assets": [
            {
             "asset": 1009172393,
             "depth": 0,
             "key": "url"
            }
           ],
           "cid": "bafkreibmgkbwqebpwptrqn3ypxqifvwcyh5mv4lnf7cnw5zidasplwhgqy",
           "mime": "image/png",
           "score": 0.4123
          }
         ]
        },
        "schema": {
         "$ref": "#/components/schemas/Results"
        }
       }
      },
      "description": "Nearest images"
     },
     "400": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      },
      "description": "Bad parameter (not charged)"
     },
     "402": {
      "description": "Payment required: x402 offer in the PAYMENT-REQUIRED header (base64 JSON; the same JSON is the body). Retry with PAYMENT-SIGNATURE."
     },
     "503": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      },
      "description": "The embedding model or the index did not answer (not charged)"
     }
    },
    "summary": "Search NFT images by text",
    "tags": [
     "images"
    ]
   },
   "post": {
    "description": "Reverse image search over the images of every Algorand NFT cached by Nodely's IPFS cache: the uploaded image (png, jpeg, gif, webp, bmp up to 16 MiB; raw body with an image/* Content-Type, or JSON {\"image\": base64 or data URL}) is embedded with Qwen3-VL-Embedding-2B and answered with the visually and semantically nearest images, their CIDs, scores and referencing assets.",
    "operationId": "imagesSearchImage",
    "parameters": [
     {
      "description": "Number of results, 1-100 (default 20).",
      "example": "10",
      "in": "query",
      "name": "k",
      "schema": {
       "type": "string"
      }
     },
     {
      "description": "0 = leave out the referencing Algorand assets (faster).",
      "in": "query",
      "name": "assets",
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "properties": {
         "image": {
          "description": "base64 image or data URL",
          "type": "string"
         }
        },
        "required": [
         "image"
        ],
        "type": "object"
       }
      },
      "image/*": {
       "schema": {
        "format": "binary",
        "type": "string"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "example": {
         "results": [
          {
           "assets": [
            {
             "asset": 1009172393,
             "depth": 0,
             "key": "url"
            }
           ],
           "cid": "bafkreibmgkbwqebpwptrqn3ypxqifvwcyh5mv4lnf7cnw5zidasplwhgqy",
           "mime": "image/png",
           "score": 0.4123
          }
         ]
        },
        "schema": {
         "$ref": "#/components/schemas/Results"
        }
       }
      },
      "description": "Nearest images"
     },
     "400": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      },
      "description": "Bad parameter (not charged)"
     },
     "402": {
      "description": "Payment required: x402 offer in the PAYMENT-REQUIRED header (base64 JSON; the same JSON is the body). Retry with PAYMENT-SIGNATURE."
     },
     "415": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      },
      "description": "Not a supported image (not charged)"
     },
     "503": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      },
      "description": "The embedding model or the index did not answer (not charged)"
     }
    },
    "summary": "Search NFT images by an image",
    "tags": [
     "images"
    ]
   }
  },
  "/v1/images/similar/{cid}": {
   "get": {
    "description": "More like this: the images of Algorand NFTs nearest to an image already in Nodely's IPFS cache (by its CID), excluding that image's own content. An unknown or not yet embedded CID answers 404 and is not charged.",
    "operationId": "imagesSimilar",
    "parameters": [
     {
      "description": "IPFS CID of an image in the cache",
      "in": "path",
      "name": "cid",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "description": "Number of results, 1-100 (default 20).",
      "example": "10",
      "in": "query",
      "name": "k",
      "schema": {
       "type": "string"
      }
     },
     {
      "description": "0 = leave out the referencing Algorand assets (faster).",
      "in": "query",
      "name": "assets",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "example": {
         "results": [
          {
           "assets": [
            {
             "asset": 1009172393,
             "depth": 0,
             "key": "url"
            }
           ],
           "cid": "bafkreibmgkbwqebpwptrqn3ypxqifvwcyh5mv4lnf7cnw5zidasplwhgqy",
           "mime": "image/png",
           "score": 0.4123
          }
         ]
        },
        "schema": {
         "$ref": "#/components/schemas/Results"
        }
       }
      },
      "description": "Nearest images"
     },
     "400": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      },
      "description": "Bad parameter (not charged)"
     },
     "402": {
      "description": "Payment required: x402 offer in the PAYMENT-REQUIRED header (base64 JSON; the same JSON is the body). Retry with PAYMENT-SIGNATURE."
     },
     "404": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      },
      "description": "CID not an embedded image of the cache (not charged)"
     },
     "503": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      },
      "description": "The embedding model or the index did not answer (not charged)"
     }
    },
    "summary": "NFT images similar to a cached image",
    "tags": [
     "images"
    ]
   }
  }
 },
 "servers": [
  {
   "url": "https://x402.api.nodely.io"
  }
 ]
}