Twenty a été conçu pour être convivial pour les développeurs, offrant des API puissantes qui s’adaptent à votre modèle de données personnalisé. Nous fournissons quatre types d’API distincts pour répondre à différents besoins d’intégration.
Approche axée sur les développeurs
Twenty génère des API spécifiquement pour votre modèle de données :
- Pas besoin d’ID longs : Utilisez directement les noms de vos objets et champs dans les points de terminaison
- Objets standard et personnalisés traités à égalité : Vos objets personnalisés bénéficient du même traitement API que ceux intégrés
- Points de terminaison dédiés : Chaque objet et champ a son propre point de terminaison API
- Documentation personnalisée : Générée spécifiquement pour le modèle de données de votre espace de travail
Votre documentation API personnalisée est disponible sous Paramètres → API & Webhooks après la création d’une clé API. Comme Twenty génère des API qui correspondent à votre modèle de données personnalisé, la documentation est propre à votre espace de travail.
Les deux types d’API
API principale
Accessible sur /rest/ ou /graphql/
Travaillez avec vos enregistrements réels (les données) :
- Créer, lire, mettre à jour, supprimer People, Companies, Opportunities, etc.
- Interroger et filtrer les données
- Gérer les relations entre les enregistrements
API de métadonnées
Accessible sur /rest/metadata/ ou /metadata/
Gérez votre espace de travail et votre modèle de données :
- Créer, modifier ou supprimer des objets et des champs
- Configurer les paramètres de l’espace de travail
- Définir les relations entre les objets
REST vs GraphQL
Les API Core et Metadata sont disponibles aux formats REST et GraphQL :
| Format | Opérations disponibles |
|---|
| REST | CRUD, opérations par lot, upserts |
| GraphQL | Identique + upserts par lot, requêtes de relations en un seul appel |
Points d’accès API
| Environnement | URL de base |
|---|
| Cloud | https://api.twenty.com/ |
| Auto-hébergé | https://{your-domain}/ |
Authentification
Chaque requête API nécessite une clé API dans l’en-tête :
Authorization: Bearer YOUR_API_KEY
Créer une clé API
- Allez dans Paramètres → API & Webhooks
- Cliquez sur + Créer une clé
- Configurer:
- Nom : Nom descriptif pour la clé
- Date d’expiration : Date à laquelle la clé expire
- Cliquez sur Enregistrer
- Copiez immédiatement — la clé n’est affichée qu’une seule fois
Votre clé API donne accès à des données sensibles. Ne la partagez pas avec des services non fiables. Si elle est compromise, désactivez-la immédiatement et générez-en une nouvelle.
Attribuer un rôle à une clé API
Pour une meilleure sécurité, attribuez un rôle spécifique pour limiter l’accès :
- Allez dans Paramètres → Rôles
- Cliquez sur le rôle à attribuer
- Ouvrez l’onglet Attribution
- Sous Clés API, cliquez sur + Attribuer à une clé API
- Sélectionnez la clé API
La clé héritera des autorisations de ce rôle. Voir Autorisations pour plus de détails.
Gérer les clés API
Régénérer : Paramètres → API & Webhooks → Cliquez sur la clé → Régénérer
Supprimer : Paramètres → API & Webhooks → Cliquez sur la clé → Supprimer
Bac à sable API
Testez vos API directement dans le navigateur avec notre bac à sable intégré — disponible pour REST et GraphQL.
Accéder au bac à sable
- Allez dans Paramètres → API & Webhooks
- Créer une clé API (obligatoire)
- Cliquez sur REST API ou GraphQL API pour ouvrir le bac à sable
Ce que vous obtenez
- Documentation interactive : Générée pour votre modèle de données spécifique
- Tests en direct : Exécutez de véritables appels API sur votre espace de travail
- Explorateur de schéma : Parcourez les objets, champs et relations disponibles
- Générateur de requêtes : Construisez des requêtes avec l’autocomplétion
Le bac à sable reflète vos objets et champs personnalisés, de sorte que la documentation est toujours précise pour votre espace de travail.
Opérations par Lot
REST et GraphQL prennent en charge les opérations par lot :
- Taille du lot : Jusqu’à 60 enregistrements par requête
- Opérations : Créer, mettre à jour, supprimer plusieurs enregistrements
Fonctionnalités spécifiques à GraphQL :
- Upsert par lot : Créer ou mettre à jour en un seul appel
- Utilisez des noms d’objets au pluriel (par exemple,
CreateCompanies au lieu de CreateCompany)
Limites de débit
Les requêtes API sont limitées pour garantir la stabilité de la plateforme :
| Limite | Valeur |
|---|
| Requêtes | 100 appels par minute |
| Taille du lot | 60 enregistrements par appel |
Utilisez les opérations par lot pour maximiser le débit — traitez jusqu’à 60 enregistrements dans un seul appel API au lieu d’effectuer des requêtes individuelles.
