SCscipot
query
query

Unified query with automatic routing

Changed on

Execute a unified query against a POT with automatic strategy selection.

How it works:

  1. Classifies query (relational → GraphRAG, everything else → RAG)
  2. Executes that strategy
  3. Returns results with routing metadata

Strategies:

  • auto (default): Automatic selection based on query classification
  • rag: Force RAG-only (semantic search with embeddings)
  • graph_rag: Force GraphRAG (graph traversal for relational queries; seeds from RAG)
  • cag: Not available on this endpoint (501 STRATEGY_NOT_AVAILABLE); use POST /pots/{pot_id}/cag/search

Metadata: classification.suggested_strategy is the classifier's suggestion and may still read cag for a factual query; strategy_used is what ran. cag_attempted is always false and strategy_used is never cag or cag_with_rag_fallback (both stay in the schema for compatibility).

Tokens: a read is never refused for tokens. The gap signal's relevance judge (one small LLM call, only on an ambiguous gap) is billed as gap_signal_judge and skipped once the month's tokens are spent, leaving the deterministic verdict (v0.7.27.0).

Latency:

  • RAG: ~500ms
  • GraphRAG: ~200-800ms (depends on graph density)
post/pots/{pot_id}/query

Request

Path parameters

pot_idstring required

POT identifier (UUID or slug)

Request body

querystring required

Query text for retrieval

top_kinteger

Maximum results to return

strategy'auto' | 'cag' | 'rag' | 'graph_rag'

Force strategy or auto-select based on query classification. cag is not available on /query and answers 501 STRATEGY_NOT_AVAILABLE; use POST /pots/{pot_id}/cag/search

enable_fallbackboolean

Kept for compatibility. /query has no CAG, so there is no CAG-to-RAG fallback for this flag to allow or suppress

include_edgesboolean

Include edge context (contradictions, relationships) in response

include_stancesboolean

Include stance summaries for contradiction edges (requires include_edges=True)

as_ofstring date nullable

Day to judge validity on (ISO 8601). Each result says whether it is in force that day (currency); nothing is excluded. Omitted = today (UTC). A future day answers what will be in force then.

Example request

{
  "enable_fallback": true,
  "filters": {
    "domain": "architecture",
    "levels": [
      "CONSTITUTION",
      "VERIFIED"
    ],
    "tags": [
      "core"
    ]
  },
  "query": "What is POT Index?",
  "strategy": "auto",
  "top_k": 5
}

Response

Successful query

is_knowledge_gapboolean required

Convenience flag: true when retrieval likely hit a knowledge gap (gap_signal.confidence < threshold). The integrator decides whether to act on it.

Example response

{
  "data": {
    "results": [
      {
        "content": "POT Index es el sistema de scoring...",
        "domain": "architecture",
        "fact_id": "01234567-89ab-cdef-0123-456789abcdef",
        "level": "VERIFIED",
        "match_details": {
          "combined_score": 0.82,
          "similarity_score": 0.81
        },
        "pot_score": 0.85,
        "score": 0.82,
        "source": "rag",
        "tags": [
          "core",
          "scoring"
        ]
      }
    ],
    "total_results": 1
  },
  "gap_signal": {
    "average_score": 0.85,
    "confidence": 0.85,
    "high_certainty_facts": 1,
    "is_knowledge_gap": false,
    "reasons": [
      "1_high_certainty_facts"
    ],
    "threshold": 0.45,
    "total_facts": 1,
    "version": "v3"
  },
  "is_knowledge_gap": false,
  "metadata": {
    "cag_attempted": false,
    "cag_duration_ms": 0,
    "cag_results_count": 0,
    "classification": {
      "category": "factual",
      "confidence": 0.75,
      "reasoning": [
        "WHAT question pattern detected"
      ],
      "suggested_strategy": "cag"
    },
    "fallback_triggered": false,
    "rag_duration_ms": 470,
    "strategy_used": "rag",
    "total_duration_ms": 480
  }
}

Changes

  • 7764b32b043bRevision changes
    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property /// to the response with the status

  • 0fb6ed61ba72Revision changes
    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status