{
  "openapi": "3.1.0",
  "info": {
    "title": "Runware API - Model Search",
    "version": "1.0.0",
    "description": "Search for models."
  },
  "servers": [
    {
      "url": "https://api.runware.ai/v1",
      "description": "Runware REST API"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Runware API Key (e.g., Bearer <your-key>)"
      }
    },
    "schemas": {
      "AuthenticationTask": {
        "title": "Authentication",
        "description": "Authenticates a connection using an API key. Can be sent as the first element of the request array as an alternative to using the Authorization header.",
        "type": "object",
        "x-response-schema": "https://schemas.runware.ai/responses/utilities/authentication.json",
        "properties": {
          "taskType": {
            "title": "Task Type",
            "description": "Identifier for the type of task being performed.",
            "type": "string",
            "const": "authentication"
          },
          "apiKey": {
            "title": "API Key",
            "description": "Your Runware API key.",
            "type": "string"
          },
          "connectionSessionUUID": {
            "title": "Connection Session UUID",
            "description": "Optional session UUID to resume a previous connection and receive any buffered results.",
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "taskType",
          "apiKey"
        ],
        "additionalProperties": false
      },
      "RequestBody": {
        "type": "array",
        "items": {
          "title": "Model Search",
          "description": "Search for models.",
          "type": "object",
          "properties": {
            "taskType": {
              "title": "Task Type",
              "description": "Identifier for the type of task being performed.",
              "type": "string",
              "const": "modelSearch"
            },
            "taskUUID": {
              "title": "Task UUID",
              "description": "UUID v4 identifier for tracking tasks and matching async responses. Must be unique per task.",
              "type": "string",
              "format": "uuid"
            },
            "search": {
              "title": "Search",
              "description": "Search query to find models by name, description or AIR ID.",
              "type": "string",
              "maxLength": 48,
              "anyOf": [
                {
                  "maxLength": 0
                },
                {
                  "minLength": 2
                }
              ]
            },
            "source": {
              "title": "Source",
              "description": "Filter by model source.",
              "type": "string",
              "enum": [
                "official",
                "community"
              ]
            },
            "category": {
              "title": "Category",
              "description": "Filter models by category.",
              "type": "string",
              "enum": [
                "checkpoint",
                "lora",
                "lycoris",
                "vae",
                "embeddings"
              ]
            },
            "architecture": {
              "title": "Architecture",
              "description": "Filter by model architecture.",
              "type": "string"
            },
            "capabilities": {
              "title": "Capabilities",
              "description": "Filter by model capabilities.",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "visibility": {
              "title": "Visibility",
              "description": "Filter by visibility status.",
              "type": "string",
              "enum": [
                "public",
                "private",
                "favorite",
                "owned"
              ]
            },
            "limit": {
              "title": "Limit",
              "description": "Maximum number of results to return.",
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "offset": {
              "title": "Offset",
              "description": "Number of results to skip for pagination.",
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "sort": {
              "title": "Sort",
              "description": "Sort order for results. A bare field name sorts ascending and a `-` prefix sorts descending, except `popularity`, whose bare value is already descending (most popular first). `_score` sorts by search relevance and has no descending form. Defaults to `_score` when `search` is non-empty, and to `popularity` otherwise.",
              "type": "string",
              "enum": [
                "_score",
                "popularity",
                "-popularity",
                "name",
                "-name",
                "addedUnixTimestamp",
                "-addedUnixTimestamp",
                "updatedDateUnixTimestamp",
                "-updatedDateUnixTimestamp"
              ]
            }
          },
          "required": [
            "taskType",
            "taskUUID"
          ],
          "allOf": [
            {
              "if": {
                "properties": {
                  "category": {
                    "const": "checkpoint"
                  }
                },
                "required": [
                  "category"
                ]
              },
              "then": {
                "properties": {
                  "architecture": {
                    "enum": [
                      "exactlyai_image",
                      "flux1d",
                      "flux1s",
                      "fluxkontextdev",
                      "illustrious",
                      "krea_oss_2",
                      "krea_oss_2_turbo",
                      "noobai",
                      "pony",
                      "sd1x",
                      "sdxl",
                      "sdxllightning",
                      "sdxlturbo",
                      "z_image",
                      "z_image_turbo"
                    ]
                  }
                }
              }
            },
            {
              "if": {
                "properties": {
                  "category": {
                    "const": "lora"
                  }
                },
                "required": [
                  "category"
                ]
              },
              "then": {
                "properties": {
                  "architecture": {
                    "enum": [
                      "flux1d",
                      "flux1s",
                      "flux2klein_4b",
                      "flux2klein_9b",
                      "flux2klein_base_4b",
                      "flux2klein_base_9b",
                      "flux_2_dev",
                      "fluxkontextdev",
                      "hidreamdev",
                      "hidreamfast",
                      "hidreamfull",
                      "illustrious",
                      "krea_oss_2",
                      "krea_oss_2_turbo",
                      "ltx_2_3_video",
                      "noobai",
                      "pony",
                      "qwen_image",
                      "qwen_image_edit",
                      "qwen_image_edit_plus",
                      "qwen_image_layered",
                      "sd1x",
                      "sd3",
                      "sdxl",
                      "sdxllightning",
                      "sdxlturbo",
                      "z_image",
                      "z_image_turbo"
                    ]
                  }
                }
              }
            },
            {
              "if": {
                "properties": {
                  "category": {
                    "const": "lycoris"
                  }
                },
                "required": [
                  "category"
                ]
              },
              "then": {
                "properties": {
                  "architecture": {
                    "enum": [
                      "flux1d",
                      "flux1s",
                      "flux2klein_4b",
                      "flux2klein_9b",
                      "flux2klein_base_4b",
                      "flux2klein_base_9b",
                      "flux_2_dev",
                      "fluxkontextdev",
                      "hidreamdev",
                      "hidreamfast",
                      "hidreamfull",
                      "illustrious",
                      "noobai",
                      "pony",
                      "qwen_image",
                      "qwen_image_edit",
                      "qwen_image_edit_plus",
                      "qwen_image_layered",
                      "sd1x",
                      "sd3",
                      "sdxl",
                      "sdxllightning",
                      "sdxlturbo",
                      "z_image",
                      "z_image_turbo"
                    ]
                  }
                }
              }
            },
            {
              "if": {
                "properties": {
                  "category": {
                    "const": "vae"
                  }
                },
                "required": [
                  "category"
                ]
              },
              "then": {
                "properties": {
                  "architecture": {
                    "enum": [
                      "illustrious",
                      "noobai",
                      "pony",
                      "sd1x",
                      "sdxl",
                      "sdxllightning",
                      "sdxlturbo"
                    ]
                  }
                }
              }
            },
            {
              "if": {
                "properties": {
                  "category": {
                    "const": "embeddings"
                  }
                },
                "required": [
                  "category"
                ]
              },
              "then": {
                "properties": {
                  "architecture": {
                    "enum": [
                      "illustrious",
                      "noobai",
                      "pony",
                      "sd1x",
                      "sdxl",
                      "sdxllightning",
                      "sdxlturbo"
                    ]
                  }
                }
              }
            }
          ],
          "additionalProperties": false
        },
        "description": "You must always POST an array of task objects."
      },
      "ResponseBody": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "title": "Model Search Response",
              "type": "object",
              "properties": {
                "taskType": {
                  "title": "Task Type",
                  "description": "Identifier for the type of task this response belongs to.",
                  "type": "string",
                  "const": "modelSearch"
                },
                "taskUUID": {
                  "title": "Task UUID",
                  "description": "UUID v4 identifier echoed from the original request, used to match async responses to their tasks.",
                  "type": "string",
                  "format": "uuid"
                },
                "totalResults": {
                  "title": "Total Results",
                  "description": "Total number of models matching the search criteria.",
                  "type": "integer",
                  "minimum": 0
                },
                "results": {
                  "title": "Results",
                  "description": "List of models found.",
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "air": {
                        "title": "AIR",
                        "description": "Artificial Intelligence Resource identifier.",
                        "type": "string"
                      },
                      "name": {
                        "title": "Name",
                        "description": "Model name.",
                        "type": "string"
                      },
                      "category": {
                        "title": "Category",
                        "description": "Model category.",
                        "type": "string",
                        "enum": [
                          "checkpoint",
                          "lora",
                          "lycoris",
                          "vae",
                          "embeddings"
                        ]
                      },
                      "architecture": {
                        "title": "Architecture",
                        "description": "Model architecture.",
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "capabilities": {
                        "title": "Capabilities",
                        "description": "Model capabilities.",
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "source": {
                        "title": "Source",
                        "description": "Model source.",
                        "type": "string",
                        "enum": [
                          "official",
                          "community"
                        ]
                      },
                      "heroImage": {
                        "title": "Hero Image",
                        "description": "Representative image URL.",
                        "type": [
                          "string",
                          "null"
                        ],
                        "format": "uri"
                      },
                      "private": {
                        "title": "Private",
                        "description": "Whether the model is private.",
                        "type": "boolean"
                      },
                      "isFavorite": {
                        "title": "Is Favorite",
                        "description": "Whether the model is favorited.",
                        "type": "boolean"
                      },
                      "provider": {
                        "title": "Provider",
                        "description": "Model provider.",
                        "type": "string"
                      },
                      "shortDescription": {
                        "title": "Short Description",
                        "description": "Short description.",
                        "type": "string"
                      },
                      "positiveTriggerWords": {
                        "title": "Positive Trigger Words",
                        "description": "Positive trigger words.",
                        "type": "string"
                      },
                      "negativeTriggerWords": {
                        "title": "Negative Trigger Words",
                        "description": "Negative trigger words.",
                        "type": "string"
                      },
                      "comment": {
                        "title": "Comment",
                        "description": "Additional comments or notes.",
                        "type": "string"
                      },
                      "type": {
                        "title": "Type",
                        "description": "Checkpoint type.",
                        "type": "string",
                        "enum": [
                          "base",
                          "inpainting",
                          "refiner",
                          "pix2pix"
                        ]
                      },
                      "version": {
                        "title": "Version",
                        "description": "Version of the model.",
                        "type": "string"
                      },
                      "tags": {
                        "title": "Tags",
                        "description": "Tags associated with the model.",
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "addedUnixTimestamp": {
                        "title": "Added Unix Timestamp",
                        "description": "Unix timestamp of when the model was added.",
                        "type": "integer",
                        "minimum": 0
                      },
                      "updatedDateUnixTimestamp": {
                        "title": "Updated Date Unix Timestamp",
                        "description": "Unix timestamp of when the model was last updated.",
                        "type": "integer",
                        "minimum": 0
                      },
                      "floatingPoint": {
                        "title": "Floating Point",
                        "description": "Floating point precision of the model weights.",
                        "type": "string"
                      },
                      "uniqueIdentifier": {
                        "title": "Unique Identifier",
                        "description": "Unique identifier for the model.",
                        "type": "string"
                      },
                      "defaultWidth": {
                        "title": "Default Width",
                        "description": "Default output width.",
                        "type": [
                          "integer",
                          "null"
                        ]
                      },
                      "defaultHeight": {
                        "title": "Default Height",
                        "description": "Default output height.",
                        "type": [
                          "integer",
                          "null"
                        ]
                      },
                      "defaultSteps": {
                        "title": "Default Steps",
                        "description": "Default number of inference steps.",
                        "type": "integer"
                      },
                      "defaultCFG": {
                        "title": "Default CFG",
                        "description": "Default classifier-free guidance scale.",
                        "type": "number"
                      },
                      "defaultScheduler": {
                        "title": "Default Scheduler",
                        "description": "Default scheduler.",
                        "type": "string"
                      },
                      "defaultStrength": {
                        "title": "Default Strength",
                        "description": "Default strength for img2img.",
                        "type": "number"
                      },
                      "defaultWeight": {
                        "title": "Default Weight",
                        "description": "Default weight for the model.",
                        "type": "number"
                      },
                      "defaultFPS": {
                        "title": "Default FPS",
                        "description": "Default frames per second.",
                        "type": "integer"
                      },
                      "defaultNumberOfFrames": {
                        "title": "Default Number of Frames",
                        "description": "Default number of frames.",
                        "type": "integer"
                      },
                      "defaultDuration": {
                        "title": "Default Duration",
                        "description": "Default duration in seconds.",
                        "type": "number"
                      }
                    },
                    "required": [
                      "air",
                      "name",
                      "category",
                      "architecture",
                      "capabilities",
                      "source",
                      "heroImage",
                      "private"
                    ],
                    "additionalProperties": true,
                    "allOf": [
                      {
                        "if": {
                          "properties": {
                            "source": {
                              "const": "official"
                            }
                          },
                          "required": [
                            "source"
                          ]
                        },
                        "then": {
                          "properties": {
                            "version": false,
                            "tags": false,
                            "addedUnixTimestamp": false,
                            "updatedDateUnixTimestamp": false,
                            "floatingPoint": false,
                            "uniqueIdentifier": false,
                            "defaultWidth": false,
                            "defaultHeight": false,
                            "defaultSteps": false,
                            "defaultCFG": false,
                            "defaultScheduler": false,
                            "defaultStrength": false,
                            "defaultWeight": false,
                            "defaultFPS": false,
                            "defaultNumberOfFrames": false,
                            "defaultDuration": false
                          }
                        }
                      },
                      {
                        "if": {
                          "properties": {
                            "category": {
                              "not": {
                                "const": "checkpoint"
                              }
                            }
                          },
                          "required": [
                            "category"
                          ]
                        },
                        "then": {
                          "properties": {
                            "type": false
                          }
                        }
                      }
                    ]
                  }
                }
              },
              "required": [
                "taskType",
                "taskUUID",
                "totalResults",
                "results"
              ],
              "additionalProperties": true
            }
          }
        }
      },
      "ErrorResponse": {
        "title": "Error Response",
        "description": "Standard error response returned by the Runware API.",
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "code",
                "message"
              ],
              "additionalProperties": true,
              "properties": {
                "code": {
                  "type": "string",
                  "description": "A short identifier for the error (e.g., invalidApiKey, timeoutProvider)."
                },
                "message": {
                  "type": "string",
                  "description": "A human-readable explanation of what went wrong."
                },
                "parameter": {
                  "type": "string",
                  "description": "The request parameter related to the error, if applicable."
                },
                "taskType": {
                  "type": "string",
                  "description": "The task type of the request that failed."
                },
                "taskUUID": {
                  "type": "string",
                  "description": "The unique identifier of the failed request."
                },
                "documentation": {
                  "type": "string",
                  "description": "A link to relevant documentation."
                }
              }
            }
          }
        },
        "required": [
          "errors"
        ],
        "additionalProperties": false
      }
    }
  },
  "paths": {
    "/": {
      "post": {
        "summary": "Run Model Search",
        "description": "Search for models.",
        "operationId": "run_model_search",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResponseBody"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request — Missing or invalid parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — No valid API key provided.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required — Insufficient account balance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — The API key lacks permissions for this request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests — Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server Error — Something went wrong on Runware's end.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable — Temporarily unavailable (maintenance or capacity).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "apiKeyAuth": []
    }
  ]
}