canonical: https://jentic.com/apis/needle.app/needle # Needle App Needle API Jentic publishes the only available OpenAPI specification for Needle API, keeping it validated and agent-ready. The Needle API is a RAG-as-a-Service platform that lets developers create collections, attach files, and run semantic search without managing their own vector store or embedding pipeline. The 10 endpoints cover collection lifecycle, file ingestion via signed upload URLs, collection statistics, and a search endpoint that returns ranked passages from the indexed content. Authentication uses an x-api-key header issued from the Needle dashboard. ## For AI agents Create RAG collections, ingest files via signed upload URLs, and run semantic search across documents through Needle's hosted vector store. ## Scope Does not host an LLM, expose raw vector operations, or process payments - use for hosted RAG collection ingestion and search only. ## Capabilities - Create and list RAG collections through POST /collections and GET /collections - Add files to a collection from signed URLs via POST `/collections/{collectionId}/files` - Run semantic search across indexed content with POST `/collections/{collectionId}/search` - Inspect collection statistics including file count and indexing status via `/collections/{collectionId}/stats` - Generate signed upload URLs for direct browser-to-storage file ingestion via `/files/upload-url` - Retrieve signed download URLs for ingested files via `/files/download-url` ## Use cases ### Hosted Knowledge Base for a Support Bot A support team builds a knowledge base by creating a Needle collection, uploading help-center PDFs and policy documents through the signed upload URL flow, and querying it from a chatbot via `/collections/{collectionId}/search.` Needle handles chunking, embedding, and retrieval, returning ranked passages the bot uses to ground its answers. Time-to-first-answer is typically under an hour for a small knowledge base. Example prompt: POST /collections to create the collection, upload PDFs via the signed URL flow, then POST `/collections/{collectionId}/search` with the user question. ### Document Search for an Internal Tool An internal tool surfaces an enterprise's policy and SOP documents to employees without indexing them on a self-managed vector database. The team uploads the documents to Needle and exposes a single search box backed by `/collections/{collectionId}/search.` Adding new documents is a matter of generating a fresh upload URL and POSTing the file reference to the collection. Example prompt: POST `/files/upload-url` to get a signed URL, upload the SOP, then POST `/collections/{collectionId}/files` with the returned file reference. ### Per-Tenant RAG for a SaaS Product A SaaS vendor gives each tenant its own Needle collection so customer documents stay isolated from each other. The vendor's app provisions a collection on tenant signup, ingests files as the customer uploads them, and runs scoped search at query time. The /stats endpoint surfaces ingestion progress to the customer dashboard. Example prompt: POST /collections with the tenant id in the name, then route every customer search through that collection's /search endpoint. ### Agent-Driven RAG Setup An AI agent that needs to ground itself in a customer's documents uses Jentic to create a Needle collection, ingest files, and search them without rebuilding the upload-URL choreography. The agent searches for the right operation, loads the schema, and submits each call while Jentic handles the x-api-key header. Example prompt: Search Jentic for 'search a Needle collection', load the schema for `/collections/{collectionId}/search`, and execute it with the user question. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/collections` | Create a collection | | GET | `/collections` | List collections | | GET | `/collections/{collectionId}/stats` | Get collection stats | | POST | `/collections/{collectionId}/files` | Add files to a collection | | POST | `/collections/{collectionId}/search` | Search a collection | | GET | `/files/upload-url` | Get a signed file upload URL | | GET | `/files/download-url` | Get a signed file download URL | ## Key resources - **Collections** — Create, list, and inspect RAG collections - **Files** — Add, list, and delete files within a collection - **Search** — Run semantic search across indexed content - **Upload URLs** — Generate signed URLs for direct file upload - **Download URLs** — Generate signed URLs for file retrieval - **Stats** — Inspect ingestion and indexing progress ## Why Jentic - **Setup:** Wiring the Needle API by hand means passing the x-api-key on every request, fetching signed upload and download URLs before moving files, and sequencing collection ingestion ahead of search yourself. Through Jentic you install once, import Needle from the API Directory, store the API key once, and your agent calls it. - **Permission scoping:** Needle puts the collection id in the URL path (`/collections/{collectionId}/...`), so a rule can pin your agent to one collection: it can add files and run searches for that collection and nothing else. You choose the operations it may call, so creating other collections is not included unless you add it. - **Credential handling:** Your Needle x-api-key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'search a Needle collection' or 'add a file to a collection', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Pinecone** — Self-served vector database with explicit index, namespace, and embedding control - **Chroma** — Open-source vector store with a hosted API - **OpenAI** — Language models that consume the passages Needle returns ## FAQ ### Why is there no official OpenAPI spec for Needle API? Needle publishes its API as developer documentation rather than a formal OpenAPI file. Jentic generates and maintains this spec so that AI agents and developers can call Needle API via structured tooling. It is validated against the live api.needle.app endpoints and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Needle API use? Needle uses an apiKey scheme via the x-api-key header. Generate the key from the Needle dashboard and send it on every request to api.needle.app/api/v1. Through Jentic the key is stored encrypted in the vault and injected at execution time, so the raw key never enters agent context. ### Can I run semantic search with the Needle API? Yes. POST `/collections/{collectionId}/search` with the natural-language query and any filters. Needle returns ranked passages from the indexed files in the collection, suitable for grounding an LLM response or surfacing in a search UI. ### What are the rate limits for the Needle API? Needle does not publish numeric per-endpoint rate limits in the OpenAPI document; tier limits are governed by the workspace plan in the Needle dashboard. Expect 429 responses on bursts on the free tier and back off; contact Needle for higher limits on paid plans. ### How do I add a file to a Needle collection through Jentic? Run pip install jentic, then search for 'add a file to a Needle collection', load the schemas for GET `/files/upload-url` and POST `/collections/{collectionId}/files`, and execute them in sequence with the file reference returned by the upload. ### Does the Needle API host the underlying vector database? Yes. Needle manages embeddings, chunking, and the vector index for you. The API exposes only collection, file, and search primitives rather than raw vector operations, so you do not configure dimensions, indices, or namespaces. ### Can I limit what my agent is allowed to do with the Needle API? Yes. Because you run Jentic One yourself, your own rules decide which Needle operations and credentials the agent may use. Since Needle puts the collection id in the URL path (`/collections/{collectionId}/...`), you can pin the agent to a single collection so it only adds files via POST `/collections/{collectionId}/files` and runs POST `/collections/{collectionId}/search` for that one collection. Operations you do not grant, such as POST /collections to create new collections, stay off limits unless you add them.