How does the Plugsky RAG API work?

Key facts

Collections	POST /v1/rag/collections
Documents	POST /v1/rag/collections/{id}/documents
Query	POST /v1/rag/collections/{id}/query
Formats	PDF, DOCX, TXT, MD, HTML
Chunking	500-token chunks with 50-token overlap by default
Embeddings	Documents embedded with the plugsky-embed model
Reranking	Optional rerank: true on queries
Data use	Documents never used to train any model

TL;DR

• Three calls: create a collection, upload documents, query.
• Chunking, embedding and indexing happen automatically.
• Queries return ranked chunks with source citations and scores.
• pgvector is the default store; Pinecone, Qdrant and Weaviate on Enterprise.
• Bring your own embeddings by setting embedding_model to custom.

How it works, step by step

1. Create a collection with POST /v1/rag/collections and note its id.
2. Upload files with multipart POST to the collection's documents endpoint.
3. Attach metadata such as department or access level to each document.
4. Query with top_k and rerank: true to tune recall and ordering.
5. Read chunks, scores and source references from the response.
6. Compose the retrieved chunks into a chat completion prompt with citation instructions.

Original data

Try it yourself

Open the RAG sandbox →

Collections and document upload

A collection is the container for one knowledge base. You create it with a name and optional metadata, then upload documents to its documents endpoint. The API accepts PDF, DOCX, TXT, MD and HTML. During upload you can attach per-document metadata, which is returned with chunks at query time and is useful for access filters or routing.

Documents move through parsing, chunking, embedding and indexing automatically; there is no separate indexing call to make.

Chunking, embeddings and storage

By default documents are split into 500-token chunks with 50-token overlap and embedded with the plugsky-embed model. Overlap preserves context that would otherwise be cut at a boundary. If your content has structure — policies with sections, contracts with clauses — test a smaller or larger chunk size against your own evaluation set before uploading everything.

pgvector is the default vector store. Pinecone, Qdrant and Weaviate are supported on Enterprise, and Private Endpoint deployments can bring their own store. You can also set embedding_model: "custom" and supply your own vectors at upload time.

Querying and citations

A query takes the search text, top_k and an optional rerank flag. The response contains the top chunks with text, similarity score, source (for example handbook.pdf#page=12) and metadata, plus rerank scores when enabled. Because every chunk carries its source, you can require the chat model to cite the document and page it used.

Ask for fewer, more relevant chunks rather than a large top_k: every chunk consumes context window and can dilute the answer.

Scale, deployment and data handling

Self-serve collections scale to large document counts, and Enterprise removes the hard cap. The same endpoints run in region-locked data planes and in VPC, on-prem and air-gapped deployments. Documents are stored encrypted at rest, used only for retrieval, and never used to train models — an important distinction when your material is confidential.

Honest caveat: the RAG API is a managed retrieval layer, not a full document-management system. Versioning, retention policy and complex permission models belong in your application or in your own index if those requirements are strict.

Honest comparison

Capability	Plugsky RAG API	DIY RAG stack	Fully managed competitor
Setup	Three endpoints, automatic indexing	Chunking, embedding, store and query code	Varies
Formats	PDF, DOCX, TXT, MD, HTML	Whatever you parse	Varies
Citations	Built into query results	You implement	Often available
Vector store	pgvector default; bring your own on Enterprise	Your choice	Vendor's store
Deployment	Cloud, VPC, on-prem, air-gapped	Wherever you host it	Usually SaaS only
Ops overhead	Managed	High	Managed