Pedidos y respuestas
Headers, cuerpos JSON, formatos de ids y fechas, tamaños máximos, archivos y la forma de una respuesta exitosa.
Esta página reúne las reglas de forma que valen para todas las rutas de /api/v1: qué mandar, en qué formato, y qué esperar de vuelta.
Headers del pedido
| Header | Cuándo | Valor |
|---|---|---|
Authorization | Siempre (salvo GET /openapi.json) | Bearer rcl_… |
Content-Type | Cuando mandas un cuerpo | application/json (o multipart/form-data en las rutas de archivos) |
Idempotency-Key | Opcional, en las acciones y en los POST que crean o gastan. Solo REST: el servidor MCP no lo acepta. | De 1 a 255 caracteres ASCII visibles; un UUID es lo habitual. Ver Idempotencia. |
No hace falta mandar Accept: toda respuesta es JSON, salvo las exportaciones a CSV.
El cuerpo
- JSON, un objeto. Las rutas que leen un cuerpo aceptan
Content-Type: application/json, cualquier tipo+json,text/plaino ningúnContent-Type(como mandafetchun string). Un cuerpo que dice ser otra cosa, como un formulario, contesta415 UNSUPPORTED_MEDIA_TYPE. - JSON mal formado contesta
400 INVALID_JSON. - Validación contra el esquema. Cada cuerpo se valida contra su esquema: un campo obligatorio ausente, un tipo equivocado o un valor fuera de rango contesta
400 INVALIDcondetails, campo por campo. Ver Errores. No mandes campos que el esquema no lista: en las acciones (POST /actions/<tool>) un campo desconocido se rechaza con400 INVALIDydetailsnombra la clave sobrante. - Cuerpo opcional. En las acciones sin campos obligatorios puedes no mandar cuerpo: se lee como
{}. Si mandas uno, tiene que pasar la validación. nully ausente no son lo mismo. En una edición, un campo ausente no se toca y un campo ennullse vacía (cuando el esquema lo permite).
La query
Los filtros y la paginación van en la query. En las rutas que aceptan filtros, la query se valida de forma estricta: un parámetro que la ruta no conoce contesta 400 INVALID en vez de ignorarse, para que un filtro mal escrito no te devuelva la lista entera como si nada.
curl "https://app.reclee.com/api/v1/job-posts?estado=ACTIVE" -H "Authorization: Bearer $RECLEE_API_KEY"
# 400 { "error": "INVALID", "details": { "errors": ["Unrecognized key: \"estado\""] } }Los números de la query (page, pageSize, umbrales) se mandan como texto y se convierten.
Tamaño máximo
| Qué | Límite | Si se pasa |
|---|---|---|
| Cuerpo JSON de una ruta REST (incluidas las acciones) | 1 MB, salvo que la ruta diga otro | 413 PAYLOAD_TOO_LARGE |
| Cualquier pedido REST, incluido un archivo | 4,5 MB, el tope de la plataforma | 413 PAYLOAD_TOO_LARGE |
| Archivos de las rutas multipart | El de cada ruta (ver abajo) | 413 TOO_LARGE o 413 PAYLOAD_TOO_LARGE |
Un mensaje al servidor MCP (POST /api/mcp) | 4 MB | 413 con un error JSON-RPC (-32000) |
El tope de 1 MB se mira primero por el header Content-Length, antes de leer el cuerpo, y después sobre el cuerpo leído. Ningún campo de la API se acerca a ese límite. Los archivos grandes (CVs, adjuntos) no viajan por la API: se suben directo con una URL firmada (ver abajo).
Formatos
| Tipo de dato | Formato | Ejemplo |
|---|---|---|
| Ids | UUID en texto | "3f8a2b6c-1d4e-4a7b-9c2d-8e5f6a7b8c9d" |
| Fecha y hora | ISO 8601 con zona horaria, en UTC | "2026-10-06T13:12:44.512+00:00" |
| Fecha sola | YYYY-MM-DD | "2026-11-03" (targetStartDate, leftAt) |
| Enums | Texto en mayúsculas | "ACTIVE", "MID_SENIOR_LEVEL" |
| País | ISO 3166-1 alfa-2, en mayúsculas (los filtros de búsqueda de talento lo piden en minúsculas) | "AR" |
| Moneda | ISO 4217 | "USD" |
| Idioma | es o en | "es" |
| Montos | Número | 85000 |
Cuando mandas una fecha y hora, usa ISO 8601 con zona (2026-11-03T15:00:00-03:00 o …Z).
Los porcentajes no tienen una escala única: los de uso (aiUsagePct, usedPct, teamUsagePct) van de 0 a 1, y los de match score (scorePct, coveragePct) de 0 a 100. Cada campo lo dice en su descripción.
Respuestas exitosas
200con el dato en JSON, sin envoltorio: un recurso es el objeto, una lista paginada es{ rows, total, page, pageSize }, una acción es{ data, links, next?, cost? }.204sin cuerpo en algunosDELETEque desvinculan (sacar una etiqueta, un tag, un miembro del equipo de una vacante).- CSV en las exportaciones (
GET /sourcing/longlists/{longlistId}/export,GET /talent/pool/export), conContent-Type: text/csvyContent-Disposition: attachment.
// GET /job-posts/3f8a2b6c-1d4e-4a7b-9c2d-8e5f6a7b8c9d (extracto)
{
"id": "3f8a2b6c-1d4e-4a7b-9c2d-8e5f6a7b8c9d",
"title": "Senior Backend Engineer",
"status": "ACTIVE",
"workplaceType": "REMOTE",
"salaryMin": 4000,
"salaryMax": 5500,
"currencyCode": "USD",
"salaryPeriod": "MONTHLY",
"openings": 1,
"createdAt": "2026-10-02T18:40:09.031+00:00"
}Los errores, en cambio, siempre traen { "error": "CODE" }. Ver Errores.
Headers de la respuesta
| Header | Cuándo | Para qué |
|---|---|---|
X-Request-Id | Siempre | Identifica el pedido. Cítalo si reportas un problema. |
Idempotent-Replayed: true | Al reintentar con la misma Idempotency-Key | La respuesta es la guardada del primer pedido; no se volvió a ejecutar nada. |
Retry-After | En los 429 | Segundos a esperar antes de reintentar. |
Allow | En los 405 | Los métodos que la ruta sí acepta. |
Archivos y multipart
Casi nada de la API recibe archivos. Hay dos mecanismos:
Subida directa con URL firmada (CVs y adjuntos). Mandas solo la lista de archivos (nombre, tamaño, tipo y el SHA-256 de sus bytes) y recibes una URL de subida por archivo, válida dos horas, a la que haces PUT de los bytes con su tipo como Content-Type. Así funcionan las acciones upload_cv (hasta 100 CVs PDF o DOCX de hasta 4 MB) y upload_attachment (un adjunto PDF, DOCX, XLSX, PNG, JPEG o WebP de hasta 10 MB). Un archivo que el workspace ya tiene vuelve con alreadyHere: true y no se sube ni se cobra de nuevo. Ver Importar CVs.
multipart/form-data en tres rutas de planillas, con el archivo en el campo file:
| Ruta | Qué hace | Archivo |
|---|---|---|
POST /talent/pool/sheet/columns | Lee las columnas de una planilla para que digas qué es cada una. | Hasta 4 MB |
POST /talent/pool/sheet | Importa personas al pool desde una planilla. Además de file, lleva mappings (un string JSON con qué columna es qué campo) y, opcionales, blocks, dedupeOff (strings JSON) y linkPublicProfile ("true"). | Hasta 4 MB |
POST /crm/sheet | Lee una planilla CSV o XLSX del CRM como encabezados y filas, para después mandar las filas a crm/leads/import, crm/contacts/import o crm/requests/import. | Hasta 2 MB |
curl -X POST https://app.reclee.com/api/v1/talent/pool/sheet/columns \
-H "Authorization: Bearer $RECLEE_API_KEY" \
-F "file=@candidatos.xlsx"CORS
Las rutas de /api/v1 no mandan headers CORS: un navegador no puede llamarlas desde otro origen. Es a propósito, porque la API se autentica con una key que no debe vivir en el navegador. Llama a la API desde tu servidor.
El servidor MCP (/api/mcp) y los endpoints de su autorización sí responden CORS abierto (Access-Control-Allow-Origin: *), porque hay clientes MCP que corren en el navegador; ninguno usa cookies.