API REST

Shayan TaslimMis à jour

L’API REST UserJot permet à votre code d’accéder aux mêmes données de l’espace de travail que celles utilisées par le tableau de bord : métadonnées de l’espace de travail, tableaux, demandes (y compris les fusions, les demandes similaires, les tags, les abonnements et les pièces jointes), commentaires, votes, entrées du journal des modifications, membres (y compris l’effacement conformément au RGPD), entreprises, conversations, fichiers, ainsi que collections et articles du centre d’aide.

La référence interactive complète, qui comprend toutes les routes, tous les schémas et tous les exemples, est disponible sur userjot.com/docs/api et directement à l’adresse https://api.userjot.com/v1/docs. Le document OpenAPI qui la sous-tend se trouve à l’adresse https://api.userjot.com/v1/openapi.json (également disponible en miroir à l’adresse https://userjot.com/docs/api/openapi.json), afin que vous puissiez générer des clients typés dans votre langage.

URL de base et authentification

text
Base URL:      https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKEN

UserJot accepte deux types de jetons Bearer sur les routes /v1/* :

  • Jetons API : Créez un jeton dans Paramètres → MCP & API (administrateurs et propriétaires uniquement). Les jetons utilisent le préfixe uj_live_, sont associés à un seul espace de travail, n’expirent pas tant qu’ils ne sont pas révoqués et peuvent être renommés. Utilisez Maintenir pour révoquer (appuyez de manière prolongée) pour révoquer immédiatement un jeton ; les jetons révoqués restent répertoriés à des fins d’audit.

  • Jetons d’accès OAuth 2.0 : Prend en charge PKCE (S256), l’enregistrement dynamique des clients (/oauth/register), les documents de métadonnées d’identification client (CIMD), la révocation des jetons (/oauth/revoke) et les métadonnées de découverte aux adresses https://api.userjot.com/.well-known/oauth-authorization-server et https://api.userjot.com/.well-known/oauth-protected-resource/v1/mcp. Les jetons d’accès sont valables 1 heure et sont accompagnés de jetons d’actualisation renouvelés par rotation tous les 30 jours (portées workspace et offline_access). Ils restent valides uniquement tant que l’utilisateur qui a autorisé l’accès demeure propriétaire ou administrateur de cet espace de travail.

Une première requête

Bash
curl https://api.userjot.com/v1/boards \
  -H "Authorization: Bearer YOUR_USERJOT_API_TOKEN"

Limites de débit

Les requêtes API et MCP partagent le même quota de limites de débit pour l’espace de travail :

Forfait

Par minute

Par heure

Gratuit

10 requêtes

150 requêtes

Starter

60 requêtes

1 500 requêtes

Professional

120 requêtes

5 000 requêtes

Des plafonds supplémentaires s’appliquent selon l’opération :

  • Fichiers : Les importations de fichiers, les téléversements multiparties et les images Markdown importées automatiquement partagent un plafond distinct par espace de travail de 20 requêtes par minute et 300 par heure (auxquelles s’ajoutent 20 par minute et 300 par heure pour la finalisation des téléversements).

  • Conversations sortantes (POST /v1/conversations) : Disponibles uniquement avec les forfaits payants, avec une limite de 5 par jour pour Starter et de 15 par jour pour Professional (renvoie 409 plan_feature_unavailable avec le forfait Free).

Lorsque la limite est dépassée, l’API renvoie HTTP 429 avec un en-tête Retry-After et error.details.retry_after_seconds.

Pagination, erreurs et idempotence

  • Pagination par curseur. Les points de terminaison de liste acceptent cursor et limit (jusqu’à 100 ; les valeurs par défaut varient selon le point de terminaison, par exemple 10 pour les listes détaillées comme /v1/requests et /v1/changelogs) et renvoient next_cursor pour passer à la page suivante.

  • Enveloppe d’erreur. Les réponses d’erreur renvoient { "error": { "code", "message", "details" } } et incluent un en-tête de réponse X-Request-Id dans chaque réponse. Parmi les codes courants : 422 validation_error (avec details.issues), 409 plan_limit_reached, 409 plan_feature_unavailable, 409 request_merged, 410 member_erased (sur GET/PATCH /v1/members/{member_id} après DELETE /v1/members/{member_id} l’effacement conformément au RGPD), 409 member_erased (sur les routes faisant référence à un membre effacé), 409 help_slug_taken et 409 help_version_conflict.

  • Idempotence. Envoyez un en-tête Idempotency-Key (conservé pendant 24 heures avec une empreinte du corps de la requête) pour réessayer en toute sécurité les requêtes de création sur huit routes : /v1/requests, /v1/changelogs, /v1/conversations, /v1/conversations/{conversation_id}/replies, /v1/conversations/{conversation_id}/notes, /v1/assets/import, /v1/help/articles et /v1/help/collections.

Ressources et images

Importez des images (PNG, JPEG, GIF ou WebP jusqu’à 10 Mio) de trois façons :

  • Téléversement multipartie : POST /v1/assets (createAsset, REST uniquement) téléverse une image en une seule requête multipart/form-data.

  • Importation depuis une URL : POST /v1/assets/import télécharge une image HTTPS publique dans le stockage de l’espace de travail.

  • Téléversement en trois étapes avec URL présignée : POST /v1/assets/uploads (en fournissant les valeurs exactes size_bytes ; jusqu’à 100 sessions de téléversement ouvertes par espace de travail) → PUT les octets vers l’URL présignée valable 30 minutes → POST /v1/assets/uploads/{upload_id}/complete.

Référencez les fichiers téléversés dans Markdown avec asset:<id>. Les URL d’images HTTPS publiques intégrées dans du Markdown envoyé aux routes du journal des modifications et des articles d’aide sont également importées automatiquement (jusqu’à 10 images intégrées par requête de journal des modifications et 20 par requête d’article du centre d’aide), et sont comptabilisées dans le plafond de fichiers de l’espace de travail.

Webhooks

Les webhooks sortants destinés aux clients ne sont pas encore disponibles. Pour recevoir des alertes d’équipe en temps réel, utilisez Connecter Slack ou Connecter Discord, ou interrogez les modifications à l’aide de l’API REST.

REST ou MCP

Le serveur MCP repose sur cette API et expose 98 des 100 opérations REST sous forme d’outils MCP (POST /v1/assets le téléversement multipartie et DELETE /v1/members/{member_id} l’effacement conformément au RGPD sont disponibles uniquement via REST). Utilisez l’API REST depuis votre propre serveur backend, vos automatisations ou le code de votre application lorsque vous souhaitez contrôler entièrement les requêtes et les réponses. Utilisez MCP pour connecter un client d’IA compatible avec le protocole Model Context Protocol.

Gestion des jetons

Traitez votre jeton API comme n’importe quel autre secret :

  • Ne l’inscrivez pas en dur dans des fichiers de configuration suivis par le contrôle de version.

  • Privilégiez les variables d’environnement ou un gestionnaire de secrets.

  • Dans la mesure du possible, utilisez des jetons distincts pour les différents environnements ou membres de l’équipe.

  • Révoquez les jetons dont vous n’avez plus besoin dans Paramètres → MCP & API en utilisant Maintenir pour révoquer.

Cet article a-t-il répondu à votre question ?