Reclee

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

POST/actions/{tool}
  • {tool} es el nombre exacto de la acción, en snake_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 404 con { "error": "NOT_FOUND" }.
  • Un nombre que existe pero es una lectura (por ejemplo get_job_post o list_applications del MCP) responde 405 con { "error": "METHOD_NOT_ALLOWED", "allowed": [] } y un header Allow vacío: esa lectura se hace con su GET en 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 responde 409 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.

FamiliaQué haceCosto
DOEscribe en vacantes, pipeline, entrevistas, talent pool y listas.No consume créditos ni uso.
CRMEscribe en el CRM: leads, contactos, requests y su actividad.No consume créditos ni uso.
GENERATELa IA escribe una propuesta o un borrador que la persona revisa en la app.Uso de IA del plan.
PROVIDERLlama 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:

CampoQué es
dataLo que la acción escribió o calculó: ids nuevos, conteos, el estado resultante. Su forma es propia de cada acción.
linksCada 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.
nextQué 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.
costSolo 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.004 es el 0,4 %);
  • teamUsagePct: la fracción del uso compartido del equipo, de 0 a 1;
  • credits: los créditos que consumió;
  • billedLater: true cuando 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 que next.suggestions;
  • retryAfterSeconds: en 429, junto con el header Retry-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ódigoHTTPCuándo
UNAUTHENTICATED401La API key falta, es inválida o fue revocada.
INVALID400El body no pasa el schema de la acción, o una regla de negocio lo rechaza. Trae details.
INVALID_JSON400El body no es JSON válido.
NOT_FOUND404La acción no existe, o un id del body no existe en el workspace.
METHOD_NOT_ALLOWED405El nombre es una lectura: se lee con su GET.
FORBIDDEN403La persona dueña de la key no puede hacer esa escritura.
SEAT_REQUIRED403Una acción PROVIDER con una key de alguien sin asiento.
WORKSPACE_SUSPENDED409El workspace está programado para eliminarse y rechaza todo.
PAYLOAD_TOO_LARGE413El body pesa más de 1 MB.
UNSUPPORTED_MEDIA_TYPE415El Content-Type no es JSON.
IDEMPOTENCY_KEY_REUSED422Misma Idempotency-Key con otro body.
IDEMPOTENCY_IN_FLIGHT409La primera llamada con esa Idempotency-Key todavía está corriendo.
RATE_LIMITED429Más de 60 requests por minuto. Trae retryAfterSeconds y el header Retry-After.
UNEXPECTED500Un 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ónFamiliaQué hace
create_job_postGENERATECrea una vacante como borrador.
update_job_postDOEdita los campos y las condiciones de una vacante.
duplicate_job_postDODuplica una vacante como borrador nuevo.
close_job_postDOCierra una vacante.
reopen_job_postDOReabre una vacante cerrada.
delete_draft_job_postDOElimina un borrador que nadie trabajó.
set_job_post_ownerDOCambia el owner de una vacante.
add_job_post_memberDOSuma a un miembro al equipo de la vacante.
remove_job_post_memberDOSaca a un miembro del equipo de la vacante.
add_job_post_subscriberDOSuscribe a un miembro a las notificaciones.
remove_job_post_subscriberDOQuita a un miembro de las notificaciones.
set_pipeline_stagesDODefine las etapas del pipeline.
set_recommendation_thresholdDOFija el puntaje mínimo de recomendación.
create_job_post_shareDOCrea un link para el cliente.
revoke_job_post_shareDORevoca un link para el cliente.
create_noteDOAgrega una nota a una vacante o a una persona.
update_noteDOReescribe una nota propia.
write_evaluation_criteriaGENERATELa IA escribe los criterios de evaluación.
write_screening_criteriaGENERATELa IA escribe las preguntas de screening.

Postulaciones

AcciónFamiliaQué hace
add_to_job_postDOSuma personas del pool al pipeline.
move_application_stageDOMueve a un candidato de etapa, o lo contrata.
move_applications_stageDOMueve a varios candidatos a la misma etapa.
disqualify_applicationDOCorta a un candidato.
restore_applicationDORevierte un corte.
withdraw_applicationDORegistra que el candidato se bajó.
set_applications_statusDOCambia el estado de varios candidatos.
add_application_labelDOPone una etiqueta a una postulación.
remove_application_labelDOQuita una etiqueta de una postulación.
set_applications_labelsDOPone y quita etiquetas a varios candidatos.
update_labelDORenombra o archiva una etiqueta.
add_application_commentDOAgrega un comentario a una postulación.
update_application_commentDOCorrige un comentario propio.
reply_to_commentDOResponde a un comentario.
activate_guaranteeDOActiva la garantía de una contratación.
review_screening_answerDOResuelve una respuesta de screening.
run_match_scorePROVIDERCalcula el Match Score de candidatos.

Entrevistas y evaluación

AcciónFamiliaQué hace
create_interviewDOAgenda o registra una entrevista.
update_interviewDOEdita o cancela una entrevista.
update_interview_questionDOEdita o descarta una pregunta de entrevista.
set_interview_transcriptDOCarga la transcripción de una entrevista.
generate_interview_questionsGENERATELa IA propone preguntas de entrevista.
generate_answers_from_transcriptGENERATELa IA redacta las respuestas desde la transcripción.
generate_scorecardGENERATELa IA propone el scorecard.
draft_reportGENERATELa IA propone textos del reporte.
generate_reportDOConstruye una versión del reporte, sin IA.
write_considerationDOEscribe una consideración para el cliente.

Talent pool

AcciónFamiliaQué hace
create_profileDOAgrega una persona al pool a mano.
update_profileDOEdita el perfil propio de una persona del pool.
add_profile_contactDOGuarda un email o teléfono cargado a mano.
update_profile_contactDOCorrige un email o teléfono cargado a mano.
add_profile_tagDOAgrega un tag a personas del pool.
remove_profile_tagDOQuita un tag a personas del pool.
update_tagDORenombra o archiva un tag.
set_profile_do_not_contactDOMarca personas como «no contactar».
save_to_poolDOGuarda en el pool personas de una búsqueda.
remove_from_poolDOSaca personas del pool.
resolve_merge_candidateDOResuelve un posible duplicado.
upload_attachmentDOAdjunta un archivo a una persona.
upload_cvPROVIDERAbre una carga de CVs al pool.

Búsqueda de talento

AcciónFamiliaQué hace
search_talentPROVIDERBusca personas fuera del workspace.
search_talent_previewPROVIDERPide una página de personas sin enriquecerlas.
load_more_talentPROVIDERTrae la página siguiente de una búsqueda.
enrich_profilePROVIDERTrae el perfil completo de LinkedIn.
enrich_contactPROVIDERBusca el email y el teléfono de personas del pool.

Listas

AcciónFamiliaQué hace
create_bookmarkDOCrea una lista.
update_bookmarkDORenombra o describe una lista.
delete_bookmarkDOBorra una lista.
set_bookmark_visibilityDOComparte una lista o la vuelve privada.
add_to_bookmarkDOAgrega personas a una lista.
remove_from_bookmarkDOSaca personas de una lista.
add_longlist_to_bookmarkDOAgrega una longlist entera a una lista.

Sourcing

AcciónFamiliaQué hace
write_sourcing_criteriaGENERATELa IA escribe los criterios de sourcing.
write_talent_icpGENERATELa IA propone el perfil ideal.
update_talent_icpDOEdita y aprueba un perfil ideal.
create_sourcing_searchDOAgrega una búsqueda al perfil ideal.
close_talent_icpDOCierra un perfil ideal.
run_sourcingPROVIDEREmpieza a armar la longlist.
continue_sourcingPROVIDERSigue una corrida de sourcing abierta.
cancel_sourcingDODetiene una corrida de sourcing.
build_longlistDOArma una longlist con lo ya calificado.

CRM

AcciónFamiliaQué hace
create_leadCRMCrea un lead (empresa cliente).
update_leadCRMEdita un lead.
move_lead_stageCRMMueve un lead de etapa en el CRM.
set_lead_do_not_contactCRMMarca un lead como «no contactar».
set_contact_do_not_contactCRMMarca un contacto como «no contactar».
create_contactCRMCrea un contacto en un lead.
update_contactCRMEdita un contacto.
log_lead_activityCRMRegistra una actividad en un lead.
create_requestCRMCrea un request (búsqueda pedida por un cliente).
update_requestCRMEdita un request.
set_request_statusCRMCambia el estado de un request.
link_request_to_job_postCRMVincula un request con una vacante.
archive_leadCRMArchiva o restaura un lead.
archive_requestCRMArchiva o restaura un request.
archive_contactCRMArchiva o restaura un contacto.
update_lead_activityCRMCorrige una actividad propia de un lead.
add_contact_historyCRMAgrega o corrige un trabajo del historial de un contacto.

En esta página