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

# Search for context data in the context processor

> This endpoint sends a search request to the context processor to retrieve relevant context data based on the provided query.



## OpenAPI

````yaml POST /api/v1/context/search
openapi: 3.1.0
info:
  title: Alchemyst AI API v1 documentation
  version: 1.0.0
  description: v1 API documentation for Alchemyst AI
servers:
  - url: https://platform-backend.getalchemystai.com
    description: production
security:
  - bearerAuth: []
tags: []
paths:
  /api/v1/context/search:
    post:
      tags:
        - context
      summary: Search for context data in the context processor
      description: >-
        This endpoint sends a search request to the context processor to
        retrieve relevant context data based on the provided query.
      operationId: searchUserContext
      parameters:
        - in: query
          name: metadata
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            default: 'false'
          required: false
          description: >
            Controls whether metadata is included in the response:

            - metadata=true → metadata will be included in each context item in
            the response.

            - metadata=false (or omitted) → metadata will be excluded from the
            response for better performance.
        - in: query
          name: mode
          schema:
            type: string
            enum:
              - fast
              - standard
            default: standard
          required: false
          description: >
            Controls the search mode:

            - mode=fast → prioritizes speed over completeness.

            - mode=standard → performs a comprehensive search (default if
            omitted).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
                - similarity_threshold
                - minimum_similarity_threshold
              properties:
                user_id:
                  type: string
                  description: The ID of the user making the request
                  example: user123
                  deprecated: true
                query:
                  type: string
                  description: The search query used to search for context data
                  example: search query for user preferences
                similarity_threshold:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: >-
                    Maximum similarity threshold (must be >=
                    minimum_similarity_threshold)
                  example: 0.8
                minimum_similarity_threshold:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: Minimum similarity threshold
                  example: 0.5
                scope:
                  type: string
                  enum:
                    - internal
                    - external
                  default: internal
                  description: Search scope
                body_metadata:
                  type: object
                  description: Additional metadata for the search
                  default: {}
            examples:
              simple:
                summary: Search without metadata filters (metadata=false or omitted)
                value:
                  query: What did the customer ask about pricing for the Scale plan?
                  similarity_threshold: 0.8
                  minimum_similarity_threshold: 0.5
                  scope: internal
              withMetadata:
                summary: Search with metadata filters (requires metadata=true)
                value:
                  query: What did the customer ask about pricing for the Scale plan?
                  similarity_threshold: 0.8
                  minimum_similarity_threshold: 0.5
                  scope: internal
                  metadata:
                    fileName: support_thread_TCK-1234.txt
                    groupName:
                      - support
                      - pricing
                    lastModifiedAt: '2025-01-10T12:34:56.000Z'
      responses:
        '202':
          description: >-
            Context search request successfully processed. Response structure
            varies based on metadata query parameter: if metadata=true, each
            context includes metadata; if metadata=false or omitted, metadata is
            excluded from the response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  contexts:
                    type: array
                    items:
                      type: object
                      properties:
                        updatedAt:
                          type: string
                          format: date-time
                        createdAt:
                          type: string
                          format: date-time
                        metadata:
                          type: object
                          description: Only included when query parameter metadata=true
                        content:
                          type: string
                        score:
                          type: number
                          minimum: 0.001
        '400':
          description: Bad Request - Invalid or missing search parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    example: 'Fields missing. Detailed error: {error details}'
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required - User not allowed to perform action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - User lacks required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    example: error
      security:
        - bearerAuth: []
components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Invalid job id
        status:
          type: number
          example: 400
        error:
          type: object
          example: Error details
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: UNAUTHORIZED
            message:
              type: string
              example: User not authenticated
            details:
              type: object
              additionalProperties: true
        statusText:
          type: string
          description: Error message (detailed in debug mode)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````