API REST
La API REST de UserJot proporciona a tu código acceso a los mismos datos del espacio de trabajo que usa el panel: metadatos del espacio de trabajo, tableros, solicitudes (incluidas las combinaciones, las solicitudes similares, las etiquetas, las suscripciones y los archivos adjuntos), comentarios, votos, entradas del registro de cambios, miembros (incluida la eliminación conforme al RGPD), empresas, conversaciones, recursos y colecciones y artículos del Centro de ayuda.
La referencia interactiva completa, con todas las rutas, esquemas y ejemplos, está disponible en userjot.com/docs/api y directamente en https://api.userjot.com/v1/docs. El documento OpenAPI en el que se basa está en https://api.userjot.com/v1/openapi.json (también disponible en https://userjot.com/docs/api/openapi.json), para que puedas generar clientes con tipos en tu lenguaje.
URL base y autenticación
Base URL: https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKENUserJot acepta dos tipos de tokens Bearer en las rutas /v1/*:
Tokens de API: Crea un token en Configuración → MCP & API (solo para administradores y propietarios). Los tokens usan el prefijo
uj_live_, pertenecen a un solo espacio de trabajo, no caducan hasta que se revoquen y se pueden cambiar de nombre. Usa Mantén pulsado para revocar (mantén pulsado) para revocar un token de inmediato; los tokens revocados siguen apareciendo en la lista para conservar el historial de auditoría.Tokens de acceso OAuth 2.0: Admite PKCE (
S256), el registro dinámico de clientes (/oauth/register), documentos de metadatos de ID de cliente (CIMD), la revocación de tokens (/oauth/revoke) y metadatos de descubrimiento enhttps://api.userjot.com/.well-known/oauth-authorization-serveryhttps://api.userjot.com/.well-known/oauth-protected-resource/v1/mcp. Los tokens de acceso duran 1 hora y se usan con tokens de actualización rotatorios de 30 días (ámbitosworkspaceyoffline_access); solo siguen siendo válidos mientras el usuario que los autorizó siga siendo propietario o administrador de ese espacio de trabajo.
Una primera solicitud
curl https://api.userjot.com/v1/boards \
-H "Authorization: Bearer YOUR_USERJOT_API_TOKEN"Límites de solicitudes
Las solicitudes de API y MCP comparten el mismo límite de solicitudes del espacio de trabajo:
Plan | Por minuto | Por hora |
|---|---|---|
Free | 10 solicitudes | 150 solicitudes |
Starter | 60 solicitudes | 1.500 solicitudes |
Professional | 120 solicitudes | 5.000 solicitudes |
También se aplican límites adicionales específicos para cada operación:
Recursos: Las importaciones de recursos, las cargas multiparte y las imágenes Markdown importadas automáticamente comparten un límite independiente del espacio de trabajo de 20 solicitudes por minuto y 300 por hora (más 20 por minuto y 300 por hora para completar las cargas).
Conversaciones salientes (
POST /v1/conversations): Disponibles solo en los planes de pago; el límite es de 5 al día en Starter y de 15 al día en Professional (en Free, devuelve409 plan_feature_unavailable).
Cuando se supera un límite, la API devuelve HTTP 429 con un encabezado Retry-After y error.details.retry_after_seconds.
Paginación, errores e idempotencia
Paginación con cursores. Los endpoints de listas aceptan
cursorylimit(hasta100; los valores predeterminados varían según el endpoint, por ejemplo,10en listas detalladas como/v1/requestsy/v1/changelogs) y devuelvennext_cursorpara avanzar por las páginas.Formato de los errores. Las respuestas de error devuelven
{ "error": { "code", "message", "details" } }e incluyen un encabezado de respuestaX-Request-Iden todas las respuestas. Entre los códigos más comunes están422 validation_error(condetails.issues),409 plan_limit_reached,409 plan_feature_unavailable,409 request_merged,410 member_erased(enGET/PATCH /v1/members/{member_id}después deDELETE /v1/members/{member_id}la eliminación conforme al RGPD),409 member_erased(en rutas que hacen referencia a un miembro eliminado),409 help_slug_takeny409 help_version_conflict.Idempotencia. Envía un encabezado
Idempotency-Key(que se almacena durante 24 horas junto con una huella digital del cuerpo de la solicitud) para reintentar de forma segura las solicitudes de creación en ocho rutas:/v1/requests,/v1/changelogs,/v1/conversations,/v1/conversations/{conversation_id}/replies,/v1/conversations/{conversation_id}/notes,/v1/assets/import,/v1/help/articlesy/v1/help/collections.
Recursos e imágenes
Carga imágenes (PNG, JPEG, GIF o WebP de hasta 10 MiB) de tres maneras:
Carga multiparte:
POST /v1/assets(createAsset, solo REST) carga una imagen en una sola solicitudmultipart/form-data.Importación desde URL:
POST /v1/assets/importdescarga una imagen HTTPS pública al almacenamiento del espacio de trabajo.Carga en tres pasos con URL prefirmada:
POST /v1/assets/uploads(proporciona elsize_bytesexacto; hasta 100 sesiones de carga abiertas por espacio de trabajo) →PUTlos bytes a la URL prefirmada, válida durante 30 minutos →POST /v1/assets/uploads/{upload_id}/complete.
Haz referencia a los recursos cargados en Markdown con asset:<id>. Las URL públicas de imágenes HTTPS incrustadas en Markdown y enviadas a los endpoints del registro de cambios y de los artículos de ayuda también se importan automáticamente (hasta 10 imágenes insertadas por solicitud del registro de cambios y 20 por solicitud de artículo del Centro de ayuda), y cuentan para el límite de recursos del espacio de trabajo.
Webhooks
Los webhooks salientes para clientes aún no están disponibles. Para recibir alertas del equipo en tiempo real, usa Connect Slack o Connect Discord, o consulta los cambios mediante la API REST.
REST o MCP
El servidor MCP está basado en esta API y expone 98 de las 100 operaciones REST como herramientas MCP (POST /v1/assets para cargas multiparte y DELETE /v1/members/{member_id} para la eliminación conforme al RGPD solo están disponibles mediante REST). Usa la API REST desde tu propio backend, automatización o código de aplicación cuando quieras tener control total sobre las solicitudes y respuestas. Usa MCP para conectar un cliente de IA compatible con el Model Context Protocol.
Gestión de tokens
Trata tu token de API como cualquier otro secreto:
No incluyas el token directamente en archivos de configuración confirmados en el repositorio.
Es preferible usar variables de entorno o un administrador de secretos.
Siempre que sea posible, usa tokens distintos para cada entorno o miembro del equipo.
Revoca los tokens que ya no necesites en Configuración → MCP & API usando Mantén pulsado para revocar.