> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Test a knowledge-base document query > Run a real similarity search scoped to a single knowledge-base document and return the top-matching chunks plus the synthesized answer the agent would generate — a sandbox for verifying retrieval quality before shipping. Bumps each matched chunk's retrieval count so operators can watch retrieval frequency stabilise. Requires an operator role (owner, admin, or developer) because it calls the LLM provider and is billable. ## OpenAPI ````yaml /openapi.yaml post /api/v1/agents/{agentId}/knowledge-base/{docId}/test-query openapi: 3.1.0 info: title: Devotel CPaaS API description: Orbit by Devotel — Communications Platform as a Service API version: 1.0.0 contact: name: Devotel url: https://devotel.io email: support@devotel.io license: name: Proprietary servers: - url: https://api.orbit.devotel.io description: Production security: - Bearer: [] - ApiKey: [] tags: - name: Messages description: >- Send and manage messages across all channels (SMS, WhatsApp, RCS, Email, Viber, etc.) - name: Fax description: >- List and track fax (MMS/T.38) transmissions on Telnyx-backed fax numbers (sending flows through the Messaging API) - name: Agents description: AI agent creation, configuration, and execution - name: Voice description: Voice calls, IVR, conferencing, and SIP trunking - name: OnCall description: On-call rotations and escalation policy planning for incident alerting - name: Webhooks description: Webhook endpoint management and delivery logs - name: Numbers description: Phone number search, provisioning, and configuration - name: Brand Identity description: >- Unified cross-channel brand trust posture (10DLC, toll-free, WhatsApp, RCS, branded calling, number KYC) - name: Contacts description: Contact management, segmentation, and lifecycle tracking - name: Campaigns description: Marketing campaign orchestration and analytics - name: Flows description: Automation flow builder and execution engine - name: Templates description: Message template management and approval workflows - name: Settings description: Organization, channel, and user preference settings - name: Verify description: OTP generation and verification across channels - name: Push description: Push notification delivery via FCM and APNs - name: Integrations description: Third-party service connections and OAuth management - name: CDP description: >- Customer Data Platform — activation surface (CRM object sync, streaming destinations, ad-audience activation) - name: Files description: >- Server-to-server media upload, listing, retrieval, and deletion (signed-URL backed) - name: Commerce description: >- Omnichannel conversational-commerce — persistent cart + checkout state machine, channel-agnostic hosted pay-by-link, native WhatsApp checkout, and AP2-style agent payment mandates. - name: Sync description: >- Real-time shared-state primitive (Twilio Sync parity) — Documents, Maps, Lists, and ephemeral Streams, with change events relayed over the /api/v1/ws/sync WebSocket gateway paths: /api/v1/agents/{agentId}/knowledge-base/{docId}/test-query: post: tags: - Agents summary: Test a knowledge-base document query description: >- Run a real similarity search scoped to a single knowledge-base document and return the top-matching chunks plus the synthesized answer the agent would generate — a sandbox for verifying retrieval quality before shipping. Bumps each matched chunk's retrieval count so operators can watch retrieval frequency stabilise. Requires an operator role (owner, admin, or developer) because it calls the LLM provider and is billable. parameters: - schema: type: string in: path name: agentId required: true - schema: type: string in: path name: docId required: true requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string minLength: 1 maxLength: 2000 description: The natural-language query to run against the document. limit: type: integer minimum: 1 maximum: 20 default: 5 description: Top-K chunks to return. threshold: type: number minimum: 0 maximum: 1 default: 0 description: Minimum similarity score for a chunk to be included. synthesize: type: boolean default: true description: >- Whether to also synthesize an answer from the retrieved chunks. example: query: What is the refund window for enterprise plans? limit: 5 synthesize: true responses: '200': description: The top matching chunks and the synthesized answer. content: application/json: schema: type: object properties: data: type: object properties: agent_id: type: string document_id: type: string doc_version_at_query: type: integer description: >- Document version pinned when the query ran, so stale results can be detected after a re-chunk. query: type: string chunks: type: array items: type: object additionalProperties: true description: The retrieved chunks with their similarity scores. synthesized_answer: type: string nullable: true description: >- The answer the agent would generate, or null when synthesize=false. kb_collection_missing: type: boolean description: >- True when the document has chunks but the vector collection could not be reached. query_embedding_dim: type: integer description: >- Dimensionality of the query embedding used for the search. rag_pii_redaction_applied: type: boolean description: >- Whether operator-only PII redaction was applied to the returned chunk text. meta: $ref: '#/components/schemas/ResponseMeta' components: schemas: ResponseMeta: type: object required: - request_id - timestamp additionalProperties: false properties: request_id: type: string description: Unique request identifier (also returned as X-Request-Id header) timestamp: type: string format: date-time docs_url: type: string format: uri nullable: true securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT description: Dashboard JWT token from Clerk ApiKey: type: apiKey name: X-API-Key in: header description: Server-to-server API key (dv_live_sk_*) ````