PJT AI REST API
Una API REST estándar para integrar los datos de PJT AI con sistemas externos. Todas las solicitudes y respuestas son JSON, y la URL base es https://api.pjt.ai/api/external/v1.
- Autenticación — cabecera X-API-Key (API key de cuenta, prefijo pjt_)
- Ámbitos de la clave — read (solo lectura, por defecto) / write. POST·PUT·DELETE requieren una clave con ámbito write — de lo contrario 403 SCOPE_FORBIDDEN
- Límite — 60 req/min + 10 000 req/mes por clave (Enterprise a convenir)
- Códigos de respuesta — 2xx éxito, 4xx error del cliente, 5xx error del servidor
- Fechas — todas las marcas de tiempo son ISO 8601 (UTC)
Autenticación
Cada solicitud requiere la cabecera X-API-Key: <API_KEY>. Emite claves en Configuración de cuenta > Claves API (se muestran solo una vez al crearlas).
/workspacesListar workspaces
Devuelve los workspaces accesibles para la cuenta de la API key.
/workspaces/{workspaceId}Obtener workspace
Devuelve un workspace.
| Nombre | Tipo | Descripción |
|---|---|---|
| workspaceIdREQUIRED | integer | ID del workspace |
/workspaces/{workspaceId}/projectsListar proyectos
Devuelve los proyectos activos del workspace (excluye cancelados/archivados).
| Nombre | Tipo | Descripción |
|---|---|---|
| workspaceIdREQUIRED | integer | ID del workspace |
/projectsCrear proyecto (idempotente)
Crea un proyecto. Con externalRef la llamada es idempotente — repetir el mismo (workspaceId, externalRef) devuelve el proyecto existente con 200 en lugar de crear uno nuevo (201 en la primera creación).
| Nombre | Tipo | Descripción |
|---|---|---|
| workspaceIdREQUIRED | integer | ID del workspace |
| nameREQUIRED | string | Nombre del proyecto |
| externalRef | string | Clave de idempotencia — repetir con el mismo valor devuelve el proyecto existente con 200 en lugar de crear uno nuevo |
| code | string | Código del proyecto (prefijo de clave de tarea). Se genera automáticamente si se omite |
| description | string | Descripción |
| clientIds | array | Array de IDs de clientes |
| managerId | integer | ID de cuenta del manager |
| startDate | date | Fecha de inicio — ISO 8601 (YYYY-MM-DD) |
| endDate | date | Fecha de fin — ISO 8601 (YYYY-MM-DD) |
| budget | integer | Presupuesto |
/projects/{projectId}Detalle / progreso del proyecto
Devuelve el detalle del proyecto: estado, progreso (%), fechas planificadas/reales y última modificación.
| Nombre | Tipo | Descripción |
|---|---|---|
| projectIdREQUIRED | string | ID del proyecto — ID numérico o publicId que empieza con p_ |
/projects/{projectId}Actualizar proyecto
Actualiza solo los campos enviados (actualización parcial).
| Nombre | Tipo | Descripción |
|---|---|---|
| projectIdREQUIRED | string | ID del proyecto — ID numérico o publicId que empieza con p_ |
| Nombre | Tipo | Descripción |
|---|---|---|
| name | string | Nombre del proyecto |
| status | enum | Estado — PLANNING·ESTIMATING·WAITING·IN_PROGRESS·ON_HOLD·COMPLETED·CANCELLED |
| progressRate | integer | Progreso (%) 0–100 |
| startDate | date | Fecha de inicio — ISO 8601 (YYYY-MM-DD) |
| endDate | date | Fecha de fin — ISO 8601 (YYYY-MM-DD) |
/projects/{projectId}Eliminar proyecto
Elimina un proyecto. Devuelve 204 No Content si tiene éxito (sin cuerpo).
| Nombre | Tipo | Descripción |
|---|---|---|
| projectIdREQUIRED | string | ID del proyecto — ID numérico o publicId que empieza con p_ |
/projects/{projectId}/timelineTimeline (hitos)
Hitos del proyecto — nombre, estado (PLANNED/IN_PROGRESS/COMPLETED), fecha límite, fecha de finalización y progreso. Ordenados por sortOrder.
| Nombre | Tipo | Descripción |
|---|---|---|
| projectIdREQUIRED | string | ID del proyecto — ID numérico o publicId que empieza con p_ |
/projects/{projectId}/activitiesActividades
Eventos de cambio de tareas del proyecto, del más reciente al más antiguo — tipo, mensaje, actor y hora.
| Nombre | Tipo | Descripción |
|---|---|---|
| projectIdREQUIRED | string | ID del proyecto — ID numérico o publicId que empieza con p_ |
| Nombre | Tipo | Descripción |
|---|---|---|
| page | integer | Número de página (desde 0, por defecto 0) |
| size | integer | Tamaño de página (por defecto 50, máx. 200) |
/projects/{projectId}/filesArchivos
Adjuntos de tareas y comentarios del proyecto combinados, del más reciente al más antiguo. fileUrl es una URL estática sin expiración.
| Nombre | Tipo | Descripción |
|---|---|---|
| projectIdREQUIRED | string | ID del proyecto — ID numérico o publicId que empieza con p_ |
| Nombre | Tipo | Descripción |
|---|---|---|
| limit | integer | Máximo de elementos (por defecto 100, máx. 500) |
/projects/{projectId}/tasksListar tareas
Devuelve las tareas de un proyecto. Usa /tasks/paged si necesitas paginación.
| Nombre | Tipo | Descripción |
|---|---|---|
| projectIdREQUIRED | string | ID del proyecto — ID numérico o publicId que empieza con p_ |
| Nombre | Tipo | Descripción |
|---|---|---|
| sortBy | string | Campo de ordenación (por defecto createdAt) |
/tasksCrear tarea
Crea una tarea.
| Nombre | Tipo | Descripción |
|---|---|---|
| projectIdREQUIRED | integer | ID del proyecto (numérico) |
| titleREQUIRED | string | Título |
| description | string | Descripción |
| assigneeId | integer | ID de cuenta del asignado |
| status | enum | Estado — PENDING·TODO·IN_PROGRESS·IN_REVIEW·BLOCKED·COMPLETED·CANCELLED |
| priority | enum | Prioridad — URGENT·HIGH·MEDIUM·LOW |
| dueDate | date | Fecha límite — ISO 8601 |
| milestoneId | integer | ID del hito a vincular |
/tasks/{taskId}Obtener tarea
Devuelve una tarea.
| Nombre | Tipo | Descripción |
|---|---|---|
| taskIdREQUIRED | integer | ID de la tarea |
/tasks/{taskId}Actualizar tarea
Actualiza solo los campos enviados.
| Nombre | Tipo | Descripción |
|---|---|---|
| taskIdREQUIRED | integer | ID de la tarea |
| Nombre | Tipo | Descripción |
|---|---|---|
| title | string | Título |
| status | enum | Estado — PENDING·TODO·IN_PROGRESS·IN_REVIEW·BLOCKED·COMPLETED·CANCELLED |
| priority | enum | Prioridad — URGENT·HIGH·MEDIUM·LOW |
| dueDate | date | Fecha límite — ISO 8601 |
/tasks/{taskId}Eliminar tarea
Elimina una tarea. Devuelve 204 No Content si tiene éxito.
| Nombre | Tipo | Descripción |
|---|---|---|
| taskIdREQUIRED | integer | ID de la tarea |
/tasks/assignedMis tareas asignadas
Devuelve las tareas asignadas a la cuenta de la API key.
/projects/{projectId}/documentsListar documentos
Devuelve los documentos de un proyecto. Usa /documents/paged si necesitas paginación.
| Nombre | Tipo | Descripción |
|---|---|---|
| projectIdREQUIRED | string | ID del proyecto — ID numérico o publicId que empieza con p_ |
/documents/{documentId}Obtener documento
Devuelve un documento incluyendo su contenido.
| Nombre | Tipo | Descripción |
|---|---|---|
| documentIdREQUIRED | integer | ID del documento |
/documentsCrear documento
Crea un documento.
| Nombre | Tipo | Descripción |
|---|---|---|
| workspaceIdREQUIRED | integer | ID del workspace |
| titleREQUIRED | string | Título |
| documentTypeREQUIRED | enum | Tipo de documento (p. ej. REQUIREMENT, MEETING_NOTE) |
| projectId | integer | ID del proyecto (numérico) |
| content | string | Cuerpo del documento |
| visibility | enum | Visibilidad — PUBLIC·TEAM·PRIVATE |
/documents/{documentId}Actualizar documento
Actualiza solo los campos enviados.
| Nombre | Tipo | Descripción |
|---|---|---|
| documentIdREQUIRED | integer | ID del documento |
| Nombre | Tipo | Descripción |
|---|---|---|
| title | string | Título |
| content | string | Cuerpo del documento |
| visibility | enum | Visibilidad — PUBLIC·TEAM·PRIVATE |
/documents/{documentId}Eliminar documento
Elimina un documento. Devuelve 204 No Content si tiene éxito.
| Nombre | Tipo | Descripción |
|---|---|---|
| documentIdREQUIRED | integer | ID del documento |
Códigos de error
Cada respuesta de error incluye error.code y error.message.
| Código | Nombre | Descripción | Acción |
|---|---|---|---|
| 400 | Bad Request | El cuerpo de la solicitud no es válido. | Valida el body de la solicitud |
| 401 | Unauthorized | La clave de API es inválida o falta. | Vuelve a comprobar la clave de API |
| 403 | Forbidden | No tienes permiso para acceder a este recurso. Las solicitudes de escritura con una clave de solo lectura devuelven SCOPE_FORBIDDEN. | Comprueba roles/ámbitos |
| 404 | Not Found | No se encontró el recurso solicitado. | Vuelve a comprobar el ID |
| 429 | Rate Limited | Has superado el límite de tasa. | Consulta la cabecera Retry-After y aplica backoff |
| 500 | Server Error | Se produjo un error al procesar la solicitud en el servidor. | Reintenta tras 5 min, revisa status.pjt.ai |