Guide
Upload knowledge
Atlas Knowledge stores business documents, URLs, and plain text as org-owned grounding material. Both Atlas-hosted agents and external sales agents query the same knowledge corpus. Knowledge is tenant-isolated — your corpus is invisible to other Mirai organizations. Customer-facing answers should cite source metadata when available and hand off to a human operator when no evidence supports the answer.
Knowledge source types
urlCrawl and ingest a single URL. Atlas fetches, parses, and chunks the page content.textDirectly ingest a plain-text passage with a title. Best for FAQs, policies, and short-form content.documentUpload a PDF or DOCX file. Processed asynchronously; poll for completion.Ingest a URL
Provide a publicly accessible URL. Atlas queues a crawl job, extracts the text content, chunks it into indexed passages, and makes it searchable via GET /v1/atlas/knowledge.
POST /v1/atlas/knowledge
{
"idempotency_key": "kn_url_pricing_01HX9Z",
"source_type": "url",
"url": "https://acme.com/pricing",
"title": "Acme Beauty Pricing"
}
Response: {
"knowledge_id": "kn_01HXAB",
"source_type": "url",
"status": "queued",
"title": "Acme Beauty Pricing"
}"Ingest plain text
Directly submit text content. Ideal for FAQs, return policies, menu items, or any content that does not have a live URL. The text is chunked and indexed immediately without an async job.
POST /v1/atlas/knowledge
{
"idempotency_key": "kn_text_faq_01HX9Z",
"source_type": "text",
"title": "Booking & Cancellation FAQ",
"text": "Reservations can be cancelled up to 24 hours before the appointment time. Late cancellations within 24 hours are non-refundable. To reschedule, please contact us via WhatsApp at least 12 hours before your appointment."
}
Response: {
"knowledge_id": "kn_01HXAC",
"source_type": "text",
"status": "indexed",
"title": "Booking & Cancellation FAQ",
"indexed_at": "2026-05-21T10:15:00Z"
}"Query knowledge for grounding
Search the org-owned corpus using a natural language query. Atlas returns ranked passages with source metadata and citation evidence. Agents should include citations in customer-facing answers and fall back to handoff when no passage meets a relevance threshold.
GET /v1/atlas/knowledge?q=cancellation+policy&limit=5
Response: {
"data": [
{
"knowledge_id": "kn_01HXAC",
"source_type": "text",
"title": "Booking & Cancellation FAQ",
"passage": "Reservations can be cancelled up to 24 hours before...",
"relevance_score": 0.94,
"citation": { "knowledge_id": "kn_01HXAC", "title": "Booking & Cancellation FAQ" }
}
],
"query": "cancellation policy",
"total_results": 1
}Knowledge lifecycle
- Queued — URL or document submitted; ingestion in progress. Poll
GET /v1/atlas/knowledge/{id}for status. - Indexed — Content chunked and stored. Available to all agents in the org.
- Failed — Ingestion error (invalid URL, unsupported format, or fetch blocked). Retry with a corrected source or re-submit as text.
- Archived — Soft-deleted. Removed from search results but retained in run citation history. Restore via
PATCH /v1/atlas/knowledge/{id}.
Knowledge readiness for sandbox
Before testing in sandbox, ensure the canonical corpus covers the key customer journeys. At minimum, the knowledge base should answer questions about: