Reclee

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:

  1. El método y el path, y qué hace en una o dos oraciones.
  2. 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.
  3. Un ejemplo con curl.
  4. Un ejemplo de respuesta. Los nombres de campo son los reales; cuando la respuesta es larga se muestra un extracto y se indica.
  5. Los errores propios de ese endpoint.
  6. 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 INVALID en 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 contesta 415 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 INVALID con details, 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ódigoStatusCuándo
UNAUTHENTICATED401Falta la API key, o no es válida.
FORBIDDEN403Tu rol no puede hacer esa operación (por ejemplo, un VIEWER que escribe).
SEAT_REQUIRED403La operación consume uso o créditos y tu rol no tiene asiento (COLLABORATOR).
NOT_FOUND404El recurso no existe en tu workspace.
INVALID400El body o la query no pasan la validación.
RATE_LIMITED429Pasaste el límite de requests por minuto.
UNEXPECTED500Falla 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

ÁreaQué cubreRutasEndpoints
VacantesVacantes, su equipo, notas, criterios, preguntas de screening, etapas, links compartidos y match score3956
ATSPostulaciones: etapa y estado, comentarios, etiquetas, compatibilidad, condiciones, scorecard, informe, screening y entrevistas6586
TalentoEl pool de talento: perfiles, contactos, CVs, etiquetas, listas y búsquedas de talento6075
PerfilesLo que cuelga de un perfil: notas, etiquetas, listas, eventos e hitos68
SourcingICP de talento, definiciones de búsqueda, corridas de sourcing y longlists2938
CRMLeads, contactos, actividad, pedidos y colocaciones3245
Career siteConfiguración del sitio de empleo público y sus vacantes56
NotificacionesNotificaciones y preferencias67
Cuenta y workspaceTu perfil, el workspace, sus miembros y las API keys1622
FacturaciónPlan, suscripción, créditos y uso1721
Ask RecleeLas conversaciones con el asistente de Reclee58
Ayuda y rutas públicasArtículos de ayuda, planes públicos y el documento OpenAPI33

«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.

En esta página