End-to-End Workflows¶

const BASE = "http://localhost:8000/api";

const notebookId = crypto.randomUUID();
const resp = await fetch(`${BASE}/notebooks/`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    notebook_id: notebookId,
    notebook_title: "Customer Support KB",
    embedding_model: "openai/text-embedding-3-small",
    user_id: "dev-user",
  }),
});
const { data: notebook } = await resp.json();
console.log(`Created notebook: ${notebook.notebook_id}`);

const formData = new FormData();
formData.append("files", fileBlob, "handbook.pdf");

const uploadResp = await fetch(
  `${BASE}/notebooks/${notebookId}/documents/upload`,
  { method: "POST", body: formData }
);
const { data: [uploaded] } = await uploadResp.json();
const { file_id: fileId, file_name: fileName, storage_path: filePath } = uploaded;
console.log(`Uploaded: ${fileName} (${fileId})`);

const ingestResp = await fetch(
  `${BASE}/notebooks/${notebookId}/documents/ingest`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      files: [{ file_id: fileId, file_name: fileName, file_path: filePath }],
      settings: {
        parser: "Docling Parser",
        chunking_strategy: "Recursive Chunking",
        chunk_size: 1000,
        chunk_overlap: 200,
      },
      notebook_name: "Customer Support KB",
    }),
  }
);
const { data: { jobs } } = await ingestResp.json();
console.log(`Started ${jobs.length} ingestion jobs`);

let status;
do {
  const stageResp = await fetch(
    `${BASE}/notebooks/${notebookId}/documents/${fileId}/stage`
  );
  status = (await stageResp.json()).data.status;
  console.log(`Status: ${status}`);
  if (status !== "success" && status !== "error") {
    await new Promise((r) => setTimeout(r, 3000));
  }
} while (status !== "success" && status !== "error");

const convResp = await fetch(
  `${BASE}/notebooks/${notebookId}/conversations`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ title: "Support Questions", chat_mode: "rag" }),
  }
);
const conversationId = (await convResp.json()).data.conversation_id;
console.log(`Conversation: ${conversationId}`);

const msgResp = await fetch(
  `${BASE}/notebooks/${notebookId}/conversations/${conversationId}/messages`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      content: "What is the refund policy?",
      strategy_id: "fusion",
      persona: "professional",
      language: "en",
    }),
  }
);
const { data: { assistant_message: assistant } } = await msgResp.json();
const messageId = assistant.id;

console.log(`Answer: ${assistant.content.slice(0, 200)}...`);
console.log(`Strategy: ${assistant.run_metadata.strategy_id}`);
console.log(`Cached: ${assistant.run_metadata.is_cached}`);
for (const cite of assistant.citations) {
  console.log(`  [${cite.citation_id}] ${cite.metadata?.file_name}`);
}

const fbResp = await fetch(
  `${BASE}/notebooks/${notebookId}/messages/${messageId}/feedback`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      is_positive: true,
      feedback_text: "Accurate answer with correct citations",
    }),
  }
);
console.log("Feedback submitted:", (await fbResp.json()).data);

const filesResp = await fetch(
  `${BASE}/notebooks/${notebookId}/enhance/files`
);
const { data: enhanceFiles } = await filesResp.json();
for (const f of enhanceFiles) {
  console.log(`${f.file_name}: ${f.total_chunks} chunks ` +
    `(pending=${f.pending}, success=${f.success}, embedded=${f.embedded})`);
}
const targetFileId = enhanceFiles[0].file_id;
const targetFileName = enhanceFiles[0].file_name;

const enhanceResp = await fetch(`${BASE}/notebooks/${notebookId}/enhance`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ file_ids: [targetFileId] }),
});
console.log("Enhancement started:", (await enhanceResp.json()).data);

let enhanceDone = false;
while (!enhanceDone) {
  const statusResp = await fetch(
    `${BASE}/notebooks/${notebookId}/enhance/status?file_id=${targetFileId}`
  );
  const enhStatus = (await statusResp.json()).data;
  console.log(`Progress: ${enhStatus.progress_pct.toFixed(1)}% ` +
    `(success=${enhStatus.success}, failed=${enhStatus.failed})`);
  enhanceDone = enhStatus.all_terminated;
  if (!enhanceDone) await new Promise((r) => setTimeout(r, 4000));
}
console.log("Enhancement complete!");

const publishResp = await fetch(
  `${BASE}/notebooks/${notebookId}/enhance/publish`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      file_id: targetFileId,
      file_name: targetFileName,
      notebook_title: "Customer Support KB",
    }),
  }
);
const publishResult = (await publishResp.json()).data;
console.log(`Published ${publishResult.published_count} enhanced chunks`);

const searchResp = await fetch(
  `${BASE}/notebooks/${notebookId}/retrieval/retrieve`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      query: "What is the refund policy?",
      strategy_id: "fusion",
      top_k: 5,
    }),
  }
);
const searchResult = (await searchResp.json()).data;
console.log(`Found ${searchResult.total_results} chunks in ${searchResult.execution_time_ms}ms`);
for (const chunk of searchResult.chunks) {
  console.log(`  [${chunk.rank}] score=${chunk.score.toFixed(3)}: ${chunk.content.slice(0, 80)}...`);
}

const inviteResp = await fetch(
  `${BASE}/notebooks/${notebookId}/invites`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ expires_at: "2026-04-01T00:00:00Z" }),
  }
);
const invite = (await inviteResp.json()).data;
console.log(`Share this link: ${invite.invite_url}`);

const previewResp = await fetch(`${BASE}/invite/${invite.invite_code}`);
const inviteInfo = (await previewResp.json()).data;
if (inviteInfo.is_valid) {
  console.log(`Invite for notebook: ${inviteInfo.notebook_title}`);
} else {
  console.log(`Invalid invite: ${inviteInfo.reason}`);
}

const redeemResp = await fetch(
  `${BASE}/invite/${invite.invite_code}/redeem`,
  { method: "POST" }
);
const access = (await redeemResp.json()).data;
console.log(`Gained ${access.access_level} access to: ${access.notebook_title}`);

// Create conversation as invited user
const newConvResp = await fetch(
  `${BASE}/notebooks/${notebookId}/conversations`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ title: "My Questions" }),
  }
);
const newConvId = (await newConvResp.json()).data.conversation_id;

// Ask a question
const chatResp = await fetch(
  `${BASE}/notebooks/${notebookId}/conversations/${newConvId}/messages`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      content: "How do I request a refund?",
      persona: "clear",
      language: "en",
    }),
  }
);
console.log((await chatResp.json()).data.assistant_message.content);

const accessResp = await fetch(`${BASE}/notebooks/${notebookId}/access`);
for (const record of (await accessResp.json()).data) {
  console.log(`  ${record.user_id}: ${record.access_level} (granted ${record.granted_at})`);
}

const healthResp = await fetch(`${BASE}/notebooks/${notebookId}/health`);
const health = (await healthResp.json()).data;
console.log(`Health Score: ${health.health_score}/100`);
console.log(`Total Chunks: ${health.total_chunks}`);
console.log(`Duplicates:   ${health.duplicate_count}`);
console.log(`Orphans:      ${health.orphaned_count}`);
console.log(`Enhanced:     ${health.enhanced_count}`);

if (health.duplicate_count > 0) {
  console.log("\nDuplicate groups:");
  for (const group of health.duplicate_groups) {
    console.log(`  Hash ${group.content_hash.slice(0, 16)}...: ${group.count} copies`);
  }
}

const cleanupResp = await fetch(
  `${BASE}/notebooks/${notebookId}/health/cleanup`,
  { method: "POST" }
);
const cleanup = (await cleanupResp.json()).data;
console.log(`Removed ${cleanup.removed_count} duplicate chunks`);
console.log(`New health score: ${cleanup.new_health_score}/100`);
console.log(`Remaining chunks: ${cleanup.new_total_chunks}`);

const errorsResp = await fetch(
  `${BASE}/notebooks/${notebookId}/documents/errors`
);
const errors = (await errorsResp.json()).data;
if (errors.length === 0) {
  console.log("No errored files!");
} else {
  for (const err of errors) {
    console.log(`  ${err.file_name}: ${err.error_message} (stage: ${err.error_stage})`);
  }
}

const reingestResp = await fetch(
  `${BASE}/notebooks/${notebookId}/documents/${errorFileId}/reingest`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      settings: {
        parser: "Mistral OCR",
        chunking_strategy: "Recursive Chunking",
        chunk_size: 800,
        chunk_overlap: 150,
      },
    }),
  }
);
const reingest = (await reingestResp.json()).data;
console.log(`Reingest job: ${reingest.job_id}`);
console.log(`Status: ${reingest.status}`);
console.log(`Cleaned: ${reingest.cleanup_summary.documents_deleted} docs`);

// Wait for reingestion to finish
let reingestStatus;
do {
  const stageResp = await fetch(
    `${BASE}/notebooks/${notebookId}/documents/${errorFileId}/stage`
  );
  reingestStatus = (await stageResp.json()).data.status;
  if (reingestStatus !== "success" && reingestStatus !== "error") {
    await new Promise((r) => setTimeout(r, 3000));
  }
} while (reingestStatus !== "success" && reingestStatus !== "error");

// Check health again
const newHealthResp = await fetch(`${BASE}/notebooks/${notebookId}/health`);
const newHealth = (await newHealthResp.json()).data;
console.log(`Updated Health Score: ${newHealth.health_score}/100`);
console.log(`Total Chunks: ${newHealth.total_chunks}`);
console.log(`Duplicates: ${newHealth.duplicate_count}`);