Skip to main content
POST /api/v1/retrieve returns the passages (“chunks”) that best match a query, each with the record it came from and a citation link. Use it when you build your own RAG pipeline or agent on top of PipesHub and want PipesHub’s search, with its permissions and connectors, without its chat.
  • Same permissions and filters as search. Chunks are filtered by the caller’s permissions exactly as PipesHub search is, and take the same filters and date bounds. The ranking can differ: retrieval runs one search for your text, with no query rewrite unless you ask for it and no timeline mode for long date ranges.
  • Nothing is stored. No search history and no citation documents are written, so you can call it on every request your application serves.
  • Ready to cite. Every chunk carries a deep link to the passage, and a link to the record.
The Retrieval API needs a PipesHub version that includes it. An older instance answers 404 for this path.
Coding agents connecting an IDE to company documents should use MCP, not this API. See For coding agents.

Authentication

Send a personal access token or an OAuth 2.0 access token that carries the semantic:write scope, the scope search uses. The token decides whose permissions apply: a personal access token sees what you can see.

Request


Response

Nothing to find is not an error. No match, no records you can access (including an apps id that does not exist or that you cannot read), or nothing indexed yet all return 200 with chunks: [] and a message.

Errors


Use it in your code

With framework retrievers

The SDKs ship ready-made retrievers for LangChain, LlamaIndex and the Vercel AI SDK. Each takes limit, filters, max_chunks_per_record (maxChunksPerRecord in TypeScript) and rewrite_query (rewriteQuery).
LangChain documents and LlamaIndex nodes hold one chunk each. Their metadata has the record (recordId, name, connector, mimeType, updatedAt) and the citation (url, recordUrl, pageNum, blockIndex). The relevance score is metadata["score"] on a LangChain document and score on a LlamaIndex NodeWithScore. The AI SDK tool returns the response shown above, and its description tells the model to cite each passage’s url. Keep citation.url in your answer so readers can open the source passage.
The full schema is in the API reference.