> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webless.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create query

> Returns content tiles, highlights, a marketing message, and a CTA for the given query. The v1 route resolves company configuration from the runtime package for the selected version pointer.

<Note>
  Use the same `requestId` and `sessionId` for `queries`, the WebSocket summary
  stream, `cta-selection`, and `suggestions` for a single user action.
</Note>

<script src="/playground-company-prefill.js" defer />


## OpenAPI

````yaml api-reference/openapi-latest.json POST /api/v1/queries
openapi: 3.1.0
info:
  title: Webless API
  description: >-
    Reference for the latest Webless API surface. New integrations should use
    the /api/v1 endpoints.
  version: v1
servers:
  - url: https://api.webless.ai
    description: Production Search API
security: []
paths:
  /api/v1/queries:
    post:
      tags:
        - Search API
      summary: Create a query
      description: >-
        Returns content tiles, highlights, a marketing message, and a CTA for
        the given query. The v1 route resolves company configuration from the
        runtime package for the selected version pointer.
      operationId: createQueryV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1QueryRequest'
            examples:
              default:
                value:
                  query: What does Webless do?
                  company: YOUR_COMPANY
                  requestId: 1f7c5f74-7b9e-4a0a-9b7d-4e3e2a5e3b60
                  sessionId: a1c2d3e4-1111-2222-3333-444455556666
                  number_of_results: 6
                  number_of_tiles: 6
                  summary_word_limit: 120
                  version: published
      responses:
        '200':
          description: Query result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '422':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
components:
  schemas:
    V1QueryRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: The user query.
          example: What does Webless do?
        company:
          type: string
          default: sigma
          description: The company identifier provisioned by Webless.
          example: YOUR_COMPANY
        version:
          $ref: '#/components/schemas/V1RuntimeVersion'
        user_persona_id:
          type: string
          nullable: true
        tone:
          type: string
          nullable: true
        requestId:
          type: string
          description: Correlation ID for the request.
          example: 1f7c5f74-7b9e-4a0a-9b7d-4e3e2a5e3b60
        sessionId:
          type: string
          description: Stable session ID for the user session.
          example: a1c2d3e4-1111-2222-3333-444455556666
        num_highlights:
          type: integer
          default: 0
          description: Maximum number of highlights to return.
        model:
          type: string
          default: gpt
        number_of_results:
          type: integer
          default: 6
          description: Maximum number of responses to return.
        number_of_tiles:
          type: integer
          default: 6
          description: Maximum number of tiles to consider.
        summary_word_limit:
          type: integer
          default: 120
        bullet_point_word_limit:
          type: integer
          default: 25
        headline_word_limit:
          type: integer
          default: 15
        token:
          type: string
          nullable: true
        use_hyde:
          type: boolean
          default: false
        use_history:
          type: boolean
          default: false
        use_hybrid:
          type: boolean
          default: false
        frontend_labels:
          type: array
          items:
            type: string
          nullable: true
        is_private_session:
          type: boolean
          default: false
          description: >-
            When true, the request is not written to session history or
            analytics logs.
    QueryResponse:
      type: object
      properties:
        responses:
          type: array
          items:
            $ref: '#/components/schemas/SearchTile'
        marketing_message:
          oneOf:
            - $ref: '#/components/schemas/MarketingMessage'
            - type: array
              items: {}
        highlights:
          type: array
          items:
            $ref: '#/components/schemas/Highlight'
        sales_cta:
          oneOf:
            - $ref: '#/components/schemas/DynamicCtaResponse'
            - type: array
              items: {}
    ValidationErrorResponse:
      type: object
      properties:
        detail:
          type: array
          items:
            type: object
            additionalProperties: true
    V1RuntimeVersion:
      type: string
      enum:
        - published
        - unpublished
      default: published
      description: >-
        Runtime package pointer. Omit this field or use `published` for
        production traffic. Use `unpublished` only when testing an unpublished
        runtime package.
    SearchTile:
      type: object
      properties:
        id:
          type: string
        link:
          type: string
          format: uri
        score:
          type: number
        image:
          type: string
          format: uri
        title:
          type: string
        description:
          type: string
        label:
          type: array
          items:
            type: string
        gated:
          type: integer
        highlight_list:
          type: array
          items:
            type: string
    MarketingMessage:
      type: object
      properties:
        message:
          type: string
        link:
          type: string
          format: uri
      additionalProperties: true
    Highlight:
      type: object
      properties:
        text:
          type: string
        url:
          type: string
          format: uri
    DynamicCtaResponse:
      type: object
      properties:
        text:
          type: string
        url:
          type: string
          format: uri
        open_type:
          type: string
          description: >-
            Determines how the CTA URL should be opened. `self` opens in the
            same tab, `blank` opens in a new tab, and `form` triggers an in-page
            form interaction.
          enum:
            - self
            - form
            - blank
      additionalProperties: true

````