DEV Community

SurfaceDocs
SurfaceDocs

Posted on

The SurfaceDocs SDK Just Went From Write-Only to Full CRUD

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"
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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")
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

Get It

pip install --upgrade surfacedocs
Enter fullscreen mode Exit fullscreen mode

Everything is backward compatible. Your existing docs.save() calls don't change. You just have more tools now.

app.surfacedocs.dev →


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)