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`
`SearchResult`	dataclass	A document search result
`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
`search_documents(query, tag, ...)`	Search documents by title or tag
`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)