DEV Community

SurfaceDocs
SurfaceDocs

Posted on

SurfaceDocs Now Has Versioning, Search, and Real Docs

#ai #python #machinelearning #productivity

SurfaceDocs Now Has Versioning, Search, and Real Docs

SurfaceDocs is the output layer for AI pipelines. Your agents generate documents — reports, summaries, analyses — and SurfaceDocs gives them instant shareable URLs via a Python SDK or REST API. No storage config, no hosting, no frontend work.

We just shipped three features that make it actually useful at scale: document versioning, search, and a proper documentation site.

Here's what landed.

Document Versioning

Every document is now versioned. When your AI agent iterates on a report — refining analysis, incorporating feedback, reprocessing with new data — you get a full version history instead of overwriting the previous output.

from surfacedocs import SurfaceDocsClient

client = SurfaceDocsClient(api_key="sd_live_...")

# Push a new version of an existing document
client.push_version(
    document_id="doc_abc123",
    content="# Q4 Report v3\n\nUpdated with final revenue numbers..."
)

# See what versions exist
versions = client.list_versions(document_id="doc_abc123")
# Returns version history with timestamps and metadata

# Grab a specific version
v2 = client.get_version(document_id="doc_abc123", version=2)

# Roll back if the latest version is wrong
client.restore_version(document_id="doc_abc123", version=2)
Enter fullscreen mode Exit fullscreen mode

Every document now tracks current_version and version_count. There's also push_version_raw() for when you're working with HTML or plain text instead of markdown.

Why this matters: AI agents don't get things right on the first pass. They iterate. A research agent might refine a report five times as new sources come in. A documentation agent might rebuild API docs after every deploy. Without versioning, you're either overwriting history or creating a mess of duplicate documents. Now you get both — a clean URL that always shows the latest, and a full history of how it got there.

Document Search

Once you have hundreds of documents across multiple pipelines, you need to find things. Now you can.

# Search by title prefix (case-insensitive)
results = client.search_documents(query="Q4 Report")

# Filter by tag
results = client.search_documents(tag="financial-analysis")

# Combine filters, scope to a folder, paginate
results = client.search_documents(
    query="weekly",
    tag="metrics",
    folder_id="folder_xyz",
    limit=20,
    offset=0
)
Enter fullscreen mode Exit fullscreen mode

The REST API equivalent:

curl -H "Authorization: Bearer sd_live_..." \
  "https://api.surfacedocs.dev/v1/documents/search?query=Q4&tag=metrics&limit=10"
Enter fullscreen mode Exit fullscreen mode

Search works on title prefix (case-insensitive) and tags. You can filter by folder and paginate with limit/offset. Requires the documents:read API key role.

Why this matters: If you're running multiple AI pipelines — one for customer reports, one for internal docs, one for monitoring summaries — you need a way to find documents without tracking every ID yourself. Tag your documents by pipeline, search by prefix, filter by folder. Your orchestration layer can now query SurfaceDocs like a lightweight document store.

New Documentation Site

We rebuilt the docs from scratch: docs.surfacedocs.dev

Powered by Mintlify, it covers:

  • Python SDK — every method with copy-paste examples
  • REST API reference — full endpoint documentation
  • LLM provider guides — dedicated walkthroughs for OpenAI, Gemini, Anthropic, and a generic guide for any LLM
  • Document schema — what a document object looks like, all fields explained
  • Pricing — no surprises

Every method in the SDK has a corresponding docs page with working examples. If you're integrating SurfaceDocs into an agent framework, the LLM provider guides show exactly how to wire it up.

The Bigger Picture

These three features solve the same underlying problem: AI agents need infrastructure for their output.

We've spent years building infrastructure for AI input — vector databases, embedding pipelines, RAG systems. But what about the other direction? When your agent produces a 10-page analysis, where does it go? A JSON blob in a database? A file on S3 that nobody can find?

SurfaceDocs treats AI-generated documents as first-class artifacts. Versioned, searchable, instantly shareable. Your agent pushes content, gets a URL, and moves on. The human reviews it when they're ready.

With versioning, your agent can iterate without losing history. With search, your orchestration layer can find documents across pipelines. With proper docs, you can actually integrate all of this without reading source code.

Get Started 

pip install surfacedocs
Enter fullscreen mode Exit fullscreen mode 
from surfacedocs import SurfaceDocsClient

client = SurfaceDocsClient(api_key="sd_live_...")
doc = client.create_document(
    title="My First Document",
    content="# Hello World",
    tags=["test"]
)
print(doc.url)  # Instant shareable URL
Enter fullscreen mode Exit fullscreen mode

If you're building AI agents that produce documents, reports, or any text output — give SurfaceDocs a look. It's the plumbing you don't want to build yourself.

Top comments (0)