API-Spezifikation

Direkte Antwort

Maschinenlesbarer OpenAPI-Vertrag und clientseitiger REST-API-Vertrag für TextTree.

Seiteninhalt

# API-Spezifikation

TextTree veröffentlicht einen statistischen OpenAPI 3.1-Vertrag für die aktuelle REST-API:

- [OpenAPI JSON](/openapi.json)
- Produktionsserver: `https://api.texttree.ai` 
- Lokaler Phoenix-Server: `http://localhost:4001` 

Die Spezifikation basiert auf der Phoenix Route Map und der MCP-Protokollregistrierung. Es ist
Zur Kundenbewertung, Codegenerierung und Integrationsplanung vorgesehen.

## Authentifizierung

Für authentifizierte REST-API- und MCP-Anfragen ist die Ausgabe eines Bearer-Zugriffstokens erforderlich
von TextTree:

```http
Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN
```

Aktuelle Trägerzugriffstoken beginnen mit `txt_...` und umfassen Bereiche wie
`messages:write`, `campaigns:read`, `campaigns:write`, `numbers:read`,
`numbers:write`, `onboarding:read`, `onboarding:write`, `mcp:read` und
`mcp:execute` .

Legacy-API-Schlüssel`txk_...` werden als interne Datensätze für Workflows gespeichert
historisch. Sie werden nicht akzeptiert von `/api/v1/messages`, `/api/v1/numbers`,
`/api/v1/campaigns`, `/mcp` oder `/mcp/tools`.

## Legacy-Schlüsselmigration

Wenn ein Client noch über einen Legacy-Schlüssel `txk_...` verfügt, ändern Sie ihn einmal in einen Token
aktueller Träger`txt_...`:

```bash
Locken https://api.texttree.ai/api/v1/auth/migrate-legacy-key \
  -H „Autorisierung: Inhaber $TEXTREE_LEGACY_API_KEY“ \
  -H „Inhaltstyp: application/json“ \
  -d '{"name":"Produktionsträger-Token"}'
```

Bei Erfolg gibt TextTree das neue Inhaber-Token einmal zurück und widerruft den Schlüssel
geerbt. Wenn die Tokenerstellung fehlschlägt, wird der geerbte Schlüssel nicht widerrufen.

## Aktuelle REST-Oberflächen

Die OpenAPI-Datei umfasst:

- öffentliche Gesundheitskontrollen
- Headless-Kontostart
- Warteschlange ausgegebener Nachrichten und Statusabfrage
- Kampagnenrouten, Snippets und Kontaktlisten
- Nummernauflistung und Bereitstellungsrouten
- Programmatische Onboarding- und Finanzierungswege
- MCP-OAuth-Client-Verwaltungsrouten
- OAuth-Registrierung, Token-Austausch und Widerruf
- Webhook-Empfangsendpunkte für SMS- und Finanzierungsanbieter
- MCP nativer JSON-RPC-Transport und REST-Routen, geerbt von MCP-Tools

Einzelheiten zu nativen MCP-Methoden finden Sie in den Dokumenten zur [OpenAI MCP-Kompatibilität] (/docs/openai-mcp/).
und von [MCP](/docs/mcp/). OpenAPI dokumentierte HTTP-Transportendpunkte;
MCP-Tool-Deskriptoren und -Schemas leben in MCP-Dokumenten, weil sie es sind
Zurückgegeben über JSON-RPC`tools/list`.

## Fehler-Wrapper

Die meisten API-Fehler geben ein JSON-Objekt mit der Zeichenfolge `error` zurück:

```json
{
  „Fehler“: „nicht autorisiert“
}
```

Zu den Bereichsfehlern zählen fehlende Pfade oder Werkzeugbereiche:

```json
{
  „error“: „insuffizienter_Bereich“,
  „required_scope“: „messages:write“
}
```

Validierungsfehler umfassen Details auf Feldebene:

```json
{
  „error“: „validation_failed“,
  „Details“: {
    „Telefonnummer“: [„sollte mindestens 7 Zeichen lang sein“]
  }
}
```

## Idempotenz

`POST /api/v1/messages`akzeptiert einen optionalen `idempotency_key`. Wiederverwenden
Schlüssel mit demselben Empfänger, demselben Text und denselben Kosten gibt die Nachricht mit zurück
`"replayed": true` . Die Wiederverwendung desselben Schlüssels mit einem anderen Nutzlast führt zur Rückgabe
`409 idempotency_conflict` .

## Verifizierung

Die öffentlichen Live-Verifizierungen für diesen Vertrag sind:

```bash
Locken https://api.texttree.ai/health 
Locken https://api.texttree.ai/api/v1/health 
Locken https://api.texttree.ai/mcp/health 
Locken https://api.texttree.ai/.well-known/oauth-protected-resource/mcp 
Locken https://api.texttree.ai/.well-known/oauth-authorization-server/mcp 
```

Das Verhalten authentifizierter Endpunkte wird durch die Treibertests abgedeckt.
Phoenix und MCP stellen diese Repositorys bereit, ohne dass Client- oder Productions-Bearer-Token verwendet werden
zur Überprüfung der Dokumentation.