SDK Overview

What’s included in the surfacedocs Python package

Python SDK Overview

The surfacedocs package provides everything you need to save LLM-generated documents.

pip install surfacedocs

Exports

Export	Type	Purpose
SurfaceDocs	class	HTTP client for saving, reading, versioning, and managing documents
SYSTEM_PROMPT	str	Instructions for LLMs to generate documents in the correct format
DOCUMENT_SCHEMA	dict	JSON schema for LLM structured output (generic)
OPENAI_DOCUMENT_SCHEMA	dict	Schema compatible with OpenAI strict mode
GEMINI_DOCUMENT_SCHEMA	dict	Schema compatible with Google Gemini’s response_schema
VersionResult	dataclass	Result from pushing or restoring a version
VersionSummary	dataclass	Summary of a document version

from surfacedocs import (
    SurfaceDocs,
    SYSTEM_PROMPT,
    DOCUMENT_SCHEMA,
    OPENAI_DOCUMENT_SCHEMA,
    GEMINI_DOCUMENT_SCHEMA,
)

Initialization

from surfacedocs import SurfaceDocs

# Pass API key directly
client = SurfaceDocs(api_key="sd_live_...")

# Or use the SURFACEDOCS_API_KEY environment variable
client = SurfaceDocs()

Methods

Method	Description
save(content, folder_id=None)	Save a document from LLM JSON output
save_raw(title, blocks, ...)	Save a document with explicit parameters
get_document(document_id)	Retrieve a document by ID
delete_document(document_id)	Delete a document by ID
create_folder(name, parent_id=None)	Create a new folder
list_folders(parent_id=None)	List folders
push_version(document_id, content)	Push a new version from LLM output
push_version_raw(document_id, title, blocks, ...)	Push a version with explicit parameters
list_versions(document_id)	List all versions of a document
get_version(document_id, version)	Get a specific version with blocks
restore_version(document_id, version)	Restore a previous version as latest

Error Handling

from surfacedocs import (
    SurfaceDocsError,      # Base error
    AuthenticationError,   # Invalid API key
    ValidationError,       # Invalid document format
    DocumentNotFoundError, # Document doesn't exist
    FolderNotFoundError,   # Folder doesn't exist
    VersionNotFoundError,  # Version doesn't exist
)

Environment Variables

Variable	Description
SURFACEDOCS_API_KEY	API key (alternative to passing in constructor)