Inicio rápido
De cero a tu primera lectura y tu primera acción con la API de Reclee en cinco minutos.
Esta página te lleva de no tener nada a leer las vacantes de tu workspace y escribir algo en él. Necesitas una cuenta de Reclee con rol Owner o Recruiter (los roles con asiento) y una terminal.
Crea una API key
- En Reclee, abre Configuración → Developers.
- Haz clic en Crear una API key y dale un nombre que diga para qué es (por ejemplo, «Integración con el ATS»).
- Copia el secreto. Empieza con
rcl_y se muestra una sola vez: Reclee guarda solo una huella del secreto, así que no hay forma de volver a verlo. Si lo pierdes, revoca esa key y crea otra.
Guárdalo en una variable de entorno, nunca en el código:
export RECLEE_API_KEY="rcl_..."La key actúa como tú: tiene tu rol y solo ve el workspace en el que la creaste. Más detalles en Autenticación.
Comprueba que la key funciona
GET /account/me devuelve el perfil de la persona dueña de la key. Es la forma más simple de confirmar que la credencial resuelve.
curl https://app.reclee.com/api/v1/account/me \
-H "Authorization: Bearer $RECLEE_API_KEY"{
"userId": "4f6a2c1e-8b3d-4e7a-9c21-5d0b7e3f1a62",
"email": "laura.mendez@talentoandino.com",
"firstName": "Laura",
"lastName": "Méndez",
"locale": "es",
"theme": "system",
"isLastOwner": false,
"hasPassword": true,
"avatarPath": null,
"avatarUrl": null
}Si recibes 401 con { "error": "UNAUTHENTICATED" }, la key está mal copiada, fue revocada o tu rol ya no tiene asiento. Ver Autenticación.
Lista las vacantes activas
Las lecturas son GET sobre recursos. Las listas se paginan con page y pageSize y contestan { rows, total, page, pageSize }.
curl "https://app.reclee.com/api/v1/job-posts?status=ACTIVE&pageSize=5" \
-H "Authorization: Bearer $RECLEE_API_KEY"Respuesta (extracto: cada vacante trae más campos):
{
"rows": [
{
"id": "3f8a2b6c-1d4e-4a7b-9c2d-8e5f6a7b8c9d",
"requestId": null,
"title": "Senior Backend Engineer",
"status": "ACTIVE",
"seniority": "MID_SENIOR_LEVEL",
"employmentType": "FULL_TIME",
"workplaceType": "REMOTE",
"country": "AR",
"openings": 1,
"openedAt": "2026-10-06T13:12:44.512+00:00",
"createdAt": "2026-10-02T18:40:09.031+00:00",
"handle": "senior-backend-engineer"
}
],
"total": 7,
"page": 1,
"pageSize": 5
}Guarda el id de una vacante: lo usas en el paso siguiente.
Haz tu primera acción
Las escrituras van por POST /actions/<tool>. create_note deja una nota del equipo en una vacante (o en una persona del talent pool). Es una buena primera acción: no consume créditos ni uso de IA.
curl -X POST https://app.reclee.com/api/v1/actions/create_note \
-H "Authorization: Bearer $RECLEE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 0b6c3e1a-5d2f-4c8b-9a7e-1f2d3c4b5a69" \
-d '{
"jobPostId": "3f8a2b6c-1d4e-4a7b-9c2d-8e5f6a7b8c9d",
"body": "El cliente pidió priorizar inglés avanzado."
}'{
"data": { "noteId": "7c1e9a52-4b3d-4f8e-a6c1-2d9e8f7a6b5c" },
"links": [
{
"kind": "job_post",
"id": "3f8a2b6c-1d4e-4a7b-9c2d-8e5f6a7b8c9d",
"label": "Senior Backend Engineer",
"href": "https://app.reclee.com/job-posts/3f8a2b6c-1d4e-4a7b-9c2d-8e5f6a7b8c9d/overview"
}
]
}Toda acción contesta con la misma forma: data (lo que la acción produjo), links (dónde verlo en la app) y, en muchas escrituras, next (qué le falta todavía al objeto y qué acciones siguen). Las que gastan uso de IA o créditos agregan cost.
El header Idempotency-Key es opcional, pero conviene mandarlo siempre en las acciones: si la conexión se corta y reintentas con la misma key, Reclee devuelve la primera respuesta en vez de crear la nota dos veces. Ver Idempotencia.
Si algo sale mal
Todo error es JSON con un código estable en error:
{
"error": "INVALID",
"details": {
"errors": [],
"properties": {
"body": { "errors": ["Invalid input: expected string, received undefined"] }
}
}
}| Status | Qué revisar |
|---|---|
400 INVALID | El cuerpo o la query no pasan la validación: details dice qué campo. |
401 UNAUTHENTICATED | La key: mal copiada, revocada o sin asiento. |
404 NOT_FOUND | El id no existe o no es de tu workspace, o el nombre de la acción está mal escrito. |
405 METHOD_NOT_ALLOWED | Llamaste como acción algo que se lee con GET, o usaste un método que la ruta no acepta. |
429 RATE_LIMITED | Pasaste los 60 pedidos por minuto: espera lo que dice Retry-After. |
El catálogo completo está en Errores.