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

# Query Spaces

> Query one or more spaces for similar content. Accepts a single space ID or array of space IDs. Results are merged and globally ranked by default, or can be grouped by space.



## OpenAPI

````yaml api/openapi.json post /api/query
openapi: 3.1.0
info:
  version: '0.1'
  title: Orchata API
servers:
  - url: https://api.orchata.ai
    description: Orchata API Server
security:
  - ApiKey: []
paths:
  /api/query:
    post:
      tags:
        - Queries
      summary: Query Spaces
      description: >-
        Query one or more spaces for similar content. Accepts a single space ID
        or array of space IDs. Results are merged and globally ranked by
        default, or can be grouped by space.
      requestBody:
        description: Query request
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  minLength: 1
                spaceIds:
                  anyOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                topK:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 10
                threshold:
                  type: number
                  minimum: 0
                  maximum: 1
                  default: 0
                metadata:
                  type: object
                  additionalProperties: {}
                groupBySpace:
                  type: boolean
                  default: false
              required:
                - query
                - spaceIds
      responses:
        '200':
          description: Successfully retrieved query results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        chunk:
                          type: object
                          properties:
                            id:
                              type: string
                            content:
                              type: string
                            chunkIndex:
                              type: number
                          required:
                            - id
                            - content
                            - chunkIndex
                        document:
                          type: object
                          properties:
                            id:
                              type: string
                            filename:
                              type: string
                            metadata:
                              type: object
                              additionalProperties: {}
                          required:
                            - id
                            - filename
                            - metadata
                        space:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            description:
                              type: string
                          required:
                            - id
                            - name
                            - description
                        similarity:
                          type:
                            - number
                            - 'null'
                        metadata:
                          type: object
                          additionalProperties: {}
                      required:
                        - chunk
                        - document
                        - space
                        - similarity
                        - metadata
                  totalResults:
                    type: number
                  groupedBySpace:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        space:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            description:
                              type: string
                          required:
                            - id
                            - name
                            - description
                        chunks:
                          type: array
                          items:
                            type: object
                            properties:
                              chunk:
                                type: object
                                properties:
                                  id:
                                    type: string
                                  content:
                                    type: string
                                  chunkIndex:
                                    type: number
                                required:
                                  - id
                                  - content
                                  - chunkIndex
                              document:
                                type: object
                                properties:
                                  id:
                                    type: string
                                  filename:
                                    type: string
                                  metadata:
                                    type: object
                                    additionalProperties: {}
                                required:
                                  - id
                                  - filename
                                  - metadata
                              space:
                                type: object
                                properties:
                                  id:
                                    type: string
                                  name:
                                    type: string
                                  description:
                                    type: string
                                required:
                                  - id
                                  - name
                                  - description
                              similarity:
                                type:
                                  - number
                                  - 'null'
                              metadata:
                                type: object
                                additionalProperties: {}
                            required:
                              - chunk
                              - document
                              - space
                              - similarity
                              - metadata
                        totalMatches:
                          type: number
                      required:
                        - space
                        - chunks
                        - totalMatches
                  reasoning:
                    type: string
                required:
                  - results
                  - totalResults
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '403':
          description: Forbidden - insufficient permissions
      x-codeSamples:
        - lang: typescript
          label: TypeScript SDK (Simple)
          source: |-
            import { Orchata } from '@orchata-ai/sdk';

            const client = new Orchata({ apiKey: 'oai_your_api_key' });

            const { results } = await client.query({
              spaceIds: 'space_123',
              query: 'How do I authenticate?'
            });

            for (const result of results) {
              console.log(`Score: ${result.similarity}`);
              console.log(`Content: ${result.chunk.content}`);
            }
        - lang: typescript
          label: TypeScript SDK (Advanced)
          source: |-
            import { Orchata } from '@orchata-ai/sdk';

            const client = new Orchata({ apiKey: 'oai_your_api_key' });

            // Query multiple spaces with options
            const { results } = await client.query({
              spaceIds: ['space_123', 'space_456'],
              query: 'authentication',
              topK: 5,
              metadata: { category: 'docs' }
            });

            // Or group results by space
            const { groupedBySpace } = await client.query({
              spaceIds: ['space_123', 'space_456'],
              query: 'authentication',
              groupBySpace: true
            });
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Oai-Api-Key

````