Visión general
Cómo está diseñada la API REST de Reclee y las reglas que comparten todas sus rutas.
La API REST de Reclee expone todo lo que el equipo hace en la app sobre HTTP y JSON. Esta página resume el diseño y las reglas comunes; cada una tiene su página con el detalle.
Dirección base
https://app.reclee.com/api/v1Todas las rutas de esta documentación son relativas a esa dirección: GET /job-posts es GET https://app.reclee.com/api/v1/job-posts. Solo se habla HTTPS.
Lecturas y escrituras
La API separa leer de escribir:
| Qué | Cómo | Ejemplo |
|---|---|---|
| Leer | GET sobre un recurso | GET /job-posts/{jobPostId} |
| Listar | GET sobre una colección, paginada | GET /crm/leads?page=2&pageSize=50 |
| Escribir | POST /actions/<tool> con un cuerpo JSON | POST /actions/move_application_stage |
Las acciones son las operaciones de negocio con nombre: cada una tiene un nombre exacto en snake_case, un JSON Schema de entrada y una descripción de sus reglas. Son las mismas que publica el servidor MCP como tools: el mismo ejecutor, la misma validación, las mismas negativas. El catálogo está en Acciones.
Una acción devuelve siempre la misma forma:
{
"data": { "...": "lo que la acción produjo" },
"links": [{ "kind": "job_post", "id": "…", "label": "…", "href": "https://app.reclee.com/…" }],
"next": { "missing": ["…"], "suggestions": [{ "tool": "…" }] },
"cost": { "aiUsagePct": 0.004, "teamUsagePct": 0, "credits": 0, "billedLater": false }
}links: dónde ver en la app lo que se tocó, con URL absoluta.next(en las escrituras que lo calculan): qué le falta todavía al objeto y qué acciones siguen.cost(solo en las acciones que gastan): lo que gastó esta llamada. Ver Créditos y uso.
Algunas rutas REST también escriben con POST, PATCH, PUT o DELETE directo: editar tu perfil (PATCH /account/me), crear una vacante (POST /job-posts), revocar una key. La referencia REST dice qué métodos acepta cada ruta. Llamar con un método que la ruta no acepta contesta 405 METHOD_NOT_ALLOWED con la lista de los que sí (en el cuerpo, allowed, y en el header Allow).
Pedir como acción algo que es una lectura (por ejemplo POST /actions/get_job_post) contesta 405 METHOD_NOT_ALLOWED: se lee con su GET. Un nombre de acción que no existe contesta 404 NOT_FOUND.
Autenticación
Cada pedido lleva una API key en Authorization: Bearer rcl_…. La key actúa como la persona que la creó, con su rol, en un solo workspace. Ver Autenticación.
La única ruta pública es la especificación: GET /openapi.json no pide key.
Las reglas comunes
| Tema | Regla corta | Detalle |
|---|---|---|
| Formato | JSON de ida y de vuelta; la respuesta exitosa es el dato, sin envoltorio. | Pedidos y respuestas |
| Paginación | ?page desde 1 y ?pageSize hasta 200; contesta { rows, total, page, pageSize }. | Paginación |
| Errores | { "error": "CODE" } con un status fijo por código; INVALID trae details. | Errores |
| Límite | 60 pedidos por minuto por persona, compartido con el MCP. | Límites de uso |
| Reintentos | Idempotency-Key en las acciones y en los POST que crean o gastan. | Idempotencia |
| Borrados | La API casi no borra: archiva, cierra o edita. | Borrados |
| Costo | Algunas acciones consumen uso de IA o créditos; un 402 dice qué se agotó. | Créditos y uso |
| Especificación | OpenAPI 3.1 en GET /openapi.json. | OpenAPI |
Lo que la API no hace
- No borra salvo pocas excepciones: lo que se deja de usar se archiva o se cierra, para no perder historia. Ver Borrados.
- No mueve dinero. Comprar créditos, cambiar de plan o actualizar la tarjeta lo hace un
OWNERen persona, en la app. - No crea API keys. Se crean en la app; una key nunca crea otra.
- No tiene webhooks por ahora: para enterarte de un cambio, vuelve a leer el recurso.
- No es para el navegador. Las rutas de
/api/v1no mandan headers CORS: llámalas desde tu servidor, donde la key está a salvo.
Versionado
La versión va en la ruta (/api/v1). La API crece con rutas, acciones, campos y códigos de error nuevos: escribe tu cliente para que ignore los campos que no conoce y trate un código de error desconocido por su status HTTP. La especificación OpenAPI se arma en cada pedido a partir de la API en producción, así que siempre describe lo que está vivo.