Saltar al contenido
Empieza gratis

Guías

Paginación y polling

En esta página

Paginar con cursor

GET /tasks devuelve las tareas por páginas. Cada respuesta trae nextCursor; pásalo en la siguiente petición para obtener la página que sigue:

bash
curl -s "https://system.secretar-ia.org/api/v1/tasks?limit=50" \
  -H "Authorization: Bearer $SECRETARIA_API_KEY"
# → { "data": [...], "nextCursor": "1765804800000:abc…" }

curl -s "https://system.secretar-ia.org/api/v1/tasks?limit=50&cursor=1765804800000:abc…" \
  -H "Authorization: Bearer $SECRETARIA_API_KEY"
  • limit va de 1 a 100; por defecto, 50.
  • nextCursor: null significa que no hay más páginas.
  • Trata el cursor como opaco: pásalo tal cual y no lo construyas tú.
  • El orden es estable, por fecha de creación ascendente, y el cursor sigue siendo válido aunque se creen o borren tareas entre una página y otra.

Puedes combinar la paginación con los filtros status y projectId.

En Node, el recorrido completo queda así:

JavaScript
const base = 'https://system.secretar-ia.org/api/v1';
const headers = { Authorization: `Bearer ${process.env.SECRETARIA_API_KEY}` };

const tareas = [];
let cursor = null;
do {
  const url = new URL(`${base}/tasks`);
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);

  const respuesta = await fetch(url, { headers });
  if (!respuesta.ok) throw new Error(`HTTP ${respuesta.status}`);
  const pagina = await respuesta.json();
  tareas.push(...pagina.data);
  cursor = pagina.nextCursor;
} while (cursor);

Qué tareas aparecen

El listado incluye tus tareas y las de los proyectos compartidos en los que eres miembro. Las operaciones por id (GET, PATCH y DELETE de /tasks/{id}) trabajan sobre esas mismas tareas.

GET /projects no pagina, porque la lista de proyectos de una persona es corta: su respuesta no lleva nextCursor.

Polling con updatedAfter

Para sincronizar una integración (Zapier, Make, un cron), pide solo lo que cambió desde tu última pasada con updatedAfter, un timestamp en milisegundos:

bash
curl -s "https://system.secretar-ia.org/api/v1/tasks?updatedAfter=1765804800000" \
  -H "Authorization: Bearer $SECRETARIA_API_KEY"

El filtro es estricto (updatedAt > updatedAfter). Guarda el updatedAt más alto que hayas visto y pásalo tal cual en la siguiente pasada: no le sumes ni le restes nada.

Python
import os
import requests

BASE = "https://system.secretar-ia.org/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SECRETARIA_API_KEY']}"}


def cambios_desde(ultimo_updated_at):
    cambios, cursor = [], None
    while True:
        params = {"updatedAfter": ultimo_updated_at, "limit": 100}
        if cursor:
            params["cursor"] = cursor
        respuesta = requests.get(f"{BASE}/tasks", headers=HEADERS, params=params, timeout=10)
        respuesta.raise_for_status()
        pagina = respuesta.json()
        cambios.extend(pagina["data"])
        cursor = pagina["nextCursor"]
        if not cursor:
            break
    nuevo = max((t["updatedAt"] for t in cambios), default=ultimo_updated_at)
    return cambios, nuevo

Nota

No hay webhooks por ahora: el polling con updatedAfter es la forma de enterarte de los cambios. Ajusta la frecuencia a los límites de uso.

Cuidado

Las tareas borradas desaparecen del listado: el polling no te avisa de los borrados. Si necesitas detectarlos, compara de vez en cuando el listado completo con lo que tienes guardado.

Documentación