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
/copilot/chatManda 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:
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| threadId | uuid | Sí | El hilo. Si no existe y el trigger es submit-message, se crea. |
| trigger | enum | Sí | submit-message o regenerate-message. |
| message.id | uuid | Sí | 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.parts | object[] | Sí | Exactamente una parte: { type: "text", text } con hasta 8000 caracteres. |
| message.metadata.createdAt | string | Opcional | Fecha ISO 8601 con zona. Opcional; el servidor guarda su propia fecha. |
| context | object | Opcional | Sobre 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. |
| mode | enum | Opcional | Limita qué herramientas ofrece el turno: AUTO (todas, default), ASK, TALENT, JOB_POST, PIPELINE o CRM. |
| skipApproval | boolean | Opcional | true deja que las escrituras que lo permiten corran sin pedir confirmación. Default false. |
Body para approval-response:
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| threadId | uuid | Sí | El hilo donde el asistente pidió la confirmación. |
| trigger | "approval-response" | Sí | Literal. |
| approvals | object[] | Sí | De 1 a 20 decisiones. |
| approvals[].approvalId | string | Sí | El approvalId que llegó en el chunk tool-approval-request. |
| approvals[].approved | boolean | Sí | true ejecuta la escritura; false la rechaza. |
| approvals[].reason | string | Opcional | Motivo, hasta 500 caracteres (útil al rechazar). |
| context | object | Opcional | Igual que arriba. |
| mode | enum | Opcional | Igual que arriba. |
| skipApproval | boolean | Opcional | Igual 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:
type | Qué es |
|---|---|
text-start / text-delta / text-end | El texto de la respuesta; concatena los delta del mismo id. |
tool-input-available | El asistente llama a una herramienta (toolName) con ese input. Las herramientas son las mismas acciones y lecturas del MCP. |
tool-approval-request | El 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-error | El resultado de una herramienta, o su error. |
finish | Fin del mensaje. messageMetadata.createdAt es la hora que queda guardada. |
error | El 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ódigo | Status | Cuándo |
|---|---|---|
INVALID | 400 | El body no pasa el schema. |
NOT_FOUND | 404 | approval-response o regenerate-message sobre un hilo que no existe o no es tuyo, o un threadId que ya usa otra persona. |
TURN_IN_PROGRESS | 409 | El hilo está respondiendo otro turno. Reintenta cuando termine. |
STALE_THREAD | 409 | Tu 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_EXHAUSTED | 402 | El plan no tiene uso de IA disponible ahora; la respuesta trae missing y suggestions. |
RATE_LIMITED | 429 | Pasaste 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ódigo | Qué significa |
|---|---|
TURN_TIME_UP | El turno ya llevaba demasiado tiempo para empezar esa herramienta. Pídela en un mensaje nuevo. |
TURN_GENERATIONS_MAX | El turno ya inició todas las generaciones que admite. Pídela en un mensaje nuevo. |
TURN_STOPPED | Se 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
/copilot/threadsLista 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.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| cursor | string | Opcional | El 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
/copilot/threadsCrea 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.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| text | string | Sí | 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}
/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}
/copilot/threads/{threadId}Cambia el título, fija o desfija el hilo, o las dos cosas. Hace falta al menos un campo. Devuelve true.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| title | string | Opcional | Título nuevo, de 1 a 120 caracteres. |
| pinned | boolean | Opcional | true 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}
/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}
/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.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| kind | enum | Sí | job_post, profile, application, lead o bookmark (path). |
| id | uuid | Sí | 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}
/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.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| kind | enum | Sí | jobPost, lead, request o contact (path). |
| id | uuid | Sí | El id de la vacante, empresa, pedido o persona (path). |
kind | Campos |
|---|---|
jobPost | jobPostId, title, status, clientName, ownerName, stages (id, name, templateKey, qualified), totals (applications, qualified, disqualified, withdrawn) |
lead | leadId, name, stage (key, label), website, industry, country, defaultFeePct, doNotContact, contacts, activity, requests |
request | requestId, title, status, positionsCount, leadId, leadName, jobPost, jobPostHidden, placements |
contact | contactId, 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.