> ## Documentation Index > Fetch the complete documentation index at: https://docs.tastelabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Search brands > Searches the curated brand corpus for the aesthetic you describe in natural language, and returns ranked result cards. Runs synchronously: there is nothing to poll. Consumes credits (more at `deep` depth), refunded if the search fails. Results come from the corpus, not from your own submissions. To work with a result, extract it with [`POST /design/submissions`](/api-reference/endpoint/create-submission). An optional `filters` object narrows results as hard constraints (`page_type`, `industry`, `hue`, `layout`): every returned card satisfies them. ## OpenAPI ````yaml api-reference/openapi.json POST /search openapi: 3.1.0 info: title: Taste Engine Design API version: 1.0.0 description: >- Public REST API for the Taste Engine. Submit a URL, extract a structured design system from any website, search the brand corpus by aesthetic, and ground prompts in real brand profiles. All requests are authenticated with an API key sent in the `X-API-Key` header. Create one directly in the Engine dashboard at https://engine.tastelabs.com/app/api-keys. contact: name: Taste Engine Support email: support@thetaste.ai servers: - url: https://api.tastelabs.com description: Production security: - ApiKeyAuth: [] tags: - name: Account description: Identity of the authenticated API key holder. - name: Submissions description: >- Create and track extraction jobs, then retrieve the resulting design system. - name: Prompts description: Rewrite prompts grounded in an extracted brand profile. - name: Search description: >- Find brands in the curated corpus by describing an aesthetic, or by similarity to one of your own extractions. - name: Brand adherence description: >- Judge how well a page adheres to a reference site's brand: submit a pair of URLs, poll the job, then read the verdict. paths: /search: post: tags: - Search summary: Search brands description: >- Searches the curated brand corpus for the aesthetic you describe in natural language, and returns ranked result cards. Runs synchronously: there is nothing to poll. Consumes credits (more at `deep` depth), refunded if the search fails. Results come from the corpus, not from your own submissions. To work with a result, extract it with [`POST /design/submissions`](/api-reference/endpoint/create-submission). An optional `filters` object narrows results as hard constraints (`page_type`, `industry`, `hue`, `layout`): every returned card satisfies them. operationId: searchBrands requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BrandSearchRequest' example: query: dark brutalist developer tools depth: fast top_k: 6 responses: '200': description: Ranked results for the query. content: application/json: schema: $ref: '#/components/schemas/BrandSearchResults' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientCredits' '422': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalError' '502': $ref: '#/components/responses/SearchFailed' '503': $ref: '#/components/responses/SearchSaturated' components: schemas: BrandSearchRequest: type: object properties: query: type: string description: Natural-language description of the aesthetic you are looking for. minLength: 2 maxLength: 400 examples: - dark brutalist developer tools depth: $ref: '#/components/schemas/SearchDepth' top_k: type: integer description: Maximum number of results to return. minimum: 1 maximum: 30 default: 6 filters: type: - object - 'null' description: >- Hard constraints on the results, not a ranking hint: every returned card satisfies them, and the list is never padded with out-of-filter lookalikes. Values are matched verbatim against the corpus vocabulary, so an unknown value returns no matches rather than an error. properties: page_type: type: - string - 'null' description: Only brands with this page type. enum: - homepage - about - pricing - careers - case_study - features - customer_stories - portfolio - product - collections - solutions - blog - landing_page - team - services - null industry: type: - string - 'null' description: Only brands in this industry. enum: - saas - ai - design - creative_agency - fintech - branding - developer_tools - fashion - venture_capital - entertainment - beverage - food - cybersecurity - e_commerce - architecture - cloud_infrastructure - ai_infrastructure - healthcare - edtech - web_development - productivity - beauty - photography - hr_tech - media - hospitality - gaming - financial_services - wellness - investment - real_estate - proptech - web3 - restaurant - insurtech - insurance - nonprofit - null hue: type: - string - 'null' description: Only brands whose dominant palette hues include this hue. enum: - red - orange - yellow - green - teal - blue - purple - pink - brown - null layout: type: - string - 'null' description: Only brands with this layout classification. enum: - grid_based_strict - asymmetric_broken_grid - generous_whitespace - dense_packed - centered_symmetric - left_aligned_flush - card_based - overlapping_layered - null required: - query BrandSearchResults: type: object properties: search_id: type: string description: Identifier of this search, as recorded in your search history. depth: $ref: '#/components/schemas/SearchDepth' results: type: array description: Ranked results, best match first. items: $ref: '#/components/schemas/BrandSearchCard' query_tags: type: - object - 'null' description: >- The engine's soft reading of the query, for display only. Never a constraint: results are not guaranteed to satisfy these. Only the request's `filters` narrow retrieval. properties: industry: type: array items: type: string page_type: type: array items: type: string hue: type: array items: type: string aesthetic: type: array items: type: string style: type: - string - 'null' description: >- Display name of the detected design style, e.g. `Brutalism`. Only set when the detection is confident. SearchDepth: type: string description: >- Search depth. `fast` returns in seconds. `deep` consumes more credits and can take up to ~3 minutes, for when result quality matters more than latency. enum: - fast - deep default: fast BrandSearchCard: type: object description: >- One ranked brand from the corpus. Ranking scores stay internal and are not part of the response. properties: url: type: string format: uri description: URL of the brand's page in the corpus. brand_name: type: - string - 'null' description: Brand name, when one was identified. identity_paragraph: type: string description: A short description of the brand's visual identity. match: type: - string - 'null' enum: - strong - good - related - null description: >- Confidence tier of the match. `null` when the search did not assign one, as on similarity results. reason: type: - string - 'null' description: >- One sentence on why this brand matched the query. `null` when the search did not assign one. badge: type: - string - 'null' enum: - discovery - null description: >- `discovery` marks a rotating exemplar of the style detected in the query, included so identical searches do not return an identical set. `null` otherwise. tags: type: array description: Descriptive tags for the brand, e.g. industry and page type. items: type: string palette: type: - object - 'null' description: >- Palette classification: `luminance`, `temperature`, `saturation`, `themes`, `aesthetic_codes`, `effects`, plus `primary` and `secondary` hex lists. typography: type: - object - 'null' description: >- Typography classification: `family_strategy`, `hierarchy`, and `character`. screenshot_url: type: - string - 'null' format: uri description: Full-page screenshot of the brand's page. Fetch it to see the brand. required: - url - identity_paragraph Error: type: object description: >- Standard error envelope for non-2xx responses: the machine-readable `error` code and the human-readable `message` are nested under `detail`. Validation errors (`422`) and search failures (`502`, `503`) shape `detail` differently; see those responses. properties: detail: type: object properties: error: type: string description: Machine-readable error code. examples: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - NOT_READY message: type: string description: Human-readable explanation of the error. required: - error - message additionalProperties: true required: - detail responses: Unauthorized: description: The API key is missing, invalid, or expired. content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: error: UNAUTHORIZED message: Bearer token or X-API-Key required InsufficientCredits: description: >- The account doesn't have enough credits to run the request. Only occurs when credit metering is enabled. content: application/json: schema: type: object required: - detail properties: detail: type: object required: - error - message properties: error: type: string examples: - INSUFFICIENT_CREDITS message: type: string balance: type: integer description: The account's current credit balance. required: type: integer description: Credits required to run this request. example: detail: error: INSUFFICIENT_CREDITS message: Not enough credits for this request. balance: 0 required: 1 ValidationError: description: >- The request failed validation. `detail` is a list of issues, each naming the offending field in `loc`. content: application/json: schema: type: object properties: detail: type: array items: type: object properties: loc: type: array items: {} msg: type: string type: type: string example: detail: - loc: - body - url msg: Field required type: missing InternalError: description: An unexpected server error occurred. The body is plain text. content: text/plain: example: Internal Server Error SearchFailed: description: >- The search could not be completed. The credit charge is refunded. `detail` is a plain string. content: application/json: schema: type: object properties: detail: type: string example: detail: Search failed. SearchSaturated: description: >- Search is at capacity. Retry after the number of seconds in the `Retry-After` header. The credit charge is refunded. `detail` is a plain string. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: type: object properties: detail: type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- API key issued by the Taste Engine. Create one in the dashboard at https://engine.tastelabs.com/app/api-keys. ````