Acciones
Cómo funcionan las escrituras de la API de Reclee, un POST por acción, y el índice de las 97 acciones.
Toda escritura de negocio de la API (crear una vacante, mover un candidato, generar un scorecard) es una acción: un POST a /actions/<nombre> con un body JSON. Las lecturas, en cambio, son GET sobre recursos (ver la referencia REST). Las acciones son exactamente las mismas que expone el servidor MCP, con el mismo nombre, el mismo schema y el mismo ejecutor: lo que hace una integración por REST lo hace un agente por MCP, y al revés.
Cómo se llama una acción
/actions/{tool}{tool}es el nombre exacto de la acción, ensnake_case:create_job_post,move_application_stage… El índice de abajo las lista todas.- El body es JSON (
Content-Type: application/json) de hasta 1 MB. Un body vacío se lee como{}, así que una acción sin campos obligatorios se puede llamar sin body. - La acción corre con los permisos de la persona dueña de la API key, como si lo hiciera ella desde la app.
- Una respuesta exitosa es siempre
200 OK.
Ejemplo: crear una vacante con lo mínimo.
curl -X POST https://app.reclee.com/api/v1/actions/create_job_post \
-H "Authorization: Bearer rcl_..." \
-H "Content-Type: application/json" \
-d '{
"title": "Data Analyst",
"country": "MX"
}'{
"data": {
"jobPostId": "7c1e9a52-3b4d-4f8e-9a21-5d6c7b8e9f01"
},
"links": [
{
"kind": "job_post",
"id": "7c1e9a52-3b4d-4f8e-9a21-5d6c7b8e9f01",
"label": "Data Analyst",
"href": "https://app.reclee.com/job-posts/new/manual/7c1e9a52-3b4d-4f8e-9a21-5d6c7b8e9f01"
}
],
"next": {
"missing": [
"description",
"seniority",
"employmentType",
"workplaceType"
],
"suggestions": [
{
"tool": "update_job_post",
"input": {
"jobPostId": "7c1e9a52-3b4d-4f8e-9a21-5d6c7b8e9f01"
}
}
]
},
"cost": {
"aiUsagePct": 0,
"teamUsagePct": 0,
"credits": 0,
"billedLater": false
}
}Validación del body
Cada acción valida el body con su propio schema, el mismo que publica el MCP y que aparece en el documento OpenAPI bajo /actions/{tool}. En cada página de acción, la tabla Body lo describe campo por campo.
Si el body no pasa, la acción no corre y la respuesta es 400 INVALID con details, que dice qué campo falló y por qué. Por ejemplo, create_job_post sin title:
{
"error": "INVALID",
"details": {
"errors": [],
"properties": {
"title": {
"errors": [
"Invalid input: expected string, received undefined"
]
}
}
}
}details.errors lleva los errores del body completo (por ejemplo, «envía al menos un campo») y details.properties.<campo>.errors los de cada campo. Un campo que el schema no conoce se rechaza: la respuesta es 400 INVALID y details nombra la clave sobrante, por ejemplo { "errors": ["Unrecognized key: \"force\""] }. Así un nombre mal escrito no se pierde en silencio. La especificación OpenAPI publica cada body con additionalProperties: false.
Algunas reglas solo se pueden comprobar contra los datos (un rango salarial contra lo guardado, una etapa que no corresponde). Cuando una de esas reglas rechaza el pedido, la respuesta también es 400 INVALID. Si la regla sabe qué campos fallaron, details.properties los nombra (Required para uno que falta, Invalid para uno rechazado) y el cuerpo puede traer también missing y suggestions; si no, details trae un mensaje genérico en errors. Cada página de acción dice en qué casos pasa.
Otros rechazos antes de correr: un body que no es JSON (400 INVALID_JSON), un Content-Type que no es JSON (415 UNSUPPORTED_MEDIA_TYPE) y un body de más de 1 MB (413 PAYLOAD_TOO_LARGE).
Nombres que no son acciones
- Un nombre que no existe responde
404con{ "error": "NOT_FOUND" }. - Un nombre que existe pero es una lectura (por ejemplo
get_job_postolist_applicationsdel MCP) responde405con{ "error": "METHOD_NOT_ALLOWED", "allowed": [] }y un headerAllowvacío: esa lectura se hace con suGETen la referencia REST.
Idempotency-Key
Todas las acciones aceptan el header Idempotency-Key (de 1 a 255 caracteres ASCII visibles). Con él, un reintento no vuelve a escribir ni a gastar:
- La primera llamada exitosa con esa clave guarda su respuesta durante 24 horas. Un reintento con la misma clave y el mismo body recibe esa respuesta sin ejecutar nada, con el header
Idempotent-Replayed: true. - La misma clave con otro body responde
422 IDEMPOTENCY_KEY_REUSED. Mientras la primera llamada sigue corriendo, un reintento responde409 IDEMPOTENCY_IN_FLIGHT. - Solo se guarda un éxito: si la acción respondió un error, la clave queda libre y el reintento vuelve a correr.
Úsalo siempre en las acciones GENERATE y PROVIDER, que gastan uso o créditos, y en las que crean algo. Detalle en Idempotencia.
Las cuatro familias
Cada acción pertenece a una familia, que dice qué toca y qué puede costar. La familia aparece al principio de cada acción.
| Familia | Qué hace | Costo |
|---|---|---|
DO | Escribe en vacantes, pipeline, entrevistas, talent pool y listas. | No consume créditos ni uso. |
CRM | Escribe en el CRM: leads, contactos, requests y su actividad. | No consume créditos ni uso. |
GENERATE | La IA escribe una propuesta o un borrador que la persona revisa en la app. | Uso de IA del plan. |
PROVIDER | Llama a un proveedor externo de datos o corre un cálculo medido. | Puede consumir créditos o uso del plan. |
DO y CRM. Escriben en el momento de la llamada. En la app, el asistente de Reclee le muestra a la persona una tarjeta para confirmar antes de escribir; por la API no hay ese paso, así que si tu integración actúa en nombre de una persona, confirma con ella antes de llamar. Antes de escribir, el servidor hace los mismos chequeos que esa confirmación: si alguno falla, la respuesta es un error y no se escribe nada.
GENERATE. Escribe sin confirmación porque solo escribe propuestas, borradores o contenido sobre algo vacío, y nunca pisa lo que una persona confirmó. Nada de lo que genera cuenta, ni llega a un cliente, hasta que alguien lo revisa en la app. Consume uso de IA del plan y puede tardar: el servidor espera la respuesta del modelo dentro del mismo request, hasta 5 minutos, así que configura un timeout acorde.
PROVIDER. Solo la puede usar una persona con asiento (si no, 403 SEAT_REQUIRED). Puede consumir créditos (por ejemplo, revelar un contacto) o uso del plan; la página de cada acción dice cuál. Si se agotó lo que necesita, la respuesta es un 402 que dice qué falta y cuándo vuelve: ver Créditos y uso.
La respuesta
Una acción exitosa responde un objeto con estos campos:
| Campo | Qué es |
|---|---|
data | Lo que la acción escribió o calculó: ids nuevos, conteos, el estado resultante. Su forma es propia de cada acción. |
links | Cada objeto que la acción tocó, con kind, id, label y href, la URL absoluta de su pantalla en la app. Puede venir vacío. |
next | Qué sigue: missing (lo que al objeto todavía le falta) y suggestions (las acciones que siguen, con los ids ya resueltos en input). No todas las acciones lo devuelven. |
cost | Solo en GENERATE y PROVIDER: lo que gastó esta llamada. |
links[].kind es uno de job_post, application, profile, longlist, lead, member, bookmark, request, talent_search o contact.
next.suggestions nombra siempre una acción o una lectura real del MCP. Cada sugerencia trae tool, input con los ids que necesita y, en las generaciones, readsFrom: de dónde leerá la IA (REQUEST, LEAD o PREVIOUS_STEPS, lo que el objeto ya tiene). Un tool que es una lectura se hace con su GET.
cost tiene cuatro campos:
aiUsagePct: la fracción del uso de IA del mes que consumió la llamada, de 0 a 1 (0.004es el 0,4 %);teamUsagePct: la fracción del uso compartido del equipo, de 0 a 1;credits: los créditos que consumió;billedLater:truecuando parte del costo se registra después de responder (por ejemplo, un trabajo que sigue en segundo plano).
Si el costo no se pudo leer, cost no viene; nunca se informa un cero inventado.
Errores
Un error responde { "error": "<CÓDIGO>" } con el status HTTP que corresponde a ese código. Según el caso trae además:
missing: lo que falta para que la acción pueda correr;suggestions: qué acción lo resuelve, con la misma forma quenext.suggestions;retryAfterSeconds: en429, junto con el headerRetry-After;- en un
402, qué límite se agotó y cuándo vuelve (Créditos y uso).
Por ejemplo, close_job_post sobre una vacante con posiciones sin cubrir y sin motivo:
{
"error": "CLOSE_REASON_REQUIRED",
"missing": [
"closeReason"
]
}Cada página de acción lista sus errores propios. Estos aplican a todas:
| Código | HTTP | Cuándo |
|---|---|---|
UNAUTHENTICATED | 401 | La API key falta, es inválida o fue revocada. |
INVALID | 400 | El body no pasa el schema de la acción, o una regla de negocio lo rechaza. Trae details. |
INVALID_JSON | 400 | El body no es JSON válido. |
NOT_FOUND | 404 | La acción no existe, o un id del body no existe en el workspace. |
METHOD_NOT_ALLOWED | 405 | El nombre es una lectura: se lee con su GET. |
FORBIDDEN | 403 | La persona dueña de la key no puede hacer esa escritura. |
SEAT_REQUIRED | 403 | Una acción PROVIDER con una key de alguien sin asiento. |
WORKSPACE_SUSPENDED | 409 | El workspace está programado para eliminarse y rechaza todo. |
PAYLOAD_TOO_LARGE | 413 | El body pesa más de 1 MB. |
UNSUPPORTED_MEDIA_TYPE | 415 | El Content-Type no es JSON. |
IDEMPOTENCY_KEY_REUSED | 422 | Misma Idempotency-Key con otro body. |
IDEMPOTENCY_IN_FLIGHT | 409 | La primera llamada con esa Idempotency-Key todavía está corriendo. |
RATE_LIMITED | 429 | Más de 60 requests por minuto. Trae retryAfterSeconds y el header Retry-After. |
UNEXPECTED | 500 | Un error nuestro. Cita el header X-Request-Id al reportarlo. |
El catálogo completo, con el status de cada código, está en Errores. El límite de requests es compartido con el MCP: ver Límites de uso.
Índice de acciones
Las 97 acciones, agrupadas como en el menú. Cada nombre lleva a su documentación.
Vacantes
| Acción | Familia | Qué hace |
|---|---|---|
create_job_post | GENERATE | Crea una vacante como borrador. |
update_job_post | DO | Edita los campos y las condiciones de una vacante. |
duplicate_job_post | DO | Duplica una vacante como borrador nuevo. |
close_job_post | DO | Cierra una vacante. |
reopen_job_post | DO | Reabre una vacante cerrada. |
delete_draft_job_post | DO | Elimina un borrador que nadie trabajó. |
set_job_post_owner | DO | Cambia el owner de una vacante. |
add_job_post_member | DO | Suma a un miembro al equipo de la vacante. |
remove_job_post_member | DO | Saca a un miembro del equipo de la vacante. |
add_job_post_subscriber | DO | Suscribe a un miembro a las notificaciones. |
remove_job_post_subscriber | DO | Quita a un miembro de las notificaciones. |
set_pipeline_stages | DO | Define las etapas del pipeline. |
set_recommendation_threshold | DO | Fija el puntaje mínimo de recomendación. |
create_job_post_share | DO | Crea un link para el cliente. |
revoke_job_post_share | DO | Revoca un link para el cliente. |
create_note | DO | Agrega una nota a una vacante o a una persona. |
update_note | DO | Reescribe una nota propia. |
write_evaluation_criteria | GENERATE | La IA escribe los criterios de evaluación. |
write_screening_criteria | GENERATE | La IA escribe las preguntas de screening. |
Postulaciones
| Acción | Familia | Qué hace |
|---|---|---|
add_to_job_post | DO | Suma personas del pool al pipeline. |
move_application_stage | DO | Mueve a un candidato de etapa, o lo contrata. |
move_applications_stage | DO | Mueve a varios candidatos a la misma etapa. |
disqualify_application | DO | Corta a un candidato. |
restore_application | DO | Revierte un corte. |
withdraw_application | DO | Registra que el candidato se bajó. |
set_applications_status | DO | Cambia el estado de varios candidatos. |
add_application_label | DO | Pone una etiqueta a una postulación. |
remove_application_label | DO | Quita una etiqueta de una postulación. |
set_applications_labels | DO | Pone y quita etiquetas a varios candidatos. |
update_label | DO | Renombra o archiva una etiqueta. |
add_application_comment | DO | Agrega un comentario a una postulación. |
update_application_comment | DO | Corrige un comentario propio. |
reply_to_comment | DO | Responde a un comentario. |
activate_guarantee | DO | Activa la garantía de una contratación. |
review_screening_answer | DO | Resuelve una respuesta de screening. |
run_match_score | PROVIDER | Calcula el Match Score de candidatos. |
Entrevistas y evaluación
| Acción | Familia | Qué hace |
|---|---|---|
create_interview | DO | Agenda o registra una entrevista. |
update_interview | DO | Edita o cancela una entrevista. |
update_interview_question | DO | Edita o descarta una pregunta de entrevista. |
set_interview_transcript | DO | Carga la transcripción de una entrevista. |
generate_interview_questions | GENERATE | La IA propone preguntas de entrevista. |
generate_answers_from_transcript | GENERATE | La IA redacta las respuestas desde la transcripción. |
generate_scorecard | GENERATE | La IA propone el scorecard. |
draft_report | GENERATE | La IA propone textos del reporte. |
generate_report | DO | Construye una versión del reporte, sin IA. |
write_consideration | DO | Escribe una consideración para el cliente. |
Talent pool
| Acción | Familia | Qué hace |
|---|---|---|
create_profile | DO | Agrega una persona al pool a mano. |
update_profile | DO | Edita el perfil propio de una persona del pool. |
add_profile_contact | DO | Guarda un email o teléfono cargado a mano. |
update_profile_contact | DO | Corrige un email o teléfono cargado a mano. |
add_profile_tag | DO | Agrega un tag a personas del pool. |
remove_profile_tag | DO | Quita un tag a personas del pool. |
update_tag | DO | Renombra o archiva un tag. |
set_profile_do_not_contact | DO | Marca personas como «no contactar». |
save_to_pool | DO | Guarda en el pool personas de una búsqueda. |
remove_from_pool | DO | Saca personas del pool. |
resolve_merge_candidate | DO | Resuelve un posible duplicado. |
upload_attachment | DO | Adjunta un archivo a una persona. |
upload_cv | PROVIDER | Abre una carga de CVs al pool. |
Búsqueda de talento
| Acción | Familia | Qué hace |
|---|---|---|
search_talent | PROVIDER | Busca personas fuera del workspace. |
search_talent_preview | PROVIDER | Pide una página de personas sin enriquecerlas. |
load_more_talent | PROVIDER | Trae la página siguiente de una búsqueda. |
enrich_profile | PROVIDER | Trae el perfil completo de LinkedIn. |
enrich_contact | PROVIDER | Busca el email y el teléfono de personas del pool. |
Listas
| Acción | Familia | Qué hace |
|---|---|---|
create_bookmark | DO | Crea una lista. |
update_bookmark | DO | Renombra o describe una lista. |
delete_bookmark | DO | Borra una lista. |
set_bookmark_visibility | DO | Comparte una lista o la vuelve privada. |
add_to_bookmark | DO | Agrega personas a una lista. |
remove_from_bookmark | DO | Saca personas de una lista. |
add_longlist_to_bookmark | DO | Agrega una longlist entera a una lista. |
Sourcing
| Acción | Familia | Qué hace |
|---|---|---|
write_sourcing_criteria | GENERATE | La IA escribe los criterios de sourcing. |
write_talent_icp | GENERATE | La IA propone el perfil ideal. |
update_talent_icp | DO | Edita y aprueba un perfil ideal. |
create_sourcing_search | DO | Agrega una búsqueda al perfil ideal. |
close_talent_icp | DO | Cierra un perfil ideal. |
run_sourcing | PROVIDER | Empieza a armar la longlist. |
continue_sourcing | PROVIDER | Sigue una corrida de sourcing abierta. |
cancel_sourcing | DO | Detiene una corrida de sourcing. |
build_longlist | DO | Arma una longlist con lo ya calificado. |
CRM
| Acción | Familia | Qué hace |
|---|---|---|
create_lead | CRM | Crea un lead (empresa cliente). |
update_lead | CRM | Edita un lead. |
move_lead_stage | CRM | Mueve un lead de etapa en el CRM. |
set_lead_do_not_contact | CRM | Marca un lead como «no contactar». |
set_contact_do_not_contact | CRM | Marca un contacto como «no contactar». |
create_contact | CRM | Crea un contacto en un lead. |
update_contact | CRM | Edita un contacto. |
log_lead_activity | CRM | Registra una actividad en un lead. |
create_request | CRM | Crea un request (búsqueda pedida por un cliente). |
update_request | CRM | Edita un request. |
set_request_status | CRM | Cambia el estado de un request. |
link_request_to_job_post | CRM | Vincula un request con una vacante. |
archive_lead | CRM | Archiva o restaura un lead. |
archive_request | CRM | Archiva o restaura un request. |
archive_contact | CRM | Archiva o restaura un contacto. |
update_lead_activity | CRM | Corrige una actividad propia de un lead. |
add_contact_history | CRM | Agrega o corrige un trabajo del historial de un contacto. |