Key facts
| Client | OpenAI Node SDK with baseURL set to the Plugsky API |
| RAG endpoints | POST /v1/rag/collections, document upload and POST /v1/rag/query |
| Embeddings | POST /v1/embeddings with plugsky-embed-v1 (1536d) or plugsky-embed-large (3072d) |
| Retrieval | Keyword, vector and hybrid search with optional reranking and citations |
| Streaming | Chat streaming is live for token-by-token responses in Node |
| Free tier | plugsky-micro and plugsky-lite, no card required |
| Deployment | Managed, VPC, on-prem and air-gapped options |
| Product status | Live |
TL;DR
- One SDK for chat, embeddings and RAG keeps the TypeScript surface small.
- Create the collection, upload with metadata, then query for chunks.
- Keep prompt assembly typed so citation parsing cannot drift.
- Streaming improves perceived latency when the answer is long.
- Store the query plus retrieved chunk ids for evaluation and audit.
How it works, step by step
- Install the OpenAI package and set the API key in the environment.
- Create a client with the Plugsky base URL and reuse it across the app.
- Create a collection and keep its id in typed configuration.
- Upload documents with metadata fields used later for filters.
- Query the collection with top_k and read chunks, scores and sources.
- Build a typed prompt from retrieved chunks and require inline citations.
- Log the question, retrieved chunk ids and answer for evaluation.
Try it yourself
Open the OpenAI-compatible API tester →
Project setup and client configuration
Install the OpenAI Node SDK, then construct the client once with the Plugsky base URL and an API key read from the environment. Keep the client in a module that the rest of the application imports, so there is exactly one place where the base URL and default model live. That single point makes environment changes and future migrations trivial.
TypeScript helps most around the response shapes: define a small type for a retrieved chunk with text, score and source fields, and map the API response into it immediately. Everything downstream then works with a stable internal contract instead of raw JSON.
Creating a collection and uploading documents
Create a collection with a POST call and persist its identifier. Upload documents with metadata such as source, department or version; the platform accepts PDF, DOCX, TXT, MD and HTML, and chunking, embedding and indexing happen automatically with 500-token chunks and 50-token overlap by default.
Make the upload path idempotent by using a deterministic document id, so a retry or a re-run updates existing content instead of duplicating it. In serverless deployments, move uploads into background jobs: ingestion can take longer than a request timeout.
Querying and composing the answer
Send the user question to the query endpoint with top_k and optional reranking, then map the ranked chunks into your internal type. Compose the chat prompt from those chunks only, and instruct the model to answer strictly from context, cite the sources used, and decline when the answer is not present.
For user-facing chat, enable streaming so tokens appear as they are generated. Stream the grounded answer, then attach the citation list once the response completes. Keep the prompt template in one file and treat changes to it like code changes that require evaluation.
Wrapping it as a service
Expose a small internal endpoint that accepts a question, calls the query endpoint, assembles the prompt and returns the answer with citations. Add request logging with the question, retrieved chunk ids and model used, then run a fixed evaluation set through the same path on every change. That closes the loop between development and production behaviour.
Use the OpenAI-compatible API tester to check requests, then start free with plugsky-micro and plugsky-lite or the 14-day full-access trial. Current plans are on the live pricing page.
Honest comparison
| Task | Plugsky call | Your TypeScript code | Third-party stack |
|---|---|---|---|
| Chat generation | Chat completions with streaming | Prompt template and citation parsing | Separate provider SDK |
| Embeddings | POST /v1/embeddings | Batch and map responses | Embedding vendor plus store |
| Ingestion | Collection upload with automatic chunking | Background job and idempotency | Custom ingestion pipeline |
| Retrieval | Query with top_k, modes and reranking | Typed chunk mapping | Store client plus reranker |
| Operations | Managed endpoints | Logging and evaluation harness | You run every component |
Frequently asked questions
Which TypeScript package should I use?
The OpenAI Node SDK works because the API is OpenAI-compatible. Set the base URL to Plugsky and keep your existing typed client code.
Does streaming work with RAG answers?
Yes. Streaming is live on the chat endpoint, so you can stream the grounded answer and append citations when the stream finishes.
Can I run ingestion in a serverless function?
You can start it there, but long uploads may exceed request timeouts. Move ingestion into a background job or queue for reliability.
Can I use my existing embeddings code?
Yes. POST /v1/embeddings matches the OpenAI request shape, so existing TypeScript embedding calls keep working after a base URL change.
Is there a free plan?
Yes. The free plan includes plugsky-micro and plugsky-lite with 2 API keys and no credit card, and a 14-day full-access trial is available.
How is pricing structured?
Self-serve plans are flat monthly with unlimited fair-use usage and no per-token charges or overage fees. See the live pricing page for current plans.