# Entwickler-API

Kanonische URL: https://texttree.ai/de/docs/developer-api/
Markdown-URL: https://texttree.ai/de/docs/developer-api.md
Seitentyp: docs
Translation status: draft
Legal status: english_controls

## Zusammenfassung

Nachrichtenversand und Statusverträge für die aktuelle TextTree-Alpha-API.

## Seiteninhalt

# API für Entwickler

Die aktuelle JSON-API ist absichtlich eng. Es konzentriert sich auf einen kritischen Produktionspfad:
Stellen Sie ausgehende SMS in die Warteschlange und überprüfen Sie deren Status.

## Basis-URL

Die lokale Entwicklung mit Phoenix läuft unter `http://localhost:4001`.

Alle dokumentierten Entwicklerendpunkte leben unter `/api/v1`.

## Authentifizierung

Für authentifizierte Aufrufe der API ist ein von TextTree ausgestelltes Bearer-Zugriffstoken `txt_...` erforderlich.
Für die Browser-App, die Entwickler-API und wird dasselbe lokale Identitätsmodell verwendet
MCP-Routen. Legacy-API-Schlüssel `txk_...` werden als interne Datensätze aufbewahrt und sind es nicht
werden von `/api/v1/messages` akzeptiert.

```http
Autorisierung: Inhaber <textree_access_token>
Akzeptieren: application/json
```

`POST /api/v1/messages` erfordert `messages:write`. Anzahl der Inventarendpunkte
erfordern `numbers:read` oder `numbers:write`. E-Mail-Identitäten, Google,
Wallet und Agent werden zuvor auf dieselbe lokale TextTree-Identität normalisiert
Autorisierung.

## Headless-Kontostart

AI- und API-Kunden können ein Konto ohne E-Mail, Google OAuth oder erstellen
Wallet-Authentifizierung mit Benutzername und Passwort beim Booten.

`POST /api/v1/accounts`

Diese Route ist öffentlich, nur JSON und auf die erfolgreiche Kontoerstellung beschränkt
pro IP-Adresse alle fünf Minuten. TextTree speichert einen Hash der IP-Adresse
das Beschränkungsregister; Die Roh-IP wird nicht gespeichert.

### Anforderungstext

```json
{
  „Benutzername“: „Agent-Demo“,
  „Passwort“: „Korrekte Pferdebatterieklammer“
}
```

### Erfolgreiche Antwort

```json
{
  "Konto": {
    „id“: „9d7d9df7-58a0-4716-b82e-7ad5e73f7b36“,
    „Benutzername“: „agent-demo“
  },
  „backup_codes“: [„YYYY-BBBB-CCCC-DDDD“],
  „Token“: {
    „Typ“: „Träger“,
    „access_token“: „txt_…“,
    „scopes“: [„mcp:read“, „mcp:execute“, „messages:write“],
    „expires_at“: „2026-06-03T15:30:00Z“
  }
}
```

Speichern Sie den Token-Inhaber `txt_...` und die Sicherungscodes sofort. Die E-Mail
Interne Synthese, der Token-Hash, das Passwort und der drosselnde IP-Hash werden nie zurückgegeben.

### Fehler

- `422` mit `{"error":"validation_failed","details":...}` für ungültige oder doppelte Benutzernamen
  oder ungültige Passwörter
- `429` mit `{"error":"account_creation_rate_limited","retry_after_seconds":...}` wenn die
  Die IP des Antragstellers hat in den letzten fünf Minuten bereits ein Konto erstellt

## Gesundheit

`GET /api/v1/health`

Diese Route ist öffentlich und eignet sich für Bereitstellungsüberprüfungen und lokale Schnelltests.

## Eine ausgehende Nachricht in die Warteschlange stellen

`POST /api/v1/messages`

### Anforderungstext

```json
{
  „phone_number“: „+15551234567“,
  „body“: „Ihr Bestätigungscode ist 482019“,
  „estimated_cost_cents“: 2,
  „idempotency_key“: „msg_2026_04_26_0001“,
  „Metadaten“: {
    „Kampagne“: „Alpha-Einladung“,
    „Quelle“: „API“
  }
}
```

### Felder

- `phone_number`: Telefonnummer des Empfängers im E.164-Format, erforderlich
- `body`: erforderliche Zeichenfolge, 1 bis 1600 Zeichen
- `estimated_cost_cents`: optionale positive Ganzzahl, standardmäßig die konfigurierten SMS-Kosten
- `idempotency_key`: optionale Zeichenfolge, 8 bis 128 Zeichen, pro Benutzer gültig
- `metadata`: optionales JSON-Objekt

`phone_number` ist das Empfängerfeld von V1. Senden Sie `to` nicht, es sei denn, eine zukünftige Version der API dokumentiert dies ausdrücklich.
API-Sendungen nutzen die automatische Absenderauswahl. Übermittlungen aus der Browser-App können
Wählen Sie eine verbundene Markennummer; Der ausgewählte Absender wird Teil des
idempotente Nachrichtenanforderung.

### locken

```bash
Curl https://api.texttree.ai/api/v1/messages \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „phone_number“: „+15551234567“,
    „body“: „Ihr Bestätigungscode ist 482019“,
    „idempotency_key“: „msg_2026_04_26_0001“
  }'
```

### Erfolgreiche Antworten

Neu in die Warteschlange gestellte Nachrichten geben `202 Accepted` zurück:

```json
{
  „Nachricht“: {
    „id“: „8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb“,
    „status“: „in der Warteschlange“,
    „phone_number“: „+15551234567“,
    „body“: „Ihr Bestätigungscode ist 482019“,
    „provider“: „messaging_provider“,
    „consent_status“: „fehlt“,
    „external_id“: null,
    „estimated_cost_cents“: 2,
    „idempotency_key“: „msg_2026_04_26_0001“,
    „Metadaten“: {
      „Kampagne“: „Alpha-Einladung“,
      „Quelle“: „API“
    },
    „inserted_at“: „2026-04-26T20:44:12Z“,
    „updated_at“: „2026-04-26T20:44:12Z“,
    "Links": {
      „self“: „/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb“
    }
  },
  „wiedergegeben“: falsch
}
```

Wenn derselbe Benutzer dasselbe `idempotency_key` mit derselben Nachrichtennutzlast abspielt
und der gleichen Absenderauswahl gibt TextTree `200 OK` mit der vorhandenen Nachricht zurück
und `"replayed": true`.

### Fehlerantworten

- `422` mit `{"error":"validation_failed","details":...}`, wenn der Körper schlecht geformt ist
- `403` mit `{"error":"workspace_suppressed"}`, wenn der Empfänger durch eine Arbeitsbereichslöschung blockiert wird
- `402` mit `{"error":"spend_limit_exceeded"}`, wenn das aktuelle Ausgabenlimit überschritten würde
- `409` mit `{"error":"idempotency_conflict"}`, wenn ein Idempotenzschlüssel mit a wiederverwendet wird
  unterschiedlicher Empfänger, Körper, Kosten oder Absender
- `422` oder anbieterbezogene Fehlerdetails, wenn ein ausgewählter App-Absender nicht mehr verfügbar ist
  steht für den Arbeitsbereich zur Verfügung

## Überprüfen Sie den Status einer Nachricht

`GET /api/v1/messages/:id`

Dadurch wird derselbe `message`-Wrapper zurückgegeben, der in den Build-Antworten verwendet wird.

Der aktuelle Lebenszyklus eines Nachrichtenstatus ist:

- `queued`
- `dispatching`
- `sent`
- `delivered`
- `failed`
- `blocked`

`external_id` wird abgeschlossen, sobald die lieferantenorientierte Ausführung über eine stabile Lieferantenkennung verfügt.

### Statusbeispiel

```bash
Curl https://api.texttree.ai/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“
```

```json
{
  „Nachricht“: {
    „id“: „8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb“,
    „status“: „geliefert“,
    „phone_number“: „+15551234567“,
    „estimated_cost_cents“: 2,
    "Links": {
      „self“: „/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb“
    }
  }
}
```

## Vor dem Senden

Die Kontoerstellung wird mit `POST /api/v1/accounts` und gebootet
`POST /mcp/accounts`, für ausgehendes Senden muss jedoch weiterhin der Arbeitsbereich konfiguriert werden.
Bevor `POST /api/v1/messages` in einem neuen Arbeitsbereich erfolgreich sein kann, muss der Aufrufer bzw
Der Betreiber muss:

- Authentifizieren Sie sich über TextTree und fügen Sie ein Token mit `messages:write` hinzu
- Bestätigen Sie, dass für den Empfänger kein aktiver Arbeitsbereich gelöscht wird
- Legen Sie ein aktives Ausgabenlimit für `/app` fest
- Legen Sie einen Testabsender, eine Live-Absendernummer oder einen automatischen Absendermodus fest

## Numbers-API

`GET /api/v1/numbers` erfordert `numbers:read`.

`POST /api/v1/numbers` erfordert `numbers:write` und kauft eine Nummer über das
Limit des TextTree-Messaging-Anbieters. Enthält ein `area_code`, wenn das
Betreiber möchte eine lokale Nummer. Live-Käufe bleiben bis zur Bereitstellung blockiert
Aktivieren Sie explizit die Schutzbarriere für den Kauf von Live-Nummern.

```bash
Curl https://api.texttree.ai/api/v1/numbers \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
  -H „Inhaltstyp: application/json“ \
  -d '{
    "area_code": "415",
    „Friendly_name“: „Support-Hotline“
  }'
```

Erfolgreiche Käufe geben `201 Created` zurück:

```json
{
  "Nummer": {
    „id“: „b86fbe4d-2b92-4664-8e91-d2ed1d37f827“,
    „Nummer“: „+14155550123“,
    "Friendly_name": "Support-Hotline",
    „capabilities“: [„sms“],
    „status“: „verbunden“,
    „inbound_webhook_url“: „https://app.texttree.ai/webhooks/provider/incoming",
    „compliance_status“: „ausstehend“
  },
  „webhook_configured“: false,
  „warning“: „provider_inbound_webhook_configuration_api_not_documented“
}
```

## Aktuelle Alpha-Phasen-Grenzwerte

Die Entwickler-API stellt derzeit Folgendes **nicht** zur Verfügung:

- Aus Einwilligungs-/Kontaktmetadaten geerbte CRUD-Endpunkte
– CRUD-Endpunkte aus Arbeitsbereichslöschungen
- Ausgabenlimits für CRUD-Endpunkte
- direkte Erstellung von Finanzierungssitzungen; Verwenden Sie Onboarding-Finanzierungsrechnungen für Startaufladungen