Passer au contenu principal
Chaque service Tale a sa propre API REST. Elles sont utilisées en interne entre services mais aussi disponibles pour l’intégration directe avec des systèmes externes.

​
Documentation API interactive

Tous les services Python ont une UI Swagger pour explorer et tester l’API :
ServiceURL Swagger UIOpenAPI JSON
RAGhttp://localhost:8001/docshttp://localhost:8001/openapi.json
Crawlerhttp://localhost:8002/docshttp://localhost:8002/openapi.json

​
API RAG

L’API RAG gère l’indexation et la recherche des documents. C’est le moteur derrière la base de connaissances.

​
Téléverser un document

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

file:      <fichier binaire>
file_id:   "unique-file-id"
sync:      "true"  (optionnel, attendre la fin de l'indexation)
metadata:  '{"source": "upload"}'  (JSON optionnel)
L’indexation tourne en arrière-plan par défaut. sync=true attend la fin avant de répondre.

​
Vérifier les statuts de documents

POST /api/v1/documents/statuses

{
  "file_ids": ["file-id-1", "file-id-2"]
}
Renvoie le statut d’indexation par document. États : queued, running, completed, failed.

​
Chercher dans la 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
}
file_ids est requis et cible la recherche sur des documents précis.

​
Supprimer un document

DELETE /api/v1/documents/{file_id}

​
Récupérer le contenu d’un document

GET /api/v1/documents/{file_id}/content
Renvoie le texte extrait complet d’un document indexé.

​
Comparer des documents

POST /api/v1/documents/compare

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

​
API Crawler

​
Enregistrer un site à crawler

POST /api/v1/websites

{
  "domain": "https://docs.example.com",
  "scan_interval": 21600
}
scan_interval en secondes. Minimum 60.

​
Récupérer le contenu d’une page

POST /api/v1/urls/fetch

{
  "urls": ["https://docs.example.com/guide"],
  "word_count_threshold": 100
}
Renvoie le contenu en cache si disponible, sinon fetch live.

​
Infos sur un site

GET /api/v1/websites/{domain}

​
Déréférencer un site

DELETE /api/v1/websites/{domain}

​
Lister les URLs d’un site

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

​
API Platform

Le service Platform expose une API publique sur /api/v1/* pour l’accès programmatique à tes données. Authentification par clé API depuis Paramètres > Clés API.

​
Chat completions compatibles OpenAI

La plateforme fournit une interface entièrement compatible avec l’API OpenAI Chat Completions. Tout client ou SDK supportant OpenAI (Python, Node, curl, LiteLLM, etc.) peut se connecter en pointant base_url vers ton instance Tale.

​
Quick start

from openai import OpenAI

client = OpenAI(
    base_url="https://your-tale-instance.com/api/v1",
    api_key="tale_...",  # depuis Paramètres > Clés API
    default_headers={"X-Organization-Slug": "default"},
)

response = client.chat.completions.create(
    model="chat-agent",  # slug d'agent de ta page Agents
    messages=[{"role": "user", "content": "Bonjour !"}],
)
print(response.choices[0].message.content)

​
Authentification

Toutes les requêtes exigent un bearer token dans l’en-tête Authorization : 
Authorization: Bearer tale_...
Crée les clés API dans Paramètres > Clés API de l’UI.

​
En-têtes

En-têteRequisDescription
AuthorizationOuiBearer <api-key>.
X-Organization-SlugNonslug d’organisation. Résolu automatiquement si le user n’appartient qu’à une.
X-Thread-IdNonréutiliser un fil de conversation entre requêtes.

​
Endpoints

POST /api/v1/chat/completions
Envoie un message de chat et reçoit une réponse. Supporte streaming et tool calling. Body de requête :
ChampTypeDescription
modelstringRequis. slug d’agent (ex. chat-agent).
messagesarrayRequis. messages de conversation avec role et content.
streambooleanactiver le streaming SSE. Défaut : false.
temperaturenumbertempérature de sampling (0–2).
max_tokensnumbertokens max à générer.
top_pnumberparamètre de nucleus sampling.
frequency_penaltynumberpénalise les tokens répétés.
presence_penaltynumberpénalise les tokens déjà présents.
stopstring ou arrayséquences d’arrêt.
response_formatobject{"type": "json_object"} pour mode JSON.
toolsarraydéfinitions d’outils pour tool calling côté client.
tool_choicestring ou object"auto", "required", "none" ou {"type":"function","function":{"name":"..."}}.
Deux modes :
  • Mode agent (sans tools) : l’agent utilise ses outils serveurs préconfigurés (RAG, recherche web, etc.) et les exécute automatiquement. La réponse contient le texte final.
  • Mode outils client (tools fournis) : seuls les outils définis par le client sont disponibles. Le modèle renvoie des tool_calls à exécuter côté client. Renvoie les résultats via des messages role: "tool".
Exemple de tool calling : 
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

# Étape 1 : envoyer les tools
response = client.chat.completions.create(
    model="chat-agent",
    messages=[{"role": "user", "content": "Quel temps fait-il ?"}],
    tools=tools,
    tool_choice="required",
)

# Étape 2 : exécuter l'outil et renvoyer le résultat
tc = response.choices[0].message.tool_calls[0]
messages = [
    {"role": "user", "content": "Quel temps fait-il ?"},
    response.choices[0].message.model_dump(),
    {"role": "tool", "tool_call_id": tc.id, "content": '{"temp": 20}'},
]
final = client.chat.completions.create(
    model="chat-agent", messages=messages, tools=tools
)
print(final.choices[0].message.content)
GET /api/v1/models
Liste les agents disponibles (modèles). 
{
  "object": "list",
  "data": [
    { "id": "chat-agent", "object": "model", "owned_by": "default" },
    { "id": "workflow-assistant", "object": "model", "owned_by": "default" }
  ]
}
Last modified on April 20, 2026