Skip to content

API Reference

Complete API documentation for HtmlGraph.

Documentation Formats

HtmlGraph provides API documentation in two formats:

  • This site - Integrated MkDocs documentation with examples and guides
  • Standalone API Docs - Auto-generated pdoc documentation (alternative view)

Choose whichever format you prefer!

Core Modules

Quick Reference

Importing

from htmlgraph import SDK, HtmlGraph
from htmlgraph.models import Feature, Track, Session
from htmlgraph.planning import Spec, Plan

# ID generation utilities
from htmlgraph import generate_id, parse_id, is_valid_id

SDK Initialization

from htmlgraph import SDK

# Basic initialization
sdk = SDK(agent="claude")

# Custom graph directory
sdk = SDK(agent="claude", graph_dir="/path/to/.htmlgraph")

# Disable auto-session management
sdk = SDK(agent="claude", auto_session=False)

Common Operations

# Features
feature = sdk.features.create("Task")
features = sdk.features.all()
filtered = sdk.features.where(status="in-progress")

# Tracks
track = sdk.tracks.builder().title("Project").create()
tracks = sdk.tracks.all()

# Sessions
sessions = sdk.sessions.all()
current = sdk.sessions.current()

# Status
status = sdk.status()

Type Hints

HtmlGraph is fully typed with Pydantic models:

from htmlgraph import SDK
from htmlgraph.models import Feature, FeatureStatus, Priority

def process_feature(feature: Feature) -> None:
    if feature.status == FeatureStatus.IN_PROGRESS:
        print(f"Working on: {feature.title}")

sdk: SDK = SDK(agent="claude")
feature: Feature = sdk.features.create("Task")

Error Handling

HtmlGraph raises specific exceptions:

from htmlgraph import SDK
from htmlgraph.exceptions import (
    FeatureNotFoundError,
    TrackNotFoundError,
    ValidationError
)

sdk = SDK(agent="claude")

try:
    feature = sdk.features.get("invalid-id")
except FeatureNotFoundError as e:
    print(f"Feature not found: {e}")

try:
    track = sdk.tracks.builder().create()  # Missing title
except ValidationError as e:
    print(f"Validation failed: {e}")

Next Steps

Browse the API documentation: