Fluyio Developers

Los listados usan cursores. El endpoint disponible actualmente es GET /v1/subscribers, con permiso subscribers:read o un permiso global de lectura.

Por qué usar un cursor

El cursor indica desde qué posición continuar en el orden solicitado. Evita depender de un desplazamiento numérico que cambie cuando se añaden registros. No equivale a una instantánea inmutable de toda la base.

Parámetros

Parámetro	Predeterminado	Descripción
`limit`	`25`	Tamaño de página entre 1 y 100.
`cursor`	Ninguno	Valor opaco `next_cursor` de la respuesta anterior.
`sort`	`-created_at`	`created_at` para los más antiguos o `-created_at` para los más recientes.
`filter[...]`	Ninguno	Filtros combinados con `AND`.

Respuesta

{
  "object": "list",
  "data": [
    { "id": "sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8", "object": "subscriber", "email": "[email protected]", "...": "..." },
    { "id": "sub_1a2b3c4d5e6f708192a3b4c5d6e7f809", "object": "subscriber", "email": "[email protected]", "...": "..." }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0wNS0xMVQxNDozMjowOC40MjFafDlmMWMyYjNhLTRkNWUtNmY3MC04MTkyLWEzYjRjNWQ2ZTdmOA"
}

Campo	Tipo	Descripción
`object`	`string`	Siempre `list`.
`data`	`array`	Resultados de la página en el orden solicitado.
`has_more`	`boolean`	Hay más resultados después de esta página.
`next_cursor`	`string` o `null`	Envíalo como `cursor`; vale `null` cuando no quedan páginas.

No construyas ni interpretes cursores. Su formato puede cambiar. Uno que no se puede decodificar devuelve 400 invalid_cursor.

Recorrer una colección

# Page 1
curl "https://fluyio.com/api/v1/subscribers?limit=100" \
  -H "Authorization: Bearer $FLUYIO_API_KEY" \
  -H "Fluyio-Version: 2026-05-15"

# Page 2 (next_cursor from page 1)
curl "https://fluyio.com/api/v1/subscribers?limit=100&cursor=MjAyNi0wNS0xMVQxNDozMjowOC40MjFafDlm..." \
  -H "Authorization: Bearer $FLUYIO_API_KEY" \
  -H "Fluyio-Version: 2026-05-15"

Orden

Se ordena por fecha de creación y se utiliza el ID para desempatar.

# Newest first (default)
GET /v1/subscribers?sort=-created_at

# Oldest first
GET /v1/subscribers?sort=created_at

Conserva sort y todos los filtros durante el recorrido. Si cambias los parámetros, empieza de nuevo desde la primera página.

Filtros

Se combinan con AND; no hay OR, operadores libres ni búsqueda por texto.

Filtro	Coincidencia
`filter[email]`	Email exacto, comparado en minúsculas.
`filter[external_id]`	ID externo exacto.
`filter[created_at_gte]`	Creación desde el instante ISO 8601 indicado.
`filter[created_at_lte]`	Creación hasta el instante ISO 8601 indicado.
`filter[has_consent]`	Alta vigente en `email`, `sms` o `whatsapp`.

# Everyone created in May 2026 who can receive email
curl -g "https://fluyio.com/api/v1/subscribers?filter[created_at_gte]=2026-05-01T00:00:00Z&filter[created_at_lte]=2026-05-31T23:59:59Z&filter[has_consent]=email" \
  -H "Authorization: Bearer $FLUYIO_API_KEY" \
  -H "Fluyio-Version: 2026-05-15"

Una fecha o canal no válidos devuelven 400 invalid_param; param identifica el filtro. En cURL, usa -g o --globoff para conservar los corchetes.

Buscar por el ID de tu sistema

No hay un parámetro de ruta por ID externo. Utiliza el filtro y limit=1:

curl -g "https://fluyio.com/api/v1/subscribers?filter[external_id]=user_12345&limit=1" \
  -H "Authorization: Bearer $FLUYIO_API_KEY" \
  -H "Fluyio-Version: 2026-05-15"

Un array data vacío indica que no hay coincidencias.

Totales y selección de campos

No hay endpoint de conteo ni parámetro fields=. Para contar, recorre la colección o consulta el panel.

Errores frecuentes

No cambies los filtros entre páginas, no interpretes el cursor y no solicites más de 100 registros por página. Consulta errores y límites de peticiones.

Paginación, filtros y orden