Referencia REST
Todos los endpoints de lectura y escritura de la API REST de Reclee, agrupados por área.
La referencia documenta, endpoint por endpoint, cada ruta de la API REST: qué hace, qué parámetros recibe, qué devuelve y con qué errores puede contestar. Úsala para consultar un endpoint concreto; para entender el modelo general (autenticación, errores, paginación, idempotencia) empieza por Fundamentos de la API.
Todas las rutas cuelgan de la misma base y usan la misma API key:
curl "https://app.reclee.com/api/v1/job-posts" \
-H "Authorization: Bearer $RECLEE_API_KEY"En los ejemplos, $RECLEE_API_KEY es una variable de entorno con tu key (rcl_…).
Cómo leer cada endpoint
Cada área tiene su página. Dentro de ella, los endpoints se agrupan por recurso (un título de segundo nivel, por ejemplo «Vacantes» o «Notas») y cada endpoint lleva su propio título con el método y el path: GET /job-posts/{jobPostId}. Debajo vas a encontrar, en este orden:
- El método y el path, y qué hace en una o dos oraciones.
- Parámetros de ruta, Query y Body, cada uno en su tabla, con el tipo, si es obligatorio, el valor por defecto y los valores válidos.
- Un ejemplo con
curl. - Un ejemplo de respuesta. Los nombres de campo son los reales; cuando la respuesta es larga se muestra un extracto y se indica.
- Los errores propios de ese endpoint.
- La acción equivalente, cuando existe.
Parámetros de ruta
Lo que va entre llaves en el path ({jobPostId}, {applicationId}, {noteId}…) es el id del recurso: un UUID que devuelve la API en el campo id (o jobPostId, applicationId…) de otra respuesta. Todo se resuelve dentro del workspace de tu API key: un id que existe en otro workspace contesta igual que uno que no existe, 404 NOT_FOUND.
Query y body
- Los parámetros de query se validan. Las listas con filtros rechazan un parámetro que no conocen con
400 INVALIDen lugar de ignorarlo: un filtro mal escrito no te devuelve la lista entera. - El body va en JSON (
Content-Type: application/json). Un body que no es JSON contesta415 UNSUPPORTED_MEDIA_TYPE; uno que no es JSON válido,400 INVALID_JSON. Un body JSON pesa como máximo 1 MB salvo que la ruta diga otra cosa, y ningún request puede pasar de 4,5 MB (413 PAYLOAD_TOO_LARGE). - Cuando el body no pasa la validación, la respuesta es
400 INVALIDcondetails, que dice qué campo falló y por qué.
Respuestas
Una respuesta exitosa es el JSON del dato, sin envoltorio: un objeto, una lista o, en las listas paginadas, una página. Un DELETE que borra puede contestar 204 sin body. Todas las respuestas, exitosas o no, traen el header X-Request-Id: si necesitas que revisemos un request, cítalo.
Paginación
Las rutas marcadas como paginadas reciben page (desde 1, por defecto 1) y pageSize (de 1 a 200, por defecto 50) y contestan con una página:
{
"rows": [],
"total": 0,
"page": 1,
"pageSize": 50
}total cuenta todas las filas que cumplen el filtro, no solo las de la página. Detalle en Paginación.
Errores
Un error es siempre un objeto con error (un código estable en mayúsculas) y, según el caso, información extra: details en un INVALID, missing cuando al objeto le falta algo para la operación, suggestions con la acción que lo resuelve, retryAfterSeconds en un RATE_LIMITED. El status HTTP sale del código. Cada endpoint lista sus errores propios; los que valen para todas las rutas son:
| Código | Status | Cuándo |
|---|---|---|
UNAUTHENTICATED | 401 | Falta la API key, o no es válida. |
FORBIDDEN | 403 | Tu rol no puede hacer esa operación (por ejemplo, un VIEWER que escribe). |
SEAT_REQUIRED | 403 | La operación consume uso o créditos y tu rol no tiene asiento (COLLABORATOR). |
NOT_FOUND | 404 | El recurso no existe en tu workspace. |
INVALID | 400 | El body o la query no pasan la validación. |
RATE_LIMITED | 429 | Pasaste el límite de requests por minuto. |
UNEXPECTED | 500 | Falla de nuestro lado. Reintenta más tarde. |
La lista completa y cómo manejarlos está en Errores.
Lecturas, escrituras y acciones
Las lecturas son GET sobre recursos. Las escrituras de negocio van, sobre todo, por POST /actions/<tool>: el mismo ejecutor que usa el servidor MCP, con el mismo schema de entrada y la misma respuesta (que incluye next, qué sigue o qué falta). Muchas rutas de esta referencia también aceptan POST, PUT o PATCH sobre el recurso; cuando existe una acción que hace lo mismo, el endpoint la enlaza como Acción equivalente. Las acciones están documentadas en Acciones.
Las rutas que crean algo o gastan uso o créditos aceptan el header Idempotency-Key, para reintentar sin crear ni cobrar dos veces. Cada endpoint que lo acepta lo muestra en su ejemplo. Ver Idempotencia.
Borrar casi nunca es un DELETE
Una API key no borra datos de negocio. La mayoría de los DELETE contestan 405 DELETE_NOT_ALLOWED y, cuando hay una acción que archiva, cierra o edita en su lugar, la nombran en suggestions. Cada endpoint dice qué usar. Ver Borrados.
Rutas que usan IA o un proveedor de datos
Las rutas que redactan con IA (proponer criterios, redactar una descripción, armar un informe…) consumen uso de IA de tu plan; las que traen datos de un proveedor externo pueden consumir créditos. Las dos lo indican en su descripción. Ver Créditos y uso.
Áreas
| Área | Qué cubre | Rutas | Endpoints |
|---|---|---|---|
| Vacantes | Vacantes, su equipo, notas, criterios, preguntas de screening, etapas, links compartidos y match score | 39 | 56 |
| ATS | Postulaciones: etapa y estado, comentarios, etiquetas, compatibilidad, condiciones, scorecard, informe, screening y entrevistas | 65 | 86 |
| Talento | El pool de talento: perfiles, contactos, CVs, etiquetas, listas y búsquedas de talento | 60 | 75 |
| Perfiles | Lo que cuelga de un perfil: notas, etiquetas, listas, eventos e hitos | 6 | 8 |
| Sourcing | ICP de talento, definiciones de búsqueda, corridas de sourcing y longlists | 29 | 38 |
| CRM | Leads, contactos, actividad, pedidos y colocaciones | 32 | 45 |
| Career site | Configuración del sitio de empleo público y sus vacantes | 5 | 6 |
| Notificaciones | Notificaciones y preferencias | 6 | 7 |
| Cuenta y workspace | Tu perfil, el workspace, sus miembros y las API keys | 16 | 22 |
| Facturación | Plan, suscripción, créditos y uso | 17 | 21 |
| Ask Reclee | Las conversaciones con el asistente de Reclee | 5 | 8 |
| Ayuda y rutas públicas | Artículos de ayuda, planes públicos y el documento OpenAPI | 3 | 3 |
«Rutas» cuenta paths distintos; «Endpoints», cada combinación de método y path. POST /actions/<tool> no está en esta tabla: cada acción tiene su página en Acciones.