Convenciones de URL y endpoints gratuitos

Si ves un 404 en una petición típica, lo más probable es que el prefijo sea incorrecto o que estés buscando Swagger UI en una ruta no estándar. Esta página recoge todas las URL canónicas y sus alias.

Prefijo de ruta

Todos los endpoints viven bajo /v1/. No hay otros prefijos.

✅ https://api.astroway.info/v1/chart
✅ https://api.astroway.info/v1/health
❌ https://api.astroway.info/api/chart        - 404 (missing /v1/ prefix)
❌ https://api.astroway.info/api/v1/chart     - 404 (our internal path, not exposed)
❌ https://api.astroway.info/v1/v1/chart      - 308 redirect to /v1/chart (typical SDK base-URL bug fix)

Si por error usas /api/<endpoint>, devolvemos 404 con el campo error.code = "WRONG_PREFIX" y una pista: tu SDK puede procesarlo y sugerir la ruta correcta.

No es un proxy de LLM

AstroWay es una API de cálculos astrológicos, no un proxy para LLM. Si vienes con la memoria muscular del SDK de OpenAI y pruebas a cambiar simplemente base_url por el nuestro, no funcionará:

❌ POST /v1/chat/completions            - doesn't exist
❌ POST /v1/completions                 - doesn't exist
❌ GET  /v1/models                      - doesn't exist (deliberately)
❌ POST /v1/embeddings                  - doesn't exist

No publicamos la lista de proveedores de IA por dos motivos:

No le sirve de nada al integrador. Llamas a /v1/interpret/natal o /v1/horoscope/daily y nuestro servidor elige por sí mismo el LLM entre varios proveedores con fallback automático. Cambiar de proveedor no cambia la forma de la respuesta, solo la latencia y alguna que otra reformulación.
Libertad operativa. La cadena cambia sin previo aviso (exclusión de HuggingFace el 2026-05-18, incorporación de NIM/ZAI). Si anunciáramos un models[] concreto, se convertiría de facto en un contrato.

La IA está presente solo como detalle de implementación en /v1/interpret/* (natal, sinastría, tránsitos), /v1/horoscope/* (horóscopo diario/semanal), /v1/dev-assistant (asistente de documentación) y /v1/reports/* (narrativas en PDF). Los otros 750+ endpoints son Swiss Ephemeris determinista, sin IA.

Especificación OpenAPI 3.1

La dirección canónica es /v1/openapi.json. Para facilitar las integraciones hay alias:

Alias	Destino	Por qué existe
`/v1/swagger.json`	301 → `/v1/openapi.json`	Convención de Swagger 2.0 / openapi-generator
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	Valor por defecto de springdoc
`/v1/v3/api-docs`	301 → `/v1/openapi.json`	Spring Boot 3
`/v1/v2/api-docs`	301 → `/v1/openapi.json`	Spring Boot 2
`/v1/swagger/v1/swagger.json`	301 → `/v1/openapi.json`	ASP.NET Core
`/v1/swagger`, `/v1/swagger-ui`, `/v1/swagger-ui.html`	302 → `/v1/docs`	Host de Swagger UI

Swagger UI interactivo está disponible en /v1/docs (también reflejado en la documentación del navegador en /docs/api/).

Endpoints de sistema gratuitos

Estas rutas no necesitan clave API ni descuentan créditos: se pueden llamar desde cualquier frontend, monitorización o health-check.

Ruta	Qué devuelve
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}` - liveness probe rápido
`GET /v1/health/deep`	Comprobación de accesibilidad de cada BD (para UptimeRobot / Pingdom), 503 si al menos una BD no está disponible
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}` - self-check detallado para SDK
`GET /v1/openapi.json`	Especificación OpenAPI 3.1 completa con ejemplos + `x-codeSamples`
`GET /v1/docs`	Swagger UI interactivo
`GET /v1/reference/*`	Referencias canónicas (signos, planetas, casas, aspectos) - límite por IP, sin clave
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	Lista de idiomas y diccionarios de UI - para widgets

Endpoints gratuitos que requieren registro

Los endpoints de cuenta están disponibles solo con un token JWT (se emite al iniciar sesión), pero no descuentan créditos del saldo del plan.

Prefijo	Qué es
`/v1/auth/*`	Registro, inicio de sesión, refresh, restablecimiento de contraseña
`/v1/me`, `/v1/me/*`	Perfil, estadísticas, llamadas recientes
`/v1/keys`, `/v1/keys/*`	Gestión de claves API
`/v1/admin/*`	Panel de administración (requiere `api_role = admin`)
`/v1/messages`	Comentarios desde el widget (anónimo, con límite de frecuencia)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	Asistente de IA para la documentación (anónimo, límite propio)
`/v1/widget-config`	Feature flags en tiempo de ejecución para el widget
`/v1/embed/*`	Widgets iframe incrustables (límite por IP)
`/v1/oauth/*`	Inicio de sesión con Google / GitHub
`/v1/books/*`	Birth Book - JWT con scope propio (lo emite un mu-plugin de WordPress)

Endpoints de cálculo de pago

Todos los cálculos astrológicos descuentan créditos de tu plan. El coste exacto de cada uno está en la página Coste de los endpoints. En resumen:

Tier	Créditos	Ejemplos
0	0	`/v1/reference/*` - referencias públicas, sin clave
½	5	`/v1/kabbalah/sephiroth`, `/v1/fixed-stars/catalog` - tablas estáticas
1	10	`/v1/planets`, `/v1/sun-times`, `/v1/moon-phase`
2	20	`/v1/chart`, `/v1/harmonics`, `/v1/horary`
3	50	`/v1/synastry`, `/v1/progressions`, `/v1/acg`
4	100	`/v1/transit-calendar`, `/v1/group-synastry`
5	250	`/v1/rectification/trutine`, narrativas de IA `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	Informes PDF: `/v1/reports/natal`, `/v1/reports/synastry`

Descuentos por caché: X-Cache: HIT (caché de idempotencia de 5 min) - 0 créditos. Endpoints de IA (/interpret/*) - 50% de descuento en cache hit.

Las cabeceras de respuesta contienen X-Credits-Used, X-Credits-Remaining, X-Credits-Limit: los SDK pueden seguir el saldo automáticamente.

Idioma de las respuestas

El idioma se indica con ?lang= o con la cabecera Accept-Language. Se admiten 21 idiomas.

Los campos de conjuntos cerrados (signos, planetas, días de la semana, fases de la Luna, vocabulario de Human Design, nombres de los Arcanos Mayores del Tarot) se devuelven dos veces: el identificador en inglés se queda en su sitio como contrato estable, y a su lado llega un objeto localized con la traducción:

{
  "phaseName": "Waxing Gibbous",
  "moonSign": "Capricorn",
  "localized": { "phaseName": "Zunehmender Mond", "moonSign": "Steinbock", "sunSign": "Löwe" }
}

Compara los valores en inglés y muestra localized. Estos nombres salen de una tabla explícita de términos en el código, no de una traducción automática: la terminología no se puede traducir palabra por palabra, o una fase de la Luna se convierte en un término financiero.

En Human Design, los centros de localized.centers tienen como claves los mismos identificadores que centers[].name, así que la correspondencia se hace por clave, no por la cadena traducida. En el Tarot, lo mismo lo hace localized.cards, con el slug de la carta como clave.

Los campos de conjuntos abiertos siguen en inglés por ahora y están documentados como tales: themes[] en el planeta del día, las palabras clave y significados de las cartas del Tarot, los nombres de canales y puertas de Human Design. Los nombres de los Arcanos Menores se componen a partir de formas congeladas de rango y palo, así que toda la baraja de 78 cartas está localizada y nameLocalized es true para ella; el campo solo queda en false donde la tabla no puede dar un nombre. Traduce los conjuntos abiertos en tu lado o espera a los diccionarios dedicados.

Respuesta compacta: `fields` y `precision`

Un agente paga por cada token que lee. POST /v1/chart devuelve unos 32 KB, cuando al modelo normalmente le bastan dos columnas, y cada longitud llega con catorce decimales donde nadie trabaja con más precisión que un minuto de arco.

Dos parámetros de consulta lo resuelven en el último paso, así que funcionan en todos los endpoints:

fields - lista de rutas separadas por comas, relativas a data. La ruta se aplica a cada elemento de un array, así que planets.name significa el nombre de cada planeta, no una clave del array.
precision - entero de 0 a 15, redondea todos los números no enteros de la respuesta. Los enteros no se tocan: un identificador no es una medida.

curl -X POST "https://api.astroway.info/v1/chart?fields=planets.name,planets.longitude&precision=2" \
  -H "X-Api-Key: aw_live_..." -H "Content-Type: application/json" \
  -d '{"date":"1990-05-15","time":"14:30:00","timezone":"Europe/Kyiv","latitude":50.45,"longitude":30.52}'

Esta pareja de parámetros en una carta natal da 511 bytes en lugar de 32 410, es decir, una respuesta sesenta veces más pequeña.

Una ruta que no encontró nada no desaparece en silencio. Llega en el campo _fields_unmatched junto a la respuesta: algunos campos son realmente opcionales y faltan en una respuesta concreta, así que no es un error. En cambio, una lista en la que no coincide ninguna ruta es una errata, y devuelve 400 FIELDS_UNKNOWN con la lista. Un objeto vacío en lugar de una carta sería una respuesta incorrecta dada con total seguridad.

Ambos parámetros van en la query y no en una cabecera, y es a propósito: la caché de respuestas usa como clave el método, la ruta, el cuerpo, la query ordenada y el plan. Un modo en una cabecera repetiría el incidente del 2026-08-22, cuando Accept-Language no formaba parte de la clave y una respuesta en alemán se sirvió al siguiente como ucraniana.

El recorte solo afecta a data. El envoltorio, _footer y _warning se quedan completos.

Lo mismo funciona por MCP. Cada herramienta en mcp.astroway.info acepta fields y precision junto a sus propios parámetros y se los pasa a la API con la misma query. Una carta natal por MCP pesaba 91 737 bytes, porque los datos llegaban dos veces: como bloque de texto con sangría y como campo estructurado. Con las mismas tres rutas y precision: 2 son 1 182 bytes.

Llamada de carta natal	Bytes
MCP, como era antes del 21.09.2026	91 737
MCP, sin sangría en el bloque de texto	72 484
MCP, `precision: 2`	61 356
MCP, tres rutas en `fields` más `precision: 2`	1 182
REST, tres rutas en `fields` más `precision=2`	559

Hora de nacimiento desconocida

Una parte importante de los usuarios finales no conoce su hora exacta de nacimiento. Si pones un mediodía convencional y calculas la carta como una normal, la respuesta tendrá un ascendente y unas cúspides de casas que parecen fiables, pero que se desvían aproximadamente un signo por cada dos horas de error.

Por eso, en lugar de time puedes enviar timeUnknown: true:

curl -X POST https://api.astroway.info/v1/chart \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-03-15","timeUnknown":true,"timezoneOffset":2,"latitude":50.45,"longitude":30.52}'

Qué devuelve la API en este modo:

Campo	Valor
`planets`	calculados para el mediodía local
`aspects`	calculados, pero los aspectos con la Luna no son fiables (ver abajo)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	bloque con explicación: qué se ha omitido exactamente y dónde puede estar la Luna

El bloque timeUnknown.moon contiene la longitud de la Luna al principio y al final del día, el arco recorrido en el día (11.8-15.4°), la lista de signos por los que pasó y el indicador changesSign. En un día la Luna puede cambiar de signo, así que conviene mostrar este rango al usuario en lugar de esconderlo tras un solo número.

El indicador lo aceptan /v1/chart y /v1/synastry (en la sinastría se puede activar para cada miembro de la pareja por separado). El resto de endpoints dependen de las casas o de los ángulos y responden 400 TIME_UNKNOWN_UNSUPPORTED: mejor un error explícito que un indicador ignorado en silencio y un ascendente inventado en la respuesta.

Versionado de la API

Versión major en la URL (/v1/). Los cambios incompatibles solo llegan con /v2/, no in-place. Detalles en Versionado.

GET /v1/version devuelve el despliegue actual:

curl https://api.astroway.info/v1/version
# {
#   "version": "2.71.0",
#   "build_commit": "abc1234",
#   "started_at": "2026-05-27T10:42:00Z",
#   "uptime_seconds": 12345,
#   "docs_url": "https://api.astroway.info/docs/api/"
# }

Los SDK pueden llamarlo al arrancar para depurar un “¿por qué de repente se comporta distinto?”: el campo build_commit identifica el despliegue con exactitud.

Las llamadas erróneas que más vemos

Del análisis de los logs de producción de 90 días, los 5 errores típicos de los integradores:

/api/<endpoint> en lugar de /v1/<endpoint>: costumbre de wp-json de WordPress. Ahora devolvemos un 404 JSON con una pista.
/v1/v1/<endpoint>: el SDK está configurado con baseUrl = .../v1 y añade /v1/X encima. Ahora es un redirect 308.
/swagger.json en lugar de /v1/openapi.json: auto-probe de Postman/Insomnia. Ahora es un redirect 301.
/v1/me, /v1/auth/keys/me sin Authorization: Bearer <jwt> → 401. Comprueba que el token se envía en la cabecera.
/v1/embed/natal con una clave API en lugar de un token de embed → 401. Los endpoints de embed aceptan un token de embed público del panel, no una clave API.