Spécification API

Réponse directe

Contrat OpenAPI lisible par machine et contrat REST API orienté client pour TextTree.

Contenu source

# Spécification API

TextTree publie un contrat statique OpenAPI 3.1 pour le REST API actuel :

- [OpenAPI JSON](/openapi.json)
- Serveur de production : `https://api.texttree.ai`
- Serveur local Phoenix : `http://localhost:4001`

La spécification est basée sur la feuille de route Phoenix et le registre de protocole MCP. C'est
destiné à l'évaluation des clients, à la génération de code et à la planification de l'intégration.

## Authentification

Les demandes authentifiées API REST et MCP nécessitent un jeton d'accès au porteur émis
par TextTree :

```http
Autorisation : Porteur $TEXTREE_ACCESS_TOKEN
```

Les jetons d'accès au porteur actuels commencent par `txt_...` et incluent des étendues telles que
`messages:write`, `campaigns:read`, `campaigns:write`, `numbers:read`,
`numbers:write`, `onboarding:read`, `onboarding:write`, `mcp:read` et
`mcp:execute`.

Les clés API `txk_...` héritées sont conservées en tant qu'enregistrements internes pour les flux de travail
historique. Ils ne sont pas acceptés par `/api/v1/messages`, `/api/v1/numbers`,
`/api/v1/campaigns`, `/mcp` ou `/mcp/tools`.

## Migration des clés héritées

Si un client possède encore une clé héritée `txk_...`, échangez-la une fois contre un jeton
porteur actuel `txt_...` :

```bash
boucle https://api.texttree.ai/api/v1/auth/migrate-legacy-key \
-H "Autorisation : Porteur $TEXTREE_LEGACY_API_KEY" \
-H "Type de contenu : application/json" \
-d '{"name": "Jeton du porteur de production"}'
```

En cas de succès, TextTree renvoie une fois le nouveau jeton du porteur et révoque la clé
hérité. Si la création du jeton échoue, la clé héritée n'est pas révoquée.

## Surfaces REST actuelles

Le fichier OpenAPI couvre :

- contrôles de santé publique
- démarrage du compte sans tête
- mise en file d'attente des messages sortants et requête d'état
- itinéraires de campagne, extraits et listes de contacts
- liste des numéros et itinéraires d'approvisionnement
- Itinéraires d'intégration et de financement programmatiques
- Itinéraires de gestion client MCP OAuth
- Enregistrement OAuth, échange de jetons et révocation
- points de terminaison recevant des webhooks pour SMS et les fournisseurs de financement
- transport natif JSON-RPC à partir des routes MCP et REST héritées des outils MCP

Pour plus de détails sur les méthodes natives MCP, utilisez la documentation [Compatibilité OpenAI MCP](/docs/openai-mcp/).
et depuis [MCP](/docs/mcp/). OpenAPI documente les points de terminaison de transport HTTP ;
Les descripteurs et schémas de l'outil MCP se trouvent dans la documentation MCP car ils sont
renvoyé via `tools/list` de JSON-RPC.

## Emballeurs d'erreurs

La plupart des échecs API renvoient un objet JSON avec une chaîne `error` :

```json
{
"erreur": "non autorisé"
}
```

Les échecs de portée incluent un chemin manquant ou une portée d'outil :

```json
{
"erreur": "insuffficient_scope",
"required_scope": "messages : écriture"
}
```

Les échecs de validation incluent des détails au niveau du champ :

```json
{
"erreur": "validation_failed",
"détails": {
"phone_number": ["doit contenir au moins 7 caractère(s)"]
  }
}
```

## Idempotence

`POST /api/v1/messages` accepte un `idempotency_key` facultatif. Réutilisez-le
clé avec le même destinataire, le même corps et le même coût renvoie le message existant avec
`"replayed": true`. La réutilisation de la même clé avec une charge utile différente renvoie
`409 idempotency_conflict`.

## Vérification

Les vérifications publiques en direct pour ce contrat sont :

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

Le comportement des points de terminaison authentifiés est couvert par les tests des pilotes.
Phoenix et MCP, car ce référentiel n'utilise pas de jetons client ou de support de production
pour la vérification des documents.