# API-Referenz

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

## Zusammenfassung

Indexierbare SEO-Referenz für die Nachrichten, Nummern, Webhooks, Kontakte und Abrechnungs-APIs von TextTree.

## Seiteninhalt


## Authentifizierung

Verwendet ein von TextTree ausgegebenes Bearer-Zugriffstoken `txt_...`. Token müssen Folgendes enthalten:
Für den Pfad erforderlicher Bereich, z. B. `messages:write`, `numbers:read`,
`numbers:write`, `mcp:read` oder `mcp:execute`. Ältere API-Schlüssel `txk_...` sind nicht vorhanden
Sie werden von Entwickler-API-Routen oder MCP-Routen nicht akzeptiert.

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

## Erstellen Sie ein Headless-Konto

```http
POST /api/v1/accounts
POST /mcp/accounts
```

Diese öffentlichen JSON-Endpunkte erstellen ein Agentenkonto mit Benutzername und Passwort ohne
E-Mail, Google OAuth oder Wallet-Authentifizierung. Beide Routen rufen denselben Fluss auf
und geben Sie einmalige Backup-Codes plus einen Token-Träger `txt_...` von zurück
TextBaum.

Erforderliche Felder:

- `username`
- `password`

`/api/v1/accounts` akzeptiert Felder auf der obersten Ebene. `/mcp/accounts` akzeptiert die
Dieselben Felder auf der obersten Ebene oder verschachtelt in `account`.

### curl

```bash
Curl https://api.texttree.ai/api/v1/accounts \
  -H „Inhaltstyp: application/json“ \
  -d '{
    „Benutzername“: „Agent-Demo“,
    „Passwort“: „Korrekte Pferdebatterieklammer“
  }'
```

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“
  }
}
```

Die Kontoerstellung ist auf eine erfolgreiche Kontoerstellung pro IP-Adresse beschränkt
alle fünf Minuten. Wiederholte erfolgreiche Erstellungsversuche kehren zurück
`429 account_creation_rate_limited` mit `retry_after_seconds`.

## SMS senden

```http
POST /api/v1/messages
```

Erforderliche Felder:

- `phone_number`
- `body`

Optionale Felder:

- `idempotency_key`
- `metadata`

API-Sendungen nutzen die automatische Absenderauswahl. Sendungen, die aus der App stammen, können
Wählen Sie eine verbundene Markennummer aus. TextTree behandelt den ausgewählten Absender als Teil des
idempotente Nachrichtenanforderung.

### curl

```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 Termin ist morgen um 9 Uhr.“,
    „idempotency_key“: „appointment-123-reminder“
  }'
```

### JavaScript

```js
const Antwort = Warten auf fetch("https://api.texttree.ai/api/v1/messages", {
  Methode: „POST“,
  Überschriften: {
    Autorisierung: `Bearer ${process.env.TEXTREE_ACCESS_TOKEN}`,
    „Content-Type“: „application/json“,
  },
  body: JSON.stringify({
    Telefonnummer: „+15551234567“,
    body: „Ihr Termin ist morgen um 9 Uhr.“,
    idempotency_key: „appointment-123-reminder“,
  }),
});

const { message } = waiting Response.json();
```

### Python

```py
importiere dich
Importanfragen

Antwort = Anfragen.post(
    „https://api.texttree.ai/api/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['TEXTREE_ACCESS_TOKEN']}"},
    json={
        „phone_number“: „+15551234567“,
        „body“: „Ihr Termin ist morgen um 9 Uhr.“,
        „idempotency_key“: „appointment-123-reminder“,
    },
    Zeitüberschreitung=10,
)

message = Response.json()["message"]
```

### Elixir

```Elixier
Mix.install([:req])

%{body: %{"message" => message}} =
  Erforderlicher Beitrag!(
    „https://api.texttree.ai/api/v1/messages",
    auth: {:bearer, System.fetch_env!("TEXTREE_ACCESS_TOKEN")},
    json: %{
      phone_number: "+15551234567",
      body: "Your appointment is tomorrow at 9 AM.",
      idempotency_key: "appointment-123-reminder"
    }
  )
```

Antwort:

```json
{
  „Nachricht“: {
    „id“: „msg_123“,
    „status“: „in der Warteschlange“
  }
}
```

## Nachrichtenstatus

```http
GET /api/v1/messages/{id}
```

### curl

```bash
Curl https://api.texttree.ai/api/v1/messages/msg_123 \
  -H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“
```

Antwort:

```json
{
  „Nachricht“: {
    „id“: „msg_123“,
    „status“: „geliefert“,
    „phone_number“: „+15551234567“,
    „Segmente“: 1,
    „cost_cents“: 1,
    „created_at“: „2026-04-28T14:00:00Z“
  }
}
```

Verwenden Sie die Seite „Nachrichten“, um die Zeitleiste, Webhooks und Abstürze zu debuggen.

Verwenden Sie ein `idempotency_key` mit einem ausgewählten Empfänger, Text, Kosten oder Absender erneut
unterschiedlich gibt einen Idempotenzkonflikt zurück.

## Telefonnummern

```http
GET /api/v1/numbers
POST /api/v1/numbers
```

`GET` erfordert `numbers:read`. `POST` erfordert `numbers:write` und kauft a
Nummer über die Grenze des TextTree-Messaging-Anbieters hinweg. `area_code` wird unterstützt
für die Absicht, lokale Rufnummern zu erwerben. Live-Käufe erfordern die Schutzbarriere
expliziter Kauf von Live-Nummern aus der Bereitstellung.

```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“
  }'
```

Antwort:

```json
{
  "Nummer": {
    „id“: „num_123“,
    „Nummer“: „+14155550123“,
    "Friendly_name": "Support-Hotline",
    „status“: „verbunden“,
    „compliance_status“: „ausstehend“
  },
  „webhook_configured“: false,
  „warning“: „provider_inbound_webhook_configuration_api_not_documented“
}
```