Especificación OpenAPI
Cómo descargar la especificación OpenAPI 3.1 de la API y usarla con Postman, Insomnia o un generador de clientes.
La API publica su propia especificación OpenAPI 3.1. Se arma en cada pedido a partir de las rutas y las acciones que están en producción, así que nunca queda desactualizada. Sirve para explorar la API en Postman o Insomnia, generar un cliente tipado o validar tus pedidos.
Descargarla
curl -o reclee-openapi.json https://app.reclee.com/api/v1/openapi.jsonEs pública: no pide API key, porque la forma de la API no es un secreto y un cliente la necesita antes de tener una key. No cuenta contra el límite de pedidos y se cachea unos minutos.
Qué trae
| Parte | Qué describe |
|---|---|
servers | La dirección base completa, https://app.reclee.com/api/v1. Las herramientas la toman de ahí, aunque importes el archivo descargado. |
components.securitySchemes.apiKey | Autenticación bearer: Authorization: Bearer rcl_…. Aplica a todas las operaciones. |
paths — rutas REST | Cada ruta de /api/v1 con sus métodos y sus parámetros de path. Los operationId tienen la forma get job-posts/[jobPostId]. |
paths — /actions/{tool} | Una operación POST por acción (tags: ["actions"]), con operationId igual al nombre de la tool, su descripción completa, su familia en x-family (DO, CRM, GENERATE, PROVIDER) y el JSON Schema de su cuerpo. |
components.parameters | page y pageSize (en las rutas paginadas) e idempotencyKey (en las operaciones que aceptan Idempotency-Key). |
components.schemas.Page | La forma de una página: rows, total, page, pageSize. |
components.schemas.Error | La forma de un error: error, details, missing, suggestions, retryAfterSeconds. |
x-error-status | El mapa de cada código de error a su status HTTP, con los 400 incluidos. Ver Errores. |
Los DELETE que la API no ejecuta figuran como lo que son: marcados deprecated, con su respuesta 405 y la acción que los reemplaza en la descripción (ver Borrados).
Lo que todavía no describe: el cuerpo y la respuesta de las rutas REST aparecen como un objeto genérico. Los cuerpos de las acciones sí están completos; para la forma exacta de una ruta REST, usa la referencia REST.
Postman
- Import → Link, y pega
https://app.reclee.com/api/v1/openapi.json(o importa el archivo descargado: trae la dirección base completa). - Postman arma una colección con una carpeta por área (
job-posts,crm,talent,actions…). - Comprueba que la variable
baseUrlde la colección quedó enhttps://app.reclee.com/api/v1. - En la pestaña Authorization de la colección elige Bearer Token y pon la key en una variable (por ejemplo
{{recleeApiKey}}), mejor en un entorno que no compartas. - En las acciones, la pestaña Body ya trae un ejemplo armado desde el esquema.
Insomnia
- Import → From URL con
https://app.reclee.com/api/v1/openapi.json(o desde el archivo). - En el entorno base, define una variable con la key. La dirección base (
https://app.reclee.com/api/v1) ya viene en el documento. - En la autenticación de la colección, elige Bearer Token con esa variable.
Generar un cliente
Cualquier generador compatible con OpenAPI 3.1 sirve. Algunos ejemplos:
# Tipos TypeScript
npx openapi-typescript https://app.reclee.com/api/v1/openapi.json -o reclee.d.ts
# Cliente en Python, TypeScript, Go, etc.
npx @openapitools/openapi-generator-cli generate \
-i https://app.reclee.com/api/v1/openapi.json \
-g python -o ./reclee-clientTen en cuenta al generar:
- El servidor es absoluto (
https://app.reclee.com/api/v1): el cliente generado ya apunta a la API, sin configurar nada. - Los
operationIdde las rutas REST tienen espacios y barras (get job-posts/[jobPostId]). Algunos generadores los convierten en nombres de método poco legibles; si el tuyo lo permite, genera por tags o renombra las operaciones que uses. - Lo mejor tipado son las acciones: sus cuerpos salen del mismo esquema con el que la API los valida, cerrado con
additionalProperties: false(un campo que no está en el esquema se rechaza). Las respuestas de las rutas REST quedan sin tipo; tipéalas con la referencia. - Los errores comparten un solo esquema (
Error) como respuestadefault; el status de cada código está enx-error-status.
Validar antes de llamar
El esquema de cada acción en paths["/actions/<tool>"].post.requestBody es el que la API aplica. Puedes validar tus cuerpos con él antes de mandarlos (con Ajv, por ejemplo) para atrapar un 400 INVALID en tu lado. Las mismas acciones, con los mismos esquemas, son las tools del servidor MCP.