Knowledge and RAG
Load knowledge with the ingest API
Add documents, snippets, Q&A pairs and websites from code with /v1/ingest, and delete a source's vectors. Fields, limits, responses and errors.
Reference2 min readUpdated 23 October 2026
Everything you can add on the Knowledge tab you can also add from code. The ingest endpoints use the same headers as chat: your secret key in X-Api-Key and the agent in X-Agent-Id; the agent must be yours. Each call is synchronous: it returns once the content is embedded and stored. Credits are charged as in the app.
Endpoints
| Method and path | Body | Limits |
|---|---|---|
POST /v1/ingest/document | multipart file, or form fields text and filename; optional source_id | 50 MB; PDF or plain-text formats |
POST /v1/ingest/snippet | JSON {content, source_id?} | 3 to 300 characters indexed |
POST /v1/ingest/qa | JSON {question, answer, source_id?} | Question 3 to 200, answer 3 to 500 characters indexed |
POST /v1/ingest/website | JSON {url, max_pages?, max_depth?, include_paths?, exclude_paths?, source_id?} | max_pages 1 to 1,000 (default 100), max_depth 1 to 10 (default 3); at most 200 pages indexed per crawl |
DELETE /v1/ingest/source | JSON {source_type, source_id} | source_type is document, faq, web or qa |
Examples
curl https://api.sentientone.ai/v1/ingest/document \ -H "X-Api-Key: $SENTIENTONE_API_KEY" \ -H "X-Agent-Id: $AGENT_ID" \ -F "file=@returns-policy.pdf"curl https://api.sentientone.ai/v1/ingest/qa \ -H "Content-Type: application/json" \ -H "X-Api-Key: $SENTIENTONE_API_KEY" \ -H "X-Agent-Id: $AGENT_ID" \ -d '{"question": "Do you ship overseas?", "answer": "Yes, to 40 countries. Delivery takes 5 to 10 business days."}'curl https://api.sentientone.ai/v1/ingest/website \ -H "Content-Type: application/json" \ -H "X-Api-Key: $SENTIENTONE_API_KEY" \ -H "X-Agent-Id: $AGENT_ID" \ -d '{"url": "https://help.example.com", "max_pages": 50, "max_depth": 2, "include_paths": ["/articles"]}'Response
{ "source_type": "document", "source_id": "6f0c...", "status": "ready", "chunk_count": 18, "page_count": 7, "trace_id": "4f2a9c1e...", "elapsed_ms": 5230}status is ready, partial or error. Website crawls add pages_found, pages_indexed, pages_failed and pages_skipped. Keep the source_id (or pass your own) so you can delete the source's vectors later with DELETE /v1/ingest/source, which returns deleted_chunks.
Errors
| Status | Code | Meaning |
|---|---|---|
| 401 | MISSING_API_KEY, INVALID_API_KEY | Check the X-Api-Key header |
| 402 | OUT_OF_CREDITS | Not enough credits; the body includes balance and needed |
| 404 | AGENT_NOT_FOUND | The agent doesn't exist or isn't yours |
| 413 | FILE_TOO_LARGE | Over 50 MB |
| 415 | UNSUPPORTED_MEDIA_TYPE | Not PDF or a plain-text format |
| 422 | VALIDATION_ERROR, EXTRACTION_FAILED | Bad fields, text too short or long, or no extractable text |
| 502 | EMBEDDING_FAILED, CRAWL_FAILED | The embedding or crawl service failed; retry |
| 500 / 503 | INGEST_FAILED, CRAWLER_DISABLED | Unexpected failure, or crawling unavailable |
Every response has an X-Trace-Id header and every error body a request_id. Quote it to support. See Errors.
Still stuck?
Email us with what you tried and any request id. A person replies.