When we first shipped the SurfaceDocs Python SDK, it did one thing: take your LLM output and give you a URL. docs.save(content) — done.
That was intentional. The output layer for AI pipelines should be dead simple. But as people started building real workflows on top of it, the requests were predictable: "Can I read documents back?" "Can I organize things into folders?" "Can I clean up old runs?"
Fair. Here's what's new.
Read Documents
The SDK can now fetch documents back by ID:
from surfacedocs import SurfaceDocs
docs = SurfaceDocs()
doc = docs.get_document("doc_abc123")
print(doc.title) # "Q4 Analysis"
print(doc.blocks[0].type) # "heading"
print(doc.blocks[0].content) # "Executive Summary"
print(doc.visibility) # "private"
You get the full document — title, blocks, metadata, timestamps, visibility status. Every block has its type, content, and metadata.
Why this matters: Your agent can now read its own previous output. Run a daily analysis pipeline, then have tomorrow's run pull yesterday's document for comparison. Build context over time instead of starting from scratch.
Create and List Folders
Organize programmatically instead of through the UI:
# Create a folder structure
reports = docs.create_folder("Research Reports")
q1 = docs.create_folder("Q1 2026", parent_id=reports.id)
# Save directly to a subfolder
result = docs.save(analysis_output, folder_id=q1.id)
# See what's where
folders = docs.list_folders()
subfolders = docs.list_folders(parent_id=reports.id)
Why this matters: Pipelines that run on schedules can auto-organize. Daily reports go into date-based folders. Per-client analyses go into client folders. Your agent builds a clean library instead of dumping everything into one pile.
Delete Documents
docs.delete_document("doc_abc123")
Simple. Why this matters: Cleanup scripts. Your pipeline generates 30 drafts before producing a final version — now you can programmatically delete the drafts. Retention policies become code, not manual housekeeping.
Editable Titles in the Viewer
Not an SDK change, but a quality-of-life update: document titles are now editable directly in the viewer. Click the title, type, done. No more "Untitled Document" shame.
What This Enables
The SDK went from "fire and forget" to "manage your document lifecycle." A few patterns that are now possible:
Self-referencing agents:
# Agent reads yesterday's report for context
yesterday = docs.get_document(last_report_id)
context = "\n".join(b.content for b in yesterday.blocks)
# Generate today's with awareness of what came before
response = llm.generate(f"Update this analysis with today's data:\n{context}")
result = docs.save(response, folder_id=daily_folder.id)
Automated folder management:
import datetime
# Create today's folder
today = datetime.date.today().isoformat()
folder = docs.create_folder(today, parent_id=archive.id)
# Route all pipeline output there
for report in pipeline.run():
docs.save(report, folder_id=folder.id)
Cleanup scripts:
# Delete documents older than 30 days from a working folder
for doc_id in get_old_document_ids(days=30):
docs.delete_document(doc_id)
Get It
pip install --upgrade surfacedocs
Everything is backward compatible. Your existing docs.save() calls don't change. You just have more tools now.
SurfaceDocs is the output layer for AI pipelines. Now with read, write, organize, and delete — so your AI output actually has a lifecycle.
Top comments (0)