Search Documents

Find documents by title or tag with search_documents()

Search Documents

search_documents()

Search your documents by title prefix and/or tag. Results are scoped to the authenticated user.

from surfacedocs import SurfaceDocs

docs = SurfaceDocs()

# Search by title prefix
results = docs.search_documents(query="API")

# Search by tag
results = docs.search_documents(tag="guide")

# Combine title + tag
results = docs.search_documents(query="Auth", tag="security")

# Scope to a folder
results = docs.search_documents(query="setup", folder_id="fld_abc123")

for result in results:
    print(f"{result.title} → {result.url}")

Parameters:

Parameter	Type	Required	Description
query	str	No*	Title prefix to search for (case-insensitive)
tag	str	No*	Exact tag to match
folder_id	str	No	Folder ID to scope results
limit	int	No	Max results to return (default: 20, max: 50)
offset	int	No	Number of results to skip for pagination

At least one of query or tag is required.

Returns: list[SearchResult]

Raises: ValidationError if neither query nor tag is provided.

SearchResult

Each result contains document metadata (no blocks — use get_document() to fetch full content).

result.id               # "doc_abc123"
result.url              # "https://app.surfacedocs.dev/d/doc_abc123"
result.folder_id        # "fld_xyz"
result.title            # "API Documentation"
result.content_type     # "markdown"
result.block_count      # 15
result.visibility       # "private"
result.metadata         # {"tags": ["api", "guide"], "source": "claude"}
result.current_version  # 3
result.created_at       # "2024-01-01T00:00:00Z"
result.updated_at       # "2024-01-02T00:00:00Z"

Pagination

Use limit and offset for paginating through results:

# First page
page1 = docs.search_documents(query="report", limit=10, offset=0)

# Second page
page2 = docs.search_documents(query="report", limit=10, offset=10)

Examples

Find all documents tagged by source

# Find everything generated by Claude
claude_docs = docs.search_documents(tag="claude")

# Find everything from a specific pipeline
pipeline_docs = docs.search_documents(tag="weekly-report")

Search within a project folder

results = docs.search_documents(
    query="architecture",
    folder_id="fld_project_x",
    limit=5,
)