# create Search Overview

Retained recommendation Worker adapter. Automatic retries are disabled. Maximum UTF-8 request body: 4096 bytes.

Operation: createSearchOverview
POST /api/recommendation/overviews/{collection}

Access: anonymous. Automatic retries: none. Redirects: manual. Request body limit: 4096 bytes.
Default timeout: 30 seconds. Response limit: 16 MiB. Pagination is opt-in and bounded; an exhausted bound reports incomplete execution.

[HTML reference](/developers/api/createSearchOverview) · [Authoritative schemas](/api/openapi.json)

## Wire contract

```json
{
  "operationId": "createSearchOverview",
  "summary": "create Search Overview",
  "tags": [
    "recommendation"
  ],
  "description": "Retained recommendation Worker adapter. Automatic retries are disabled. Maximum UTF-8 request body: 4096 bytes.",
  "parameters": [
    {
      "name": "collection",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "enum": [
          "videos",
          "movies",
          "music",
          "podcasts"
        ]
      }
    }
  ],
  "security": [],
  "x-public-access": "anonymous",
  "x-public-side-effect": "model",
  "x-public-body-limit": 4096,
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "minLength": 3,
              "maxLength": 160
            },
            "category": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "filters": {
              "maxItems": 4,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              }
            },
            "canonicalIds": {
              "maxItems": 5,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 80
              }
            },
            "totalCount": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000
            }
          },
          "required": [
            "query",
            "canonicalIds"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "found",
                  "empty"
                ]
              },
              "query": {
                "type": "string"
              },
              "summary": {
                "type": "string"
              },
              "points": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "text": {
                      "type": "string"
                    },
                    "canonicalIds": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "text",
                    "canonicalIds"
                  ],
                  "additionalProperties": false
                }
              },
              "sources": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "canonicalId": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "canonicalUrl": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "category": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "year": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "metadata": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "image": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "src": {
                              "type": "string"
                            },
                            "alt": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "src",
                            "alt"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "actionUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "canonicalId",
                    "title",
                    "canonicalUrl",
                    "description",
                    "category",
                    "year",
                    "metadata",
                    "image",
                    "actionUrl"
                  ],
                  "additionalProperties": false
                }
              },
              "scopeNotice": {
                "type": "string"
              },
              "matchType": {
                "type": "string",
                "enum": [
                  "search-results",
                  "related"
                ]
              }
            },
            "required": [
              "status",
              "query",
              "summary",
              "points",
              "sources",
              "scopeNotice",
              "matchType"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "400": {
      "description": "Request failed",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        }
      }
    },
    "403": {
      "description": "Request failed",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        }
      }
    },
    "413": {
      "description": "Request failed",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        }
      }
    },
    "429": {
      "description": "Request failed",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        }
      }
    },
    "502": {
      "description": "Request failed",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        }
      }
    },
    "503": {
      "description": "Request failed",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        }
      }
    }
  }
}
```

## Synthetic examples

### curl

```bash
curl --fail-with-body --max-time 30 --max-filesize 16777216 --request POST 'https://irvinebroque.com/api/recommendation/overviews/videos' --header 'Accept: application/json' --header 'Content-Type: application/json' --data-binary @request.json
```

### TypeScript

```typescript
import { PublicApi } from '@irvinebroque/public-api';
const api = new PublicApi();
const result = await api.recommendation.overview({
  "collection": "videos",
  "body": {
    "query": "fixture",
    "canonicalIds": []
  }
});
console.log(result.status, result.headers.get('content-type')); // Keep transient capabilities in memory.
```

### CLI

```bash
irvinebroque recommendation overview --collection 'videos' --body-file request.json
```

### request.json

```json
{
  "query": "fixture",
  "canonicalIds": []
}
```