> ## Documentation Index
> Fetch the complete documentation index at: https://surfacedocs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
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                                       |

```python theme={null}
from surfacedocs import (
    SurfaceDocs,
    SYSTEM_PROMPT,
    DOCUMENT_SCHEMA,
    OPENAI_DOCUMENT_SCHEMA,
    GEMINI_DOCUMENT_SCHEMA,
)
```

## Initialization

```python theme={null}
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)`](/sdk/save-documents#save)                             | Save a document from LLM JSON output     |
| [`save_raw(title, blocks, ...)`](/sdk/save-documents#save_raw)                          | Save a document with explicit parameters |
| [`get_document(document_id)`](/sdk/read-documents)                                      | Retrieve a document by ID                |
| [`search_documents(query, tag, ...)`](/sdk/search-documents)                            | Search documents by title or tag         |
| [`delete_document(document_id)`](/sdk/delete-documents)                                 | Delete a document by ID                  |
| [`create_folder(name, parent_id=None)`](/sdk/folders#create-a-folder)                   | Create a new folder                      |
| [`list_folders(parent_id=None)`](/sdk/folders#list-folders)                             | List folders                             |
| [`push_version(document_id, content)`](/sdk/versioning#push_version)                    | Push a new version from LLM output       |
| [`push_version_raw(document_id, title, blocks, ...)`](/sdk/versioning#push_version_raw) | Push a version with explicit parameters  |
| [`list_versions(document_id)`](/sdk/versioning#list_versions)                           | List all versions of a document          |
| [`get_version(document_id, version)`](/sdk/versioning#get_version)                      | Get a specific version with blocks       |
| [`restore_version(document_id, version)`](/sdk/versioning#restore_version)              | Restore a previous version as latest     |

## Error Handling

```python theme={null}
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) |