Saltar al contenido principal

Ejemplos

Disponible enProResearch

Cuatro ejemplos pequeños que usan rutas reales. Usan curl y Node 18 o posterior, que trae fetch integrado, y ningún paquete. Cada uno dice qué permisos necesita la clave, así que crea una clave solo con esos. Consulta Autenticación y claves de API.

Define tu clave una vez en la terminal:

export READSIRA_KEY="pk_..."

Permisos: read:collections, write:bookmarks.

Un marcador necesita un title y el collectionId de la colección donde va. Primero enumera tus colecciones y elige una:

curl "https://api.readsira.com/api/v1/collections" \
  -H "Authorization: Bearer $READSIRA_KEY"

La respuesta tiene tus colecciones en data. Copia el id de una y después guarda el enlace:

curl -X POST "https://api.readsira.com/api/v1/bookmarks" \
  -H "Authorization: Bearer $READSIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/grid-lab",
    "title": "Grid Lab: long-duration storage",
    "collectionId": "PUT-A-COLLECTION-ID-HERE",
    "tags": ["energy"]
  }'

La respuesta tiene el marcador nuevo en data, con su id. tags es opcional, hasta 20 etiquetas. Guardar un enlace cuenta como una solicitud contra tu límite diario.

Leer los resaltados de un elemento guardado​

Permiso: read:library.

La búsqueda encuentra el elemento y da su documentId. Leer el documento devuelve tus highlights, tags y notes junto al texto.

const headers = { Authorization: `Bearer ${process.env.READSIRA_KEY}` };

const search = await fetch(
  'https://api.readsira.com/rest/v2/search?' + new URLSearchParams({ q: 'long-duration storage', limit: '1' }),
  { headers },
).then((r) => r.json());

const hit = search.data.results[0];
if (!hit) throw new Error('Nothing found');

const doc = await fetch(
  `https://api.readsira.com/rest/v2/documents/${hit.documentId}?maxChars=1`,
  { headers },
).then((r) => r.json());

console.log(doc.data.title);
for (const h of doc.data.highlights) console.log('-', h.text, h.note ? `(${h.note})` : '');

maxChars=1 pide un carácter de texto, porque aquí solo quieres los resaltados. Los resaltados vienen con cada respuesta. Para leer el texto completo, consulta Paginación.

Hacer una pregunta con citas​

Permiso: ask:library. Esto usa tu presupuesto de IA y cuenta para las respuestas que recibes cada mes.

curl -X POST "https://api.readsira.com/rest/v2/ask" \
  -H "Authorization: Bearer $READSIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "What did I save about iron-air batteries?" }'

La respuesta en data tiene answer, con marcadores como [1], y citations. El marcador [n] apunta a citations[n-1], que tiene el title, la url y la quote en la que se basa. verified es true cuando la cita se encontró en el pasaje citado.

Sincronizar tu biblioteca con un archivo​

Permiso: read:bookmarks.

Este script lee todos los marcadores, página a página, y los escribe en readsira-library.json. Espera cuando la API dice que vayas más despacio. Ejecútalo con node sync.mjs.

import { writeFile } from 'node:fs/promises';

const BASE = 'https://api.readsira.com';
const headers = { Authorization: `Bearer ${process.env.READSIRA_KEY}` };

async function get(path) {
  for (;;) {
    const res = await fetch(BASE + path, { headers });
    if (res.status === 429) {
      const wait = Number(res.headers.get('retry-after') ?? 60);
      console.log(`Rate limited, waiting ${wait} seconds`);
      await new Promise((resolve) => setTimeout(resolve, wait * 1000));
      continue;
    }
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    return (await res.json()).data;
  }
}

const bookmarks = [];
for (let page = 1; ; page++) {
  const data = await get(`/api/v1/bookmarks?page=${page}&limit=100`);
  bookmarks.push(...data.bookmarks);
  console.log(`Page ${page}: ${bookmarks.length} of ${data.total}`);
  if (!data.hasMore) break;
}

await writeFile('readsira-library.json', JSON.stringify(bookmarks, null, 2));
console.log(`Wrote ${bookmarks.length} bookmarks`);

Cada ejecución lee toda la biblioteca, así que ejecútalo tan a menudo como necesites y no más. Para una copia de todo, con notas y resaltados, en un solo archivo, usa la exportación de Privacidad y tus datos.

Consejos​

  • Comprueba una ruta en la referencia antes de construir sobre ella.
  • Gestiona 429 como en el script de sincronización y detente ante otros errores. Consulta Límites de uso y errores.
  • Mantén las claves fuera de los scripts que compartes. Léelas del entorno.
Última actualización en