Reclee

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/v1

Todas 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ómoEjemplo
LeerGET sobre un recursoGET /job-posts/{jobPostId}
ListarGET sobre una colección, paginadaGET /crm/leads?page=2&pageSize=50
EscribirPOST /actions/<tool> con un cuerpo JSONPOST /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

TemaRegla cortaDetalle
FormatoJSON 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ímite60 pedidos por minuto por persona, compartido con el MCP.Límites de uso
ReintentosIdempotency-Key en las acciones y en los POST que crean o gastan.Idempotencia
BorradosLa API casi no borra: archiva, cierra o edita.Borrados
CostoAlgunas acciones consumen uso de IA o créditos; un 402 dice qué se agotó.Créditos y uso
EspecificaciónOpenAPI 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 OWNER en 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/v1 no 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.

En esta página