Referencia API

API de Ágora CMS

Ágora CMS es un gestor de contenido headless que expone toda tu información editorial a través de una API REST estándar. Puedes integrarla en cualquier frontend — Next.js, Astro, Nuxt, una app móvil o un script Python — sin SDKs propietarios ni configuración especial. Cada workspace tiene su propia API Key y sus propios endpoints. Solo necesitas HTTP y JSON.

URL base

Todas las peticiones se hacen a:

https://app.agorastack.com/api/v1

La versión actual de la API es v1. Cuando haya cambios incompatibles se publicará una v2 manteniendo la anterior activa durante al menos 12 meses.

Autenticación

Todas las peticiones requieren el header X-API-Key con tu API Key de workspace.

X-API-Key: tu-api-key

Puedes obtener y gestionar tu API Key en Ajustes → API dentro del panel de administración.

A partir de la versión 1.0, el parámetro ?api_key= en la query string está desactivado en producción por razones de seguridad. Usa siempre el header X-API-Key.

Estructura de las respuestas

Todos los endpoints devuelven JSON con una estructura consistente.

Respuesta de colección:

{
  "data": [ ... ],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "pages": 5
  }
}

Respuesta de recurso único:

{
  "data": { ... }
}

Errores

Estructura de error:

{
  "error": true,
  "message": "Descripción del error",
  "code": 401
}

Códigos HTTP utilizados por la API:

Código	Significado
`200`	OK — La petición fue exitosa
`400`	Bad Request — Parámetros inválidos o faltantes
`401`	Unauthorized — API Key inválida o no proporcionada
`403`	Forbidden — No tienes permiso para este recurso
`404`	Not Found — El recurso no existe
`422`	Unprocessable Entity — Datos de entrada no válidos
`429`	Too Many Requests — Has superado el límite de peticiones
`500`	Internal Server Error — Error en el servidor

Parámetros comunes

La mayoría de endpoints de la API pública aceptan estos parámetros:

Parámetro	Tipo	Requerido	Descripción
`web_id`	string (UUID)	Sí	ID de la web de la que quieres obtener el contenido. Lo encuentras en Ajustes → Webs.
`lang`	string	No	Código ISO del idioma (`es`, `en`, `fr`…). Si se omite, devuelve el idioma por defecto.
`page`	integer	No	Número de página para paginación. Por defecto: `1`.
`limit`	integer	No	Resultados por página. Por defecto: `20`. Máximo: `100`.

Primeros pasos

Integrar Ágora CMS en tu proyecto es cuestión de minutos. Solo necesitas tu API Key y el web_id del sitio que quieres conectar. Sigue estos tres pasos:

Obtén tu API Key — entra en el panel de administración, ve a Ajustes → API y copia tu clave. Si aún no tienes una, pulsa "Generar nueva clave".
Haz tu primera petición — prueba el endpoint de posts con curl para verificar que la autenticación funciona: curl "https://app.agorastack.com/api/v1/posts?web_id=TU_WEB_ID" -H "X-API-Key: TU_API_KEY"
Integra en tu frontend — usa fetch, axios o cualquier cliente HTTP. Los ejemplos de esta documentación incluyen código listo para copiar.

Compatibilidad

La API de Ágora CMS es una API REST estándar que devuelve JSON. Es compatible con cualquier tecnología que pueda hacer peticiones HTTP: Next.js (App Router y Pages Router), Astro con fetch en tiempo de build o SSR, Nuxt, Vue standalone, React, Svelte, apps móviles con React Native o Flutter, scripts Python con requests, aplicaciones PHP, o cualquier automatización con cURL.

No hay SDK oficial que instalar ni dependencias adicionales. Si tu entorno puede hacer una petición GET con un header personalizado, puedes usar Ágora CMS.

Autenticación en detalle

Tu API Key es una cadena única por workspace. La encuentras en Ajustes → API del panel. Nunca la expongas en código cliente que se sirva en el navegador — úsala siempre en el servidor (getStaticProps, server components, endpoints de API, etc.).

Puedes rotar tu API Key desde el mismo panel en cualquier momento. Al rotar, la clave anterior queda inválida inmediatamente — asegúrate de actualizar todas las integraciones antes de hacerlo. Si crees que tu clave se ha comprometido, rótatela de inmediato: ve a Ajustes → API → Rotar clave.

En entornos de desarrollo puedes usar la misma clave que en producción o crear una web separada en el panel para tener datos de prueba aislados. No existe distinción de entornos a nivel de API — la separación la gestionas tú a través del web_id.

Rate limiting

La API aplica un límite de peticiones por API Key para garantizar la estabilidad del servicio. Cuando lo superas, el servidor responde con 429 Too Many Requests e incluye el header Retry-After indicando cuántos segundos debes esperar antes de reintentar.

Para gestionar el rate limiting correctamente, implementa un mecanismo de retry con backoff exponencial:

async function fetchWithRetry(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url, options)
    if (res.status !== 429) return res
    const retryAfter = res.headers.get('Retry-After') || 2
    await new Promise(r => setTimeout(r, retryAfter * 1000 * (i + 1)))
  }
  throw new Error('Demasiados reintentos')
}

En proyectos con build estático (Astro, Next.js con SSG) el límite raramente es un problema porque las peticiones ocurren en tiempo de compilación, no en cada visita de usuario. En proyectos SSR con mucho tráfico, cachea las respuestas en memoria o en Redis.

Paginación

Los endpoints que devuelven colecciones incluyen siempre el objeto meta con información de paginación:

"meta": {
  "total": 87,   // total de registros
  "page": 1,     // página actual
  "limit": 20,   // registros por página
  "pages": 5     // total de páginas
}

Para implementar paginación infinita o cargar todos los resultados en secuencia, usa meta.pages como condición de parada:

async function fetchAllPosts(webId, apiKey) {
  const base = 'https://app.agorastack.com/api/v1'
  const headers = { 'X-API-Key': apiKey }
  let page = 1
  let all = []

  while (true) {
    const res = await fetch(
      `${base}/posts?web_id=${webId}&page=${page}&limit=100`,
      { headers }
    )
    const { data, meta } = await res.json()
    all = [...all, ...data]
    if (page >= meta.pages) break
    page++
  }

  return all
}

Para paginación infinita en el frontend, guarda la página actual en estado y actualiza el array de resultados concatenando cada nueva carga. Usa meta.page < meta.pages para mostrar u ocultar el botón "Cargar más".

Siguiente Posts