---
title: "Query pipeline"
method: POST
path: "/pipelines/{name}"
tags: ["Pipelines"]
---

# Query pipeline

`POST /pipelines/{name}`

Execute a RAG query against a specific pipeline.

When the server is configured with `identity.enabled`, this endpoint requires a caller identity, supplied by the trusted proxy in front of the server as a JSON claim set in the configured claims header (default `X-Forwarded-Claims`) or a bare subject in the configured subject header (default `X-Forwarded-User`). The server does NOT verify those headers: it checks no signature, issuer, audience or expiry, and trusts whatever the proxy asserts. Anything able to reach this server's port directly can therefore assert any identity, so the deployment must ensure only a trusted proxy can — see docs/identity.md. Retrieval then runs as that caller and PostgreSQL row-level security decides what it may see. A request carrying no identity is refused with 401 `IDENTITY_REQUIRED`; there is no fallback to the service's own database role.

Identity error codes: `IDENTITY_REQUIRED` (401, no identity was presented), `IDENTITY_MALFORMED` (400, the claims header was not a JSON object), `IDENTITY_UNTRUSTED_PEER` (403, the request came from an address not permitted to assert an identity) and `IDENTITY_ROLE_NOT_ALLOWED` (403, the claims named a database role that is not on the server's allowlist).

## Path parameters

- `name` string, required

## Request body

- QueryRequest
  - `disable_hybrid` boolean — Skip the keyword-search arm for this request, using vector search alone. Reduces latency and database work. This can only turn hybrid search off: a request cannot enable it where the pipeline configuration has disabled it.
  - `filter` Filter
    - `conditions` FilterCondition[], required — Filter conditions to apply
      - `column` string, required — Column name to filter on
      - `operator` '=' | '!=' | '<' | '>' | '<=' | '>=' | 'LIKE' | 'ILIKE' | 'IN' | 'NOT IN' | 'IS NULL' | 'IS NOT NULL', required — Comparison operator
      - `value` unknown
    - `logic` 'AND' | 'OR' — Logical operator to combine conditions: AND or OR (default: AND)
  - `include_sources` boolean — Request the source documents used to produce the answer. Honoured only if the pipeline is configured with allow_include_sources: true; otherwise the answer is returned without sources and the request still succeeds.
  - `messages` Message[] — Previous conversation history for context
    - `content` string, required — Message content
    - `role` string, required — Message role (user or assistant)
  - `query` string, required — The question to answer
  - `stream` boolean — Enable streaming response (SSE)
  - `top_n` integer — Override default result limit

## Response `200`

Query response

- QueryResponse
  - `answer` string, required — The generated answer
  - `sources` Source[] — Source documents. Present only when the request set include_sources=true and the pipeline permits it via allow_include_sources.
    - `content` string, required — Document content
    - `id` string — Document identifier
    - `score` number, double, required — Relevance score
  - `tokens_used` integer, required — Total tokens consumed

## Other responses

- `400` — Invalid request
- `401` — No caller identity was presented and the server requires one (IDENTITY_REQUIRED)
- `403` — The identity presented was not acceptable: the request came from an address not permitted to assert one (IDENTITY_UNTRUSTED_PEER), or it named a database role that is not permitted (IDENTITY_ROLE_NOT_ALLOWED)
- `404` — Pipeline not found
- `413` — Request body exceeds the 1 MiB limit
- `500` — Server error. error.code is RETRIEVAL_REFUSED when the document search could not be run because of a server-side configuration or permissions problem, RETRIEVAL_FAILED when the search failed for an unclassified reason, or EXECUTION_ERROR for any other failure. A retrieval failure is never reported as an empty result set
- `503` — The document store could not be reached, so no search ran (error.code RETRIEVAL_UNAVAILABLE). Unlike a 500 this is transient and the request may be retried
- `504` — The request took too long to process (error.code REQUEST_TIMEOUT)

---

[API](https://skmtc.net/pgedge/apis/pgedge-rag-server-api.md) · [All operations](https://skmtc.net/pgedge/apis/pgedge-rag-server-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pgedge/pgedge-rag-server-api/versions/bfa21179cba1/schema)