Skip to main content
Each Tale service has its own REST API. These are used internally between services but are also available for direct integration with external systems.

​
Interactive API documentation

All Python-based services have a Swagger UI for exploring and testing the API:
ServiceSwagger UI URLOpenAPI JSON
RAGhttp://localhost:8001/docshttp://localhost:8001/openapi.json
Crawlerhttp://localhost:8002/docshttp://localhost:8002/openapi.json

​
RAG API

The RAG API handles document indexing and search. It is the engine behind the knowledge base.

​
Upload a document

POST /api/v1/documents/upload
Content-Type: multipart/form-data

file:      <binary file data>
file_id:   "unique-file-id"
sync:      "true"  (optional, wait for indexing to complete)
metadata:  '{"source": "upload"}'  (optional JSON string)
Document indexing runs in the background by default. Set sync=true to wait for indexing to complete before the response returns.

​
Check document statuses

POST /api/v1/documents/statuses

{
  "file_ids": ["file-id-1", "file-id-2"]
}
Returns the indexing status for each document. States: queued, running, completed, failed.

​
Search the knowledge base

POST /api/v1/search

{
  "query": "What is our return policy?",
  "file_ids": ["file-id-1", "file-id-2"],
  "top_k": 5,
  "similarity_threshold": 0.0,
  "include_metadata": true
}
The file_ids parameter is required and scopes the search to specific documents.

​
Delete a document

DELETE /api/v1/documents/{file_id}

​
Get document content

GET /api/v1/documents/{file_id}/content
Returns the full extracted text of an indexed document.

​
Compare documents

POST /api/v1/documents/compare

{
  "file_id_a": "file-id-1",
  "file_id_b": "file-id-2"
}

​
Crawler API

​
Register a website for crawling

POST /api/v1/websites

{
  "domain": "https://docs.example.com",
  "scan_interval": 21600
}
scan_interval is in seconds. Minimum value is 60.

​
Fetch page content

POST /api/v1/urls/fetch

{
  "urls": ["https://docs.example.com/guide"],
  "word_count_threshold": 100
}
Returns cached content when available, or fetches it live if not.

​
Get website info

GET /api/v1/websites/{domain}

​
Deregister a website

DELETE /api/v1/websites/{domain}

​
List website URLs

GET /api/v1/websites/{domain}/urls

​
Platform API

The Platform service exposes a public API at /api/v1/* for programmatic access to your data. Authenticate using an x-api-key header with a key from Settings > API Keys. Full API documentation: https://yourdomain.com/api/v1/openapi.json
Last modified on April 8, 2026