API REST

Shayan TaslimActualizado

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

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

UserJot 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 en https://api.userjot.com/.well-known/oauth-authorization-server y https://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 (ámbitos workspace y offline_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

Bash
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, devuelve 409 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 cursor y limit (hasta 100; los valores predeterminados varían según el endpoint, por ejemplo, 10 en listas detalladas como /v1/requests y /v1/changelogs) y devuelven next_cursor para avanzar por las páginas.

  • Formato de los errores. Las respuestas de error devuelven { "error": { "code", "message", "details" } } e incluyen un encabezado de respuesta X-Request-Id en todas las respuestas. Entre los códigos más comunes están 422 validation_error (con details.issues), 409 plan_limit_reached, 409 plan_feature_unavailable, 409 request_merged, 410 member_erased (en GET/PATCH /v1/members/{member_id} después de DELETE /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_taken y 409 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/articles y /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 solicitud multipart/form-data.

  • Importación desde URL: POST /v1/assets/import descarga una imagen HTTPS pública al almacenamiento del espacio de trabajo.

  • Carga en tres pasos con URL prefirmada: POST /v1/assets/uploads (proporciona el size_bytes exacto; hasta 100 sesiones de carga abiertas por espacio de trabajo) → PUT los 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.

¿Respondió esto a tu pregunta?