Aller au contenu principal

Exemples

Disponible avecProResearch

Quatre petits exemples qui utilisent de vraies routes. Ils utilisent curl et Node 18 ou plus récent, qui intègre fetch, sans aucun paquet. Chacun indique les portées dont la clé a besoin : créez donc une clé avec celles-là uniquement. Voir Authentification et clés d'API.

Définissez votre clé une fois dans le shell :

export READSIRA_KEY="pk_..."

Portées : read:collections, write:bookmarks.

Un marque-page a besoin d'un title et du collectionId de la collection dans laquelle il va. Listez d'abord vos collections et choisissez-en une :

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

La réponse contient vos collections dans data. Copiez l'id de l'une d'elles, puis enregistrez le lien :

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 réponse contient le nouveau marque-page dans data, avec son id. tags est facultatif, avec 20 étiquettes au maximum. Enregistrer un lien compte comme une requête dans votre limite quotidienne.

Lire les surlignages d'un élément enregistré​

Portée : read:library.

La recherche trouve l'élément et donne son documentId. Lire le document renvoie vos highlights, tags et notes à côté du texte.

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 demande un seul caractère de texte, car ici seuls les surlignages vous intéressent. Les surlignages sont fournis avec chaque réponse. Pour lire tout le texte, voir Pagination.

Poser une question avec citations​

Portée : ask:library. Cela utilise votre budget d'IA et compte dans les réponses dont vous disposez chaque mois.

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 réponse dans data contient answer, avec des repères comme [1], et citations. Le repère [n] renvoie à citations[n-1], qui contient le title, l'url et la quote sur laquelle il s'appuie. verified vaut true quand la citation a été retrouvée dans le passage cité.

Synchroniser votre bibliothèque vers un fichier​

Portée : read:bookmarks.

Ce script lit chaque marque-page, une page à la fois, et les écrit dans readsira-library.json. Il attend quand l'API demande de ralentir. Lancez-le avec 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`);

Chaque exécution lit toute la bibliothèque : lancez-la aussi souvent que nécessaire, pas plus. Pour une copie de tout, notes et surlignages compris, dans un seul fichier, utilisez l'exportation de Confidentialité et vos données.

Conseils​

  • Vérifiez une route dans la référence avant de bâtir dessus.
  • Gérez 429 comme dans le script de synchronisation, et arrêtez-vous sur les autres erreurs. Voir Limites de débit et erreurs.
  • Gardez les clés hors des scripts que vous partagez. Lisez-les depuis l'environnement.
Dernière mise à jour le