Reclee

Ask Reclee

El asistente de Reclee por API, con chat en streaming, hilos de conversación y el contexto de pantalla.

Ask Reclee es el asistente de Reclee: entiende lenguaje natural, lee los datos del workspace y puede ejecutar las mismas acciones que la API y el MCP, pidiendo confirmación antes de escribir. Estas rutas te dejan conversar con él desde tu propia aplicación: crear y listar hilos, mandar un mensaje y recibir la respuesta en streaming, y confirmar o rechazar las escrituras que propone.

Los hilos son personales: con una API key lees y escribes solo los hilos de la persona dueña de la key. Cada turno del chat consume uso de IA del plan del workspace (ver Créditos y uso) y cuenta para el rate limit.

Si solo quieres ejecutar acciones

Si tu integración ya sabe qué quiere hacer, no necesitas el chat: llama directo a POST /actions/<tool> o conecta el servidor MCP. El chat sirve cuando quieres que una persona converse con el asistente desde tu interfaz.

Chat

POST /copilot/chat

POST/copilot/chat

Manda un turno al asistente y devuelve su respuesta en streaming, como Server-Sent Events. Un mismo endpoint cubre tres casos, según trigger:

  • submit-message: un mensaje nuevo de la persona.
  • regenerate-message: volver a pedir la respuesta al último mensaje (reemplaza la respuesta anterior).
  • approval-response: las decisiones de la persona sobre las escrituras que el asistente pidió confirmar.

Solo viaja el último mensaje: el historial lo guarda el servidor. Si el threadId no existe todavía, el primer submit-message crea el hilo, así que una conversación nueva puede ser una sola llamada (genera tú el UUID del hilo).

Body para submit-message y regenerate-message:

CampoTipoRequeridoDescripción
threadIduuidSíEl hilo. Si no existe y el trigger es submit-message, se crea.
triggerenumSísubmit-message o regenerate-message.
message.iduuidSíId del mensaje, generado por ti. Un reintento manda el mismo id: así el servidor reemplaza la respuesta en vez de duplicarla.
message.role"user"SíSiempre user.
message.partsobject[]SíExactamente una parte: { type: "text", text } con hasta 8000 caracteres.
message.metadata.createdAtstringOpcionalFecha ISO 8601 con zona. Opcional; el servidor guarda su propia fecha.
contextobjectOpcionalSobre qué está la persona: { kind, id }, con kind job_post, profile, application, lead o bookmark. El asistente lo usa como referencia; si no se puede ver, se ignora.
modeenumOpcionalLimita qué herramientas ofrece el turno: AUTO (todas, default), ASK, TALENT, JOB_POST, PIPELINE o CRM.
skipApprovalbooleanOpcionaltrue deja que las escrituras que lo permiten corran sin pedir confirmación. Default false.

Body para approval-response:

CampoTipoRequeridoDescripción
threadIduuidSíEl hilo donde el asistente pidió la confirmación.
trigger"approval-response"SíLiteral.
approvalsobject[]SíDe 1 a 20 decisiones.
approvals[].approvalIdstringSíEl approvalId que llegó en el chunk tool-approval-request.
approvals[].approvedbooleanSítrue ejecuta la escritura; false la rechaza.
approvals[].reasonstringOpcionalMotivo, hasta 500 caracteres (útil al rechazar).
contextobjectOpcionalIgual que arriba.
modeenumOpcionalIgual que arriba.
skipApprovalbooleanOpcionalIgual que arriba.

Lo que se ejecuta al aprobar es exactamente lo que el asistente propuso y el servidor guardó: el cliente solo manda la decisión.

curl -N -X POST https://app.reclee.com/api/v1/copilot/chat \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "4c8a2e1f-6b3d-4f7a-9e5c-1d2b3a4c5e6f",
    "trigger": "submit-message",
    "message": {
      "id": "9e1f2a3b-4c5d-4e6f-8a7b-0c1d2e3f4a5b",
      "role": "user",
      "parts": [{ "type": "text", "text": "¿Cuántos candidatos calificados tiene la vacante de Backend Developer?" }]
    }
  }'

Formato del stream

La respuesta es 200 con Content-Type: text/event-stream y el header x-vercel-ai-ui-message-stream: v1: es el protocolo de UI message stream del AI SDK, así que useChat (o cualquier cliente de ese protocolo) lo lee directo. Cada evento es una línea data: con un objeto JSON, y el stream termina con data: [DONE].

data: {"type":"start","messageId":"7b2c…"}
data: {"type":"start-step"}
data: {"type":"tool-input-available","toolCallId":"call_1","toolName":"get_job_post_metrics","input":{"jobPostId":"c2e4…"}}
data: {"type":"tool-output-available","toolCallId":"call_1","output":{…}}
data: {"type":"finish-step"}
data: {"type":"start-step"}
data: {"type":"text-start","id":"t1"}
data: {"type":"text-delta","id":"t1","delta":"La vacante tiene "}
data: {"type":"text-delta","id":"t1","delta":"12 candidatos calificados."}
data: {"type":"text-end","id":"t1"}
data: {"type":"finish-step"}
data: {"type":"finish","finishReason":"stop","messageMetadata":{"createdAt":"2026-10-22T14:03:11.000Z"}}
data: [DONE]

(Extracto ilustrativo: los nombres de herramienta y su input/output dependen de lo que el asistente decida hacer.)

Los chunks que más vas a usar:

typeQué es
text-start / text-delta / text-endEl texto de la respuesta; concatena los delta del mismo id.
tool-input-availableEl asistente llama a una herramienta (toolName) con ese input. Las herramientas son las mismas acciones y lecturas del MCP.
tool-approval-requestEl asistente quiere ejecutar una escritura y espera confirmación. Guarda el approvalId: el turno termina acá y continúa con trigger: "approval-response".
tool-output-available / tool-output-errorEl resultado de una herramienta, o su error.
finishFin del mensaje. messageMetadata.createdAt es la hora que queda guardada.
errorEl turno falló a mitad de camino; errorText es TURN_FAILED.

El asistente también puede llamar a la herramienta ask_options para ofrecer opciones de respuesta (input.groups: hasta 3 grupos, cada uno con un label y de 2 a 4 options). No se ejecuta en el servidor: la persona contesta con un mensaje nuevo (submit-message) con la opción que elige, o con cualquier otro texto.

Errores

Un turno que no puede empezar contesta con un error JSON normal, antes de abrir el stream:

CódigoStatusCuándo
INVALID400El body no pasa el schema.
NOT_FOUND404approval-response o regenerate-message sobre un hilo que no existe o no es tuyo, o un threadId que ya usa otra persona.
TURN_IN_PROGRESS409El hilo está respondiendo otro turno. Reintenta cuando termine.
STALE_THREAD409Tu copia del hilo está atrasada (por ejemplo, reintentas un mensaje que ya tiene respuestas después). Vuelve a leer el hilo con GET /copilot/threads/{threadId}.
USAGE_WINDOW, USAGE_EXHAUSTED, TEAM_WINDOW, TEAM_USAGE_EXHAUSTED402El plan no tiene uso de IA disponible ahora; la respuesta trae missing y suggestions.
RATE_LIMITED429Pasaste el rate limit; trae retryAfterSeconds.

Duración y límites del turno

Un turno puede encadenar varias herramientas y generaciones, así que el stream puede quedar abierto varios minutos: la ruta admite hasta 800 segundos. Configura el timeout de tu cliente HTTP por encima de eso.

  • El turno se corta solo antes de ese tope y se guarda con lo que llegó a hacer: lo que ya se escribió o se generó queda hecho. Una respuesta cortada que solo había leído datos no se guarda: vuelve a pedirla con regenerate-message.
  • Pasado cierto punto del turno no arranca trabajo que gasta (una generación, una búsqueda o un enriquecimiento), para que lo que empiece alcance a terminar y quedar guardado.
  • Un turno inicia como máximo 4 generaciones. Las que sobran no se ejecutan; se piden en un mensaje nuevo.
  • Si cortas el turno (cerrando la conexión), no arranca ninguna herramienta más y una generación en curso se detiene; una escritura ya confirmada siempre termina.

Una herramienta que no arrancó por alguno de estos motivos llega como tool-output-available con un código en output.error, y el asistente lo explica en su texto:

CódigoQué significa
TURN_TIME_UPEl turno ya llevaba demasiado tiempo para empezar esa herramienta. Pídela en un mensaje nuevo.
TURN_GENERATIONS_MAXEl turno ya inició todas las generaciones que admite. Pídela en un mensaje nuevo.
TURN_STOPPEDSe cortó el turno antes de que la herramienta empezara.

En el mapa x-error-status de la especificación OpenAPI los tres figuran como 409, pero no llegan como respuesta HTTP: viajan dentro del stream.

Hilos

GET /copilot/threads

GET/copilot/threads

Lista los hilos de la persona, del más reciente al más viejo. No usa la paginación estándar: pagina por cursor. La primera página trae todos los hilos fijados más los 50 sin fijar más recientes; nextCursor trae la página siguiente, o es null si no hay más.

CampoTipoRequeridoDescripción
cursorstringOpcionalEl nextCursor de la página anterior. Sin cursor, la primera página.

Un cursor que no es válido contesta 400 INVALID.

curl https://app.reclee.com/api/v1/copilot/threads \
  -H "Authorization: Bearer rcl_..."

Respuesta:

{
  "threads": [
    {
      "id": "4c8a2e1f-6b3d-4f7a-9e5c-1d2b3a4c5e6f",
      "title": "Candidatos calificados de Backend Developer",
      "pinnedAt": null,
      "lastMessageAt": "2026-10-22T14:03:11.000Z",
      "createdAt": "2026-10-22T14:02:58.000Z"
    }
  ],
  "nextCursor": null
}

POST /copilot/threads

POST/copilot/threads

Crea un hilo con su primer mensaje y devuelve los dos ids. No genera la respuesta: para eso llama a POST /copilot/chat con trigger: "submit-message", el mismo threadId y message.id igual al messageId que te devolvió. Acepta Idempotency-Key (ver Idempotencia).

Es opcional: POST /copilot/chat con un threadId nuevo también crea el hilo.

CampoTipoRequeridoDescripción
textstringSíEl primer mensaje, hasta 8000 caracteres. El título del hilo sale de acá.
curl -X POST https://app.reclee.com/api/v1/copilot/threads \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f8e1c4a-thread-01" \
  -d '{ "text": "Hazme un resumen de las empresas en etapa MEETING" }'

Respuesta:

{
  "threadId": "4c8a2e1f-6b3d-4f7a-9e5c-1d2b3a4c5e6f",
  "messageId": "9e1f2a3b-4c5d-4e6f-8a7b-0c1d2e3f4a5b"
}

GET /copilot/threads/{threadId}

GET/copilot/threads/{threadId}

Devuelve un hilo con sus últimos 500 mensajes, en orden. hasOlder: true avisa que hay mensajes más viejos que no vinieron. Un hilo que no es tuyo contesta 404 NOT_FOUND, igual que uno que no existe.

Los mensajes tienen la forma UIMessage del AI SDK: id, role (user o assistant), parts (texto, llamadas a herramientas con su estado y resultado, pasos) y metadata. En los mensajes de la persona, metadata también trae el context, el mode y el skipApproval con que se mandaron. Una llamada a herramienta guardada conserva su input, su estado y la confirmación, pero no las filas que leyó: una pregunta nueva las vuelve a leer al día de hoy.

curl https://app.reclee.com/api/v1/copilot/threads/4c8a2e1f-6b3d-4f7a-9e5c-1d2b3a4c5e6f \
  -H "Authorization: Bearer rcl_..."

Respuesta (extracto):

{
  "id": "4c8a2e1f-6b3d-4f7a-9e5c-1d2b3a4c5e6f",
  "title": "Candidatos calificados de Backend Developer",
  "pinnedAt": null,
  "lastMessageAt": "2026-10-22T14:03:11.000Z",
  "createdAt": "2026-10-22T14:02:58.000Z",
  "hasOlder": false,
  "messages": [
    {
      "id": "9e1f2a3b-4c5d-4e6f-8a7b-0c1d2e3f4a5b",
      "role": "user",
      "parts": [{ "type": "text", "text": "¿Cuántos candidatos calificados tiene la vacante de Backend Developer?" }],
      "metadata": { "createdAt": "2026-10-22T14:02:58.000Z" }
    },
    {
      "id": "7b2c9d1e-3f4a-4b5c-8d6e-9f0a1b2c3d4e",
      "role": "assistant",
      "parts": [
        { "type": "step-start" },
        { "type": "text", "text": "La vacante tiene 12 candidatos calificados." }
      ],
      "metadata": { "createdAt": "2026-10-22T14:03:11.000Z" }
    }
  ]
}

PATCH /copilot/threads/{threadId}

PATCH/copilot/threads/{threadId}

Cambia el título, fija o desfija el hilo, o las dos cosas. Hace falta al menos un campo. Devuelve true.

CampoTipoRequeridoDescripción
titlestringOpcionalTítulo nuevo, de 1 a 120 caracteres.
pinnedbooleanOpcionaltrue lo fija arriba de la lista; false lo desfija.
curl -X PATCH https://app.reclee.com/api/v1/copilot/threads/4c8a2e1f-6b3d-4f7a-9e5c-1d2b3a4c5e6f \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -d '{ "pinned": true }'

Un hilo que no es tuyo contesta 404 NOT_FOUND.

DELETE /copilot/threads/{threadId}

DELETE/copilot/threads/{threadId}

Borra el hilo y todos sus mensajes, de forma permanente. Es una de las pocas cosas que una API key sí puede borrar, porque el hilo es de la persona. Devuelve true; un hilo que no es tuyo contesta 404 NOT_FOUND.

curl -X DELETE https://app.reclee.com/api/v1/copilot/threads/4c8a2e1f-6b3d-4f7a-9e5c-1d2b3a4c5e6f \
  -H "Authorization: Bearer rcl_..."

Contexto

GET /copilot/context/{kind}/{id}

GET/copilot/context/{kind}/{id}

Le pone nombre a una referencia de contexto: devuelve el { kind, id } que pasaste con el label que la persona reconoce (el título de la vacante, el nombre de la persona o de la empresa). Sirve para mostrar sobre qué está conversando el chat antes de mandar el context en POST /copilot/chat. Algo que quien llama no puede ver contesta 404 NOT_FOUND.

CampoTipoRequeridoDescripción
kindenumSíjob_post, profile, application, lead o bookmark (path).
iduuidSíEl id de ese objeto (path).
curl https://app.reclee.com/api/v1/copilot/context/job_post/c2e4f6a8-1b3d-4f5a-9c7e-2d4f6a8b0c1e \
  -H "Authorization: Bearer rcl_..."

Respuesta:

{
  "kind": "job_post",
  "id": "c2e4f6a8-1b3d-4f5a-9c7e-2d4f6a8b0c1e",
  "label": "Backend Developer Sr."
}

GET /copilot/panel/{kind}/{id}

GET/copilot/panel/{kind}/{id}

Devuelve un resumen compacto de una vacante, una empresa, un pedido o una persona del CRM, en una sola lectura: es lo que el asistente muestra en su panel lateral cuando abre una de esas pantallas. La forma de la respuesta depende de kind, que también viene en el body.

CampoTipoRequeridoDescripción
kindenumSíjobPost, lead, request o contact (path).
iduuidSíEl id de la vacante, empresa, pedido o persona (path).
kindCampos
jobPostjobPostId, title, status, clientName, ownerName, stages (id, name, templateKey, qualified), totals (applications, qualified, disqualified, withdrawn)
leadleadId, name, stage (key, label), website, industry, country, defaultFeePct, doNotContact, contacts, activity, requests
requestrequestId, title, status, positionsCount, leadId, leadName, jobPost, jobPostHidden, placements
contactcontactId, name, title, email, phone, linkedinUrl, leadId, leadName, doNotContact, doNotContactNote
curl https://app.reclee.com/api/v1/copilot/panel/contact/5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e \
  -H "Authorization: Bearer rcl_..."

Respuesta:

{
  "kind": "contact",
  "contactId": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
  "name": "Lucía Ferreyra",
  "title": "Head of People",
  "email": "lucia.ferreyra@acmelogistica.example",
  "phone": null,
  "linkedinUrl": null,
  "leadId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c12",
  "leadName": "Acme Logística",
  "doNotContact": false,
  "doNotContactNote": null
}

Para leer cada objeto completo, usa su referencia: vacantes y CRM.

En esta página