# Search

## Asset Search

**post** `/search/assets`

Search for assets.
At least one of the following fields must have a value: `query`, `filter`, `image`, or `images`.

`image`, `images` are mutually exclusive.

### Query Parameters

- `originalAssets: optional boolean`

  If set to true, returns the original asset without transformation

### Body Parameters

- `filter: optional string`

  Filter queries by an attribute's value

- `hitsPerPage: optional number`

  Maximum number of documents returned for a page. Must be used with `page`.

- `image: optional string`

  Search for similar images with `image` as a reference.

  Must be an existing `AssetId` or a valid data URL.

- `images: optional object { like, unlike }`

  Search for similar images with `images.like` and `images.unlike` as a reference

  Must be arrays of existing `AssetId` or valid data URLs.

  - `like: optional array of string`

    Search for similar images with `images.like` as a reference.

    Must be an array of existing `AssetId` or valid data URLs.

  - `unlike: optional array of string`

    Search for images that are not similar to `images.unlike` as a reference.

    Must be an array of existing `AssetId` or valid data URLs.

- `imageSemanticRatio: optional number`

  Image embedding ratio for hybrid search, applied when `image`, `images.like`, or `images.unlike`
  are provided

- `limit: optional number`

  Maximum number of documents returned. Must be used with `offset`.

- `offset: optional number`

  Number of documents to skip. Must be used with `limit`. Starts from 0.

- `page: optional number`

  Request a specific page of results. Must be used with `hitsPerPage`.

- `public: optional boolean`

  Search for public images not necessarily belonging to the current `ownerId`

- `query: optional string`

  A string used for querying search results.

- `querySemanticRatio: optional number`

  Query embedding for hybrid search, if possible

- `sortBy: optional array of string`

  Sort the search results by the given attributes. Each attribute in the list must be followed by a colon (`:`) and the preferred sorting order: either ascending (`asc`) or descending (`desc`).

  Example: `['createdAt:desc']`

### Returns

- `hits: array of object { id, authorId, collectionIds, 14 more }`

  - `id: string`

    Unique identifier for the asset (e.g., "asset_GTrL3mq4SXWyMxkOHRxlpw")

  - `authorId: string`

    User ID of the asset creator/author

  - `collectionIds: array of string`

    Array of collection IDs this asset belongs to

  - `createdAt: string`

    Creation timestamp in ISO 8601 format (e.g., "2025-01-16T11:19:41.579Z")

  - `metadata: object { aspectRatio, baseModelId, guidance, 17 more }`

    Metadata containing detailed information about the asset's properties and generation parameters

    - `aspectRatio: optional string`

      Aspect ratio of the asset (e.g., "1:1", "16:9")

    - `baseModelId: optional string`

      ID of the base model used for generation

    - `guidance: optional number`

      Guidance scale used for diffusion models to control prompt adherence

    - `height: optional number`

      Height of the asset in pixels

    - `kind: optional string`

      Classification of the asset (e.g., "image", "video")

    - `modelId: optional string`

      ID of the specific model used if asset is model-based

    - `modelType: optional string`

      Type of model used for generation (e.g., "sd-1_5", "flux.1")

    - `name: optional string`

      Custom name given to the asset

    - `negativePrompt: optional string`

      Negative prompt used during generation to specify what to avoid

    - `negativePromptStrength: optional number`

      For Flux models: controls the influence of the negative prompt

    - `numInferenceSteps: optional number`

      Number of inference steps used during generation

    - `parentJobId: optional string`

      ID of the parent job that created this asset

    - `prompt: optional string`

      Text prompt used to generate the asset

    - `scheduler: optional string`

      Scheduler algorithm used during generation

    - `seed: optional string`

      Random seed used for generation, enables reproducibility

    - `size: optional number`

      File size of the asset in bytes

    - `text: optional string`

      Text used to generate the asset: mainly for speech to text

    - `thumbnail: optional object { assetId }`

      Thumbnail image information for the asset. Ex. Canvas thumbnail

      - `assetId: string`

        ID of the asset used as thumbnail

    - `type: optional string`

      Specific type/category of the asset (e.g., "canvas", "inference-txt")

    - `width: optional number`

      Width of the asset in pixels

  - `mimeType: string`

    MIME type of the asset (e.g., "image/png", "image/jpeg")

  - `nsfw: array of string`

    Array of detected NSFW categories

  - `ownerId: string`

    Project ID of the asset owner

  - `privacy: string`

    Privacy setting of the asset ("public", "private", or "unlisted")

  - `tags: array of string`

    Array of user-assigned tags for categorization

  - `teamId: string`

    Team ID of the asset owner

  - `updatedAt: string`

    Last modification timestamp in ISO 8601 format (e.g., "2025-01-16T11:19:41.579Z")

  - `url: string`

    Signed URL of the asset

  - `description: optional string`

    Textual description of the asset. Can be either:

    - User-provided description for training images
    - Automatically generated caption for images and videos assets
    - Automatically generated description for audio assets

  - `score: optional number`

    Score assigned to the asset based on usage and popularity

  - `thumbnail: optional object { assetId, url }`

    Thumbnail preview of the asset 3D, video...

    - `assetId: string`

      ID of the asset used as thumbnail

    - `url: string`

      Signed URL of the thumbnail

  - `transcription: optional string`

    Transcription of the asset. Can be either:

    - Automatically generated transcription for audio assets with speech

- `limit: number`

  Maximum number of documents returned

- `offset: number`

  Number of documents skipped

- `estimatedTotalHits: optional number`

  Estimated total number of hits

- `hitsPerPage: optional number`

  Number of results on each page

- `page: optional number`

  Current search results page

- `totalHits: optional number`

  Exhaustive total number of matches

- `totalPages: optional number`

  Exhaustive total number of search result pages

### Example

```http
curl https://api.cloud.scenario.com/v1/search/assets \
    -H 'Content-Type: application/json' \
    -u "$SCENARIO_SDK_API_KEY:SCENARIO_SDK_API_SECRET" \
    -d '{}'
```

#### Response

```json
{
  "hits": [
    {
      "id": "id",
      "authorId": "authorId",
      "collectionIds": [
        "string"
      ],
      "createdAt": "createdAt",
      "metadata": {
        "aspectRatio": "aspectRatio",
        "baseModelId": "baseModelId",
        "guidance": 0,
        "height": 0,
        "kind": "kind",
        "modelId": "modelId",
        "modelType": "modelType",
        "name": "name",
        "negativePrompt": "negativePrompt",
        "negativePromptStrength": 0,
        "numInferenceSteps": 0,
        "parentJobId": "parentJobId",
        "prompt": "prompt",
        "scheduler": "scheduler",
        "seed": "seed",
        "size": 0,
        "text": "text",
        "thumbnail": {
          "assetId": "assetId"
        },
        "type": "type",
        "width": 0
      },
      "mimeType": "mimeType",
      "nsfw": [
        "string"
      ],
      "ownerId": "ownerId",
      "privacy": "privacy",
      "tags": [
        "string"
      ],
      "teamId": "teamId",
      "updatedAt": "updatedAt",
      "url": "url",
      "description": "description",
      "score": 0,
      "thumbnail": {
        "assetId": "assetId",
        "url": "url"
      },
      "transcription": "transcription"
    }
  ],
  "limit": 0,
  "offset": 0,
  "estimatedTotalHits": 0,
  "hitsPerPage": 0,
  "page": 0,
  "totalHits": 0,
  "totalPages": 0
}
```

## Model Search

**post** `/search/models`

Search for models.
At least one of the following fields must have a value: `query`, `filter`, `image`, or `images`.

`image`, and `images` are mutually exclusive.

### Query Parameters

- `originalAssets: optional boolean`

  If set to true, returns the original asset without transformation

- `originalModels: optional unknown`

### Body Parameters

- `filter: optional string`

  Filter queries by an attribute's value

- `hitsPerPage: optional number`

  Maximum number of documents returned for a page. Must be used with `page`.

- `image: optional string`

  Search for model with `image` as a reference

  Must be an existing `AssetId` or a valid data URL.

- `images: optional object { like, unlike }`

  Search for model with `images.like` and `images.unlike` as a reference

  Must be an array of existing `AssetId` or valid data URLs.

  - `like: optional array of string`

    Search for model images with `images.like` as a reference

    Must be an array of existing `AssetId` or valid data URLs.

  - `unlike: optional array of string`

    Search for model images that are not similar to `images.unlike` as a reference

    Must be an array of existing `AssetId` or valid data URLs.

- `imageSemanticRatio: optional number`

  Image embedding ratio for hybrid search, applied when `image`, `images.like`, or `images.unlike`
  are provided

- `limit: optional number`

  Maximum number of documents returned. Must be used with `offset`.

- `offset: optional number`

  Number of documents to skip. Must be used with `limit`. Starts from 0.

- `page: optional number`

  Request a specific page of results. Must be used with `hitsPerPage`.

- `public: optional boolean`

  Search for public images not necessarily belonging to the current `ownerId`

- `query: optional string`

  A string used for querying search results.

- `querySemanticRatio: optional number`

  Query embedding for hybrid search, if possible

- `sortBy: optional array of string`

  Sort the search results by the given attributes. Each attribute in the list must be followed by a colon (`:`) and the preferred sorting order: either ascending (`asc`) or descending (`desc`).

  Example: `['createdAt:desc']`

### Returns

- `hits: array of object { id, authorId, capabilities, 17 more }`

  - `id: string`

    Unique identifier for the model (e.g., "model_GTrL3mq4SXWyMxkOHRxlpw")

  - `authorId: string`

    User ID of the model creator/author

  - `capabilities: array of string`

    Array of model capabilities

  - `collectionIds: array of string`

    Array of collection IDs this model belongs to

  - `concepts: array of object { modelId }`

    Array of concept models associated with this model
    Each concept contains a reference to its source model

    - `modelId: string`

      ID of the concept's source model

  - `createdAt: string`

    Creation timestamp in ISO 8601 format (e.g., "2025-01-16T11:19:41.579Z")

  - `exampleAssetIds: array of string`

    Array of example asset IDs associated with this model

  - `name: string`

    Display name of the model

  - `ownerId: string`

    Project ID of the model owner

  - `privacy: string`

    Privacy setting of the model ("public", "private", or "unlisted")

  - `shortDescription: string`

    Short description of the model

  - `source: string`

    Source/origin of the model (e.g., "training", "import")

  - `tags: array of string`

    Array of user-assigned tags for categorization

  - `teamId: string`

    Team ID of the model owner

  - `trainingImagesNumber: number`

    Number of images used to train this model

  - `type: string`

    Type of the model (e.g., "sd-1_5", "flux.1")

  - `updatedAt: string`

    Last modification timestamp in ISO 8601 format (e.g., "2025-01-16T11:19:41.579Z")

  - `parentModelId: optional string`

    ID of the parent model this model was derived from

  - `score: optional number`

    Score assigned to the model based on usage and popularity

  - `thumbnail: optional object { assetId, url }`

    Thumbnail image information for the model

    - `assetId: string`

      ID of the asset used as thumbnail

    - `url: string`

      Signed URL of the thumbnail

- `limit: number`

  Maximum number of documents returned

- `offset: number`

  Number of documents skipped

- `estimatedTotalHits: optional number`

  Estimated total number of hits

- `hitsPerPage: optional number`

  Number of results on each page

- `page: optional number`

  Current search results page

- `totalHits: optional number`

  Exhaustive total number of matches

- `totalPages: optional number`

  Exhaustive total number of search result pages

### Example

```http
curl https://api.cloud.scenario.com/v1/search/models \
    -H 'Content-Type: application/json' \
    -u "$SCENARIO_SDK_API_KEY:SCENARIO_SDK_API_SECRET" \
    -d '{}'
```

#### Response

```json
{
  "hits": [
    {
      "id": "id",
      "authorId": "authorId",
      "capabilities": [
        "string"
      ],
      "collectionIds": [
        "string"
      ],
      "concepts": [
        {
          "modelId": "modelId"
        }
      ],
      "createdAt": "createdAt",
      "exampleAssetIds": [
        "string"
      ],
      "name": "name",
      "ownerId": "ownerId",
      "privacy": "privacy",
      "shortDescription": "shortDescription",
      "source": "source",
      "tags": [
        "string"
      ],
      "teamId": "teamId",
      "trainingImagesNumber": 0,
      "type": "type",
      "updatedAt": "updatedAt",
      "parentModelId": "parentModelId",
      "score": 0,
      "thumbnail": {
        "assetId": "assetId",
        "url": "url"
      }
    }
  ],
  "limit": 0,
  "offset": 0,
  "estimatedTotalHits": 0,
  "hitsPerPage": 0,
  "page": 0,
  "totalHits": 0,
  "totalPages": 0
}
```

## Domain Types

### Search Asset Search Response

- `SearchAssetSearchResponse object { id, authorId, collectionIds, 14 more }`

  - `id: string`

    Unique identifier for the asset (e.g., "asset_GTrL3mq4SXWyMxkOHRxlpw")

  - `authorId: string`

    User ID of the asset creator/author

  - `collectionIds: array of string`

    Array of collection IDs this asset belongs to

  - `createdAt: string`

    Creation timestamp in ISO 8601 format (e.g., "2025-01-16T11:19:41.579Z")

  - `metadata: object { aspectRatio, baseModelId, guidance, 17 more }`

    Metadata containing detailed information about the asset's properties and generation parameters

    - `aspectRatio: optional string`

      Aspect ratio of the asset (e.g., "1:1", "16:9")

    - `baseModelId: optional string`

      ID of the base model used for generation

    - `guidance: optional number`

      Guidance scale used for diffusion models to control prompt adherence

    - `height: optional number`

      Height of the asset in pixels

    - `kind: optional string`

      Classification of the asset (e.g., "image", "video")

    - `modelId: optional string`

      ID of the specific model used if asset is model-based

    - `modelType: optional string`

      Type of model used for generation (e.g., "sd-1_5", "flux.1")

    - `name: optional string`

      Custom name given to the asset

    - `negativePrompt: optional string`

      Negative prompt used during generation to specify what to avoid

    - `negativePromptStrength: optional number`

      For Flux models: controls the influence of the negative prompt

    - `numInferenceSteps: optional number`

      Number of inference steps used during generation

    - `parentJobId: optional string`

      ID of the parent job that created this asset

    - `prompt: optional string`

      Text prompt used to generate the asset

    - `scheduler: optional string`

      Scheduler algorithm used during generation

    - `seed: optional string`

      Random seed used for generation, enables reproducibility

    - `size: optional number`

      File size of the asset in bytes

    - `text: optional string`

      Text used to generate the asset: mainly for speech to text

    - `thumbnail: optional object { assetId }`

      Thumbnail image information for the asset. Ex. Canvas thumbnail

      - `assetId: string`

        ID of the asset used as thumbnail

    - `type: optional string`

      Specific type/category of the asset (e.g., "canvas", "inference-txt")

    - `width: optional number`

      Width of the asset in pixels

  - `mimeType: string`

    MIME type of the asset (e.g., "image/png", "image/jpeg")

  - `nsfw: array of string`

    Array of detected NSFW categories

  - `ownerId: string`

    Project ID of the asset owner

  - `privacy: string`

    Privacy setting of the asset ("public", "private", or "unlisted")

  - `tags: array of string`

    Array of user-assigned tags for categorization

  - `teamId: string`

    Team ID of the asset owner

  - `updatedAt: string`

    Last modification timestamp in ISO 8601 format (e.g., "2025-01-16T11:19:41.579Z")

  - `url: string`

    Signed URL of the asset

  - `description: optional string`

    Textual description of the asset. Can be either:

    - User-provided description for training images
    - Automatically generated caption for images and videos assets
    - Automatically generated description for audio assets

  - `score: optional number`

    Score assigned to the asset based on usage and popularity

  - `thumbnail: optional object { assetId, url }`

    Thumbnail preview of the asset 3D, video...

    - `assetId: string`

      ID of the asset used as thumbnail

    - `url: string`

      Signed URL of the thumbnail

  - `transcription: optional string`

    Transcription of the asset. Can be either:

    - Automatically generated transcription for audio assets with speech

### Search Model Search Response

- `SearchModelSearchResponse object { id, authorId, capabilities, 17 more }`

  - `id: string`

    Unique identifier for the model (e.g., "model_GTrL3mq4SXWyMxkOHRxlpw")

  - `authorId: string`

    User ID of the model creator/author

  - `capabilities: array of string`

    Array of model capabilities

  - `collectionIds: array of string`

    Array of collection IDs this model belongs to

  - `concepts: array of object { modelId }`

    Array of concept models associated with this model
    Each concept contains a reference to its source model

    - `modelId: string`

      ID of the concept's source model

  - `createdAt: string`

    Creation timestamp in ISO 8601 format (e.g., "2025-01-16T11:19:41.579Z")

  - `exampleAssetIds: array of string`

    Array of example asset IDs associated with this model

  - `name: string`

    Display name of the model

  - `ownerId: string`

    Project ID of the model owner

  - `privacy: string`

    Privacy setting of the model ("public", "private", or "unlisted")

  - `shortDescription: string`

    Short description of the model

  - `source: string`

    Source/origin of the model (e.g., "training", "import")

  - `tags: array of string`

    Array of user-assigned tags for categorization

  - `teamId: string`

    Team ID of the model owner

  - `trainingImagesNumber: number`

    Number of images used to train this model

  - `type: string`

    Type of the model (e.g., "sd-1_5", "flux.1")

  - `updatedAt: string`

    Last modification timestamp in ISO 8601 format (e.g., "2025-01-16T11:19:41.579Z")

  - `parentModelId: optional string`

    ID of the parent model this model was derived from

  - `score: optional number`

    Score assigned to the model based on usage and popularity

  - `thumbnail: optional object { assetId, url }`

    Thumbnail image information for the model

    - `assetId: string`

      ID of the asset used as thumbnail

    - `url: string`

      Signed URL of the thumbnail