Zum Hauptinhalt springen
Jeder Tale-Dienst hat eine eigene REST-API. Sie werden intern zwischen Diensten genutzt, sind aber auch für die direkte Integration mit externen Systemen verfügbar.

​
Interaktive API-Dokumentation

Alle Python-Dienste bieten eine Swagger-UI zum Erkunden und Testen:
DienstSwagger-UI-URLOpenAPI-JSON
RAGhttp://localhost:8001/docshttp://localhost:8001/openapi.json
Crawlerhttp://localhost:8002/docshttp://localhost:8002/openapi.json

​
RAG-API

Die RAG-API übernimmt Dokumenten-Indizierung und -Suche. Sie ist die Engine hinter der Wissensdatenbank.

​
Ein Dokument hochladen

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

file:      <binäre Datei>
file_id:   "unique-file-id"
sync:      "true"  (optional, auf das Ende der Indizierung warten)
metadata:  '{"source": "upload"}'  (optional JSON-String)
Die Dokument-Indizierung läuft standardmäßig im Hintergrund. Setze sync=true, um auf ihren Abschluss zu warten, bevor die Antwort zurückkehrt.

​
Dokumenten-Status prüfen

POST /api/v1/documents/statuses

{
  "file_ids": ["file-id-1", "file-id-2"]
}
Liefert den Indizierungs-Status pro Dokument. Zustände: queued, running, completed, failed.

​
In der Wissensdatenbank suchen

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
}
Der Parameter file_ids ist Pflicht und beschränkt die Suche auf bestimmte Dokumente.

​
Ein Dokument löschen

DELETE /api/v1/documents/{file_id}

​
Dokument-Inhalt lesen

GET /api/v1/documents/{file_id}/content
Liefert den vollständigen extrahierten Text eines indizierten Dokuments.

​
Dokumente vergleichen

POST /api/v1/documents/compare

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

​
Crawler-API

​
Eine Website zum Crawling registrieren

POST /api/v1/websites

{
  "domain": "https://docs.example.com",
  "scan_interval": 21600
}
scan_interval ist in Sekunden. Minimum: 60.

​
Seiteninhalt abrufen

POST /api/v1/urls/fetch

{
  "urls": ["https://docs.example.com/guide"],
  "word_count_threshold": 100
}
Liefert gecachten Inhalt, wenn vorhanden, sonst wird live gefetcht.

​
Website-Info

GET /api/v1/websites/{domain}

​
Website deregistrieren

DELETE /api/v1/websites/{domain}

​
Website-URLs auflisten

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

​
Platform-API

Der Platform-Dienst bietet eine öffentliche API unter /api/v1/* für programmatischen Zugriff auf deine Daten. Authentifiziere dich mit einem API-Schlüssel aus Einstellungen > API-Schlüssel.

​
OpenAI-kompatible Chat-Completions

Die Plattform bietet ein Interface, das vollständig kompatibel mit der OpenAI Chat Completions API ist. Jeder Client oder jedes SDK, das OpenAI unterstützt (Python, Node, curl, LiteLLM etc.), kann per base_url auf deine Tale-Instanz zeigen.

​
Quick Start

from openai import OpenAI

client = OpenAI(
    base_url="https://your-tale-instance.com/api/v1",
    api_key="tale_...",  # aus Einstellungen > API-Schlüssel
    default_headers={"X-Organization-Slug": "default"},
)

response = client.chat.completions.create(
    model="chat-agent",  # Agent-Slug von deiner Agents-Seite
    messages=[{"role": "user", "content": "Hallo!"}],
)
print(response.choices[0].message.content)

​
Authentifizierung

Alle Requests brauchen ein Bearer-Token im Authorization-Header: 
Authorization: Bearer tale_...
API-Schlüssel erstellst du in der Plattform-UI unter Einstellungen > API-Schlüssel.
HeaderPflichtBeschreibung
AuthorizationJaBearer <api-key>.
X-Organization-SlugNeinOrganisations-Slug. Wird automatisch aufgelöst, wenn der Nutzer nur in einer Organisation ist.
X-Thread-IdNeinEinen Konversations-Thread über Requests hinweg wiederverwenden.

​
Endpoints

POST /api/v1/chat/completions
Sendet eine Chat-Nachricht und erhält eine Antwort. Unterstützt Streaming und Tool-Calling. Request-Body:
FeldTypBeschreibung
modelstringPflicht. Agent-Slug (z. B. chat-agent).
messagesarrayPflicht. Konversations-Nachrichten mit role und content.
streambooleanSSE-Streaming aktivieren. Standard: false.
temperaturenumberSampling-Temperatur (0–2).
max_tokensnumbermaximale Tokens zum Erzeugen.
top_pnumberNucleus-Sampling-Parameter.
frequency_penaltynumberwiederholte Tokens bestrafen.
presence_penaltynumberbereits vorhandene Tokens bestrafen.
stopstring oder arrayStopp-Sequenzen.
response_formatobject{"type": "json_object"} für JSON-Modus.
toolsarrayTool-Definitionen für Client-seitiges Tool-Calling.
tool_choicestring oder object"auto", "required", "none" oder {"type":"function","function":{"name":"..."}}.
Zwei Modi:
  • Agent-Modus (ohne tools): Der Agent nutzt seine vorkonfigurierten Server-Tools (RAG, Web-Suche etc.) und führt sie automatisch aus. Die Antwort enthält den Finaltext.
  • Client-Tool-Modus (tools übergeben): Nur die client-definierten Tools sind verfügbar. Das Modell liefert tool_calls zur Ausführung durch den Client. Die Ergebnisse sendest du per role: "tool"-Nachrichten zurück.
Tool-Calling-Beispiel: 
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Liefert Wetter für eine Stadt",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

# Schritt 1: Tools senden
response = client.chat.completions.create(
    model="chat-agent",
    messages=[{"role": "user", "content": "Wie ist das Wetter?"}],
    tools=tools,
    tool_choice="required",
)

# Schritt 2: Tool ausführen und Ergebnis zurück schicken
tc = response.choices[0].message.tool_calls[0]
messages = [
    {"role": "user", "content": "Wie ist das Wetter?"},
    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 der verfügbaren Agents (Modelle). 
{
  "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