Taxy.io · API Reference

API Reference

Die Taxy.io Answers API ermöglicht die Integration von KI-gestützten Rechts- und Steuerantworten in eigene Systeme. Alle Antworten werden direkt von großen Sprachmodellen generiert und als Streaming-Response zurückgegeben.

Base URL

taxy-dashboard.vercel.app/api/v1

Auth

Bearer Token

Response

JSON / SSE Stream

ℹ Alle Anfragen müssen über HTTPS gestellt werden. Chat-Antworten werden als Server-Sent Events (SSE) gestreamt — der Client muss den Stream line-by-line lesen.

Authentifizierung

Jede Anfrage (außer GET /version) muss den API-Key als Bearer-Token im Authorization-Header enthalten. Keys beginnen immer mit sk-taxy-.

Authentifizierter Request

curl -X POST https://taxy-dashboard.vercel.app/api/v1/chat/message \
  -H "Authorization: Bearer sk-taxy-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query": "Welche Kündigungsfristen gelten nach BGB?"}'

⚠ API-Keys nie im Frontend-Code oder öffentlichen Repositories speichern. Verwende Umgebungsvariablen auf deinem Server.

Rate Limits

Anfragen werden pro API-Key und Tag begrenzt. Bei Überschreitung wird 429 Too Many Requests zurückgegeben.

Free

10

Anfragen / Tag

Basic

200

Anfragen / Tag

Plus / Enterprise

2.000

Anfragen / Tag

Fehlerbehandlung

Alle Fehler werden als JSON mit dem Feld error zurückgegeben.

200OK — Erfolgreiche Anfrage

201Created — Ressource erfolgreich angelegt

400Bad Request — Fehlende oder ungültige Parameter

401Unauthorized — API-Key fehlt oder ungültig

404Not Found — Ressource existiert nicht oder gehört nicht zu diesem Key

429Too Many Requests — Tageslimit erreicht

500Internal Server Error — Serverseitiger Fehler

Fehler-Response

{ "error": "Daily limit of 10 requests exceeded" }

POST /api/v1/chat/message

Frage stellen (Auto-Chat)

Stellt eine Frage und streamt die Antwort als SSE zurück. Erstellt automatisch eine neue Chat-Session. Ideal für einfache Einzelanfragen ohne Session-Management.

Request Body Content-Type: application/json

Feld	Typ	Pflicht	Beschreibung
query	string	required	Die Rechtsfrage im Klartext (alternativ: `message`)

curl

curl -X POST https://taxy-dashboard.vercel.app/api/v1/chat/message \
  -H "Authorization: Bearer sk-taxy-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"query": "Welche Kündigungsfristen gelten nach § 622 BGB?"}'

Python

import requests

API_KEY = "sk-taxy-xxxx"
BASE = "https://taxy-dashboard.vercel.app/api/v1"

resp = requests.post(
    f"{BASE}/chat/message",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"query": "Welche Kündigungsfristen gelten nach § 622 BGB?"},
    stream=True
)

for line in resp.iter_lines():
    if line.startswith(b"data: "):
        print(line[6:].decode())

JavaScript (Node.js)

const resp = await fetch("https://taxy-dashboard.vercel.app/api/v1/chat/message", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-taxy-xxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ query: "Welche Kündigungsfristen gelten nach § 622 BGB?" })
});

const reader = resp.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

Live ausprobieren Echte API · SSE Stream

API Key

Key holen

Frage / Query

Response

Response erscheint hier…

POST /api/v1/chat

Chat-Session anlegen

Legt eine benannte Chat-Session an. Danach können Nachrichten mit POST /chat/{id}/message in dieser Session geführt werden. Für Multi-Turn-Gespräche mit Kontext.

Request Body

Feld	Typ	Pflicht	Beschreibung
name	string	optional	Name der Session. Default: "New Chat"
meta	object	optional	Beliebige Metadaten (flat JSON)

Beispiel

curl -X POST https://taxy-dashboard.vercel.app/api/v1/chat \
  -H "Authorization: Bearer sk-taxy-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mandant Müller – Arbeitsrecht"}'

# Response: 201 Created
{
  "id":         "550e8400-e29b-41d4-a716-446655440000",
  "name":       "Mandant Müller – Arbeitsrecht",
  "created_at": "2026-03-05T10:00:00Z"
}

GET /api/v1/chat

Alle Chats abrufen

Gibt alle Chat-Sessions des API-Keys zurück, absteigend nach letzter Aktivität.

Beispiel

curl https://taxy-dashboard.vercel.app/api/v1/chat \
  -H "Authorization: Bearer sk-taxy-xxxx"

GET /api/v1/chat/{chat_id}

Chat abrufen

Gibt eine einzelne Chat-Session anhand ihrer ID zurück.

Beispiel

curl https://taxy-dashboard.vercel.app/api/v1/chat/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk-taxy-xxxx"

GET /api/v1/chat/{chat_id}/messages

Nachrichtenverlauf

Gibt alle Nachrichten einer Session zurück, chronologisch aufsteigend.

Response-Schema

[
  { "id": "...", "role": "user",      "content": "Welche Fristen...", "created_at": "..." },
  { "id": "...", "role": "assistant", "content": "Gemäß § 622 BGB...", "created_at": "..." }
]

GET /api/v1/chat/messages/daily-limit

Tageslimit abfragen

Zeigt die aktuelle Nutzung und das Tageslimit des API-Keys an.

Response

{ "used": 3, "limit": 10, "remaining": 7 }

PATCH /api/v1/chat/{chat_id}/message/{message_id}/feedback

Feedback zu Antwort

Bewertet eine Assistenten-Antwort als positiv oder negativ. Hilft bei der Qualitätsverbesserung.

Beispiel

curl -X PATCH https://taxy-dashboard.vercel.app/api/v1/chat/{chat_id}/message/{msg_id}/feedback \
  -H "Authorization: Bearer sk-taxy-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"feedback": "positive"}' # oder "negative"

DELETE /api/v1/chat/{chat_id}

Chat löschen

Löscht eine Chat-Session inkl. aller Nachrichten unwiderruflich.

Beispiel

curl -X DELETE https://taxy-dashboard.vercel.app/api/v1/chat/550e8400-... \
  -H "Authorization: Bearer sk-taxy-xxxx"

# Response: {"deleted": true}

POST /api/v1/folders

Ordner anlegen

Ordner dienen zur Organisation von Chat-Sessions, z.B. nach Mandant oder Rechtsgebiet.

Beispiel

curl -X POST https://taxy-dashboard.vercel.app/api/v1/folders \
  -H "Authorization: Bearer sk-taxy-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mandant Müller"}'

GET /api/v1/folders

Alle Ordner abrufen

Gibt alle Ordner des API-Keys zurück. Mit /folders/with-chats werden die zugehörigen Chats mitgeliefert.

Noch kein API Key?