0
# Page Operations
1

2
Telegraph page management including creation, editing, retrieval, and analytics. All page methods support both HTML and node-based content formats.
3

4
## Capabilities
5

6
### Create Page
7

8
Create a new Telegraph page with content and metadata.
9

10
```python { .api }
11
def create_page(title: str, content: list = None, html_content: str = None, author_name: str = None, author_url: str = None, return_content: bool = False) -> dict:
12
    """
13
    Create a new Telegraph page.
14

15
    Parameters:
16
    - title (str): Page title
17
    - content (list, optional): Content in Telegraph nodes format
18
    - html_content (str, optional): Content in HTML format (alternative to content)
19
    - author_name (str, optional): Author name for this page
20
    - author_url (str, optional): Author profile link for this page
21
    - return_content (bool): Whether to include content in response
22

23
    Returns:
24
    dict: Page information including url, path, title, and optionally content
25
    """
26
```
27

28
Usage examples:
29

30
```python
31
from telegraph import Telegraph
32

33
telegraph = Telegraph(access_token='your_token')
34

35
# Create page with HTML content
36
response = telegraph.create_page(
37
    title='My Article',
38
    html_content='<p>This is <strong>bold</strong> text.</p>',
39
    author_name='John Doe'
40
)
41
print(f"Page URL: {response['url']}")
42

43
# Create page with node content
44
nodes = [
45
    {'tag': 'p', 'children': ['Hello, world!']}
46
]
47
response = telegraph.create_page(
48
    title='Node Example',
49
    content=nodes
50
)
51
```
52

53
### Edit Page
54

55
Edit an existing Telegraph page with new content or metadata.
56

57
```python { .api }
58
def edit_page(path: str, title: str, content: list = None, html_content: str = None, author_name: str = None, author_url: str = None, return_content: bool = False) -> dict:
59
    """
60
    Edit an existing Telegraph page.
61

62
    Parameters:
63
    - path (str): Page path (from URL after telegra.ph/)
64
    - title (str): New page title
65
    - content (list, optional): New content in Telegraph nodes format
66
    - html_content (str, optional): New content in HTML format
67
    - author_name (str, optional): New author name
68
    - author_url (str, optional): New author profile link
69
    - return_content (bool): Whether to include content in response
70

71
    Returns:
72
    dict: Updated page information
73
    """
74
```
75

76
Usage example:
77

78
```python
79
# Edit existing page
80
response = telegraph.edit_page(
81
    path='My-Article-12-31',
82
    title='Updated Article',
83
    html_content='<p>Updated content with <em>emphasis</em>.</p>'
84
)
85
```
86

87
### Get Page
88

89
Retrieve a Telegraph page with optional content.
90

91
```python { .api }
92
def get_page(path: str, return_content: bool = True, return_html: bool = True) -> dict:
93
    """
94
    Get a Telegraph page.
95

96
    Parameters:
97
    - path (str): Page path (from URL after telegra.ph/)
98
    - return_content (bool): Whether to include page content
99
    - return_html (bool): Return content as HTML (True) or nodes (False)
100

101
    Returns:
102
    dict: Page information including title, author, and optionally content
103
    """
104
```
105

106
Usage examples:
107

108
```python
109
# Get page with HTML content
110
page = telegraph.get_page('My-Article-12-31')
111
print(f"Title: {page['title']}")
112
print(f"Content: {page['content']}")
113

114
# Get page with node content
115
page = telegraph.get_page('My-Article-12-31', return_html=False)
116
print(f"Nodes: {page['content']}")
117

118
# Get page metadata only
119
page = telegraph.get_page('My-Article-12-31', return_content=False)
120
print(f"Views: {page['views']}")
121
```
122

123
### Get Page List
124

125
Retrieve a list of pages belonging to the account.
126

127
```python { .api }
128
def get_page_list(offset: int = 0, limit: int = 50) -> dict:
129
    """
130
    Get list of pages belonging to Telegraph account.
131

132
    Parameters:
133
    - offset (int): Sequential number of first page to return (default: 0)
134
    - limit (int): Number of pages to retrieve (0-200, default: 50)
135

136
    Returns:
137
    dict: Contains 'total_count' and 'pages' list with page information
138
    """
139
```
140

141
Usage example:
142

143
```python
144
# Get first 10 pages
145
result = telegraph.get_page_list(limit=10)
146
print(f"Total pages: {result['total_count']}")
147

148
for page in result['pages']:
149
    print(f"- {page['title']} ({page['url']})")
150

151
# Get next 10 pages
152
result = telegraph.get_page_list(offset=10, limit=10)
153
```
154

155
### Get Page Views
156

157
Get view statistics for a Telegraph page with optional time filtering.
158

159
```python { .api }
160
def get_views(path: str, year: int = None, month: int = None, day: int = None, hour: int = None) -> dict:
161
    """
162
    Get view statistics for a Telegraph page.
163

164
    Parameters:
165
    - path (str): Page path (from URL after telegra.ph/)
166
    - year (int, optional): Filter by year (required if month specified)
167
    - month (int, optional): Filter by month (required if day specified)
168
    - day (int, optional): Filter by day (required if hour specified)
169
    - hour (int, optional): Filter by specific hour
170

171
    Returns:
172
    dict: View statistics with 'views' count
173
    """
174
```
175

176
Usage examples:
177

178
```python
179
# Get total views
180
views = telegraph.get_views('My-Article-12-31')
181
print(f"Total views: {views['views']}")
182

183
# Get views for specific year
184
views = telegraph.get_views('My-Article-12-31', year=2024)
185
print(f"2024 views: {views['views']}")
186

187
# Get views for specific day
188
views = telegraph.get_views('My-Article-12-31', year=2024, month=3, day=15)
189
print(f"March 15, 2024 views: {views['views']}")
190

191
# Get views for specific hour
192
views = telegraph.get_views('My-Article-12-31', year=2024, month=3, day=15, hour=14)
193
print(f"March 15, 2024 2:00 PM views: {views['views']}")
194
```
195

196
## Content Formats
197

198
Telegraph supports two content formats:
199

200
### HTML Content
201
Standard HTML with restricted tag set. Use `html_content` parameter.
202

203
Allowed tags: `a`, `aside`, `b`, `blockquote`, `br`, `code`, `em`, `figcaption`, `figure`, `h3`, `h4`, `hr`, `i`, `iframe`, `img`, `li`, `ol`, `p`, `pre`, `s`, `strong`, `u`, `ul`, `video`
204

205
### Node Content
206
Telegraph's internal JSON format. Use `content` parameter.
207

208
```python
209
nodes = [
210
    {'tag': 'p', 'children': ['Simple paragraph']},
211
    {'tag': 'p', 'children': [
212
        'Text with ',
213
        {'tag': 'strong', 'children': ['bold']},
214
        ' formatting'
215
    ]},
216
    {'tag': 'img', 'attrs': {'src': '/file/image.jpg'}}
217
]
218
```
219

220
## Error Handling
221

222
Page operations may raise these exceptions:
223

224
- `TelegraphException`: API errors, invalid parameters, or authentication failures
225
- `RetryAfterError`: Rate limiting with retry timing
226
- `NotAllowedTag`: HTML contains disallowed tags
227
- `InvalidHTML`: Malformed HTML content
228

229
```python
230
from telegraph.exceptions import TelegraphException, NotAllowedTag, InvalidHTML
231

232
try:
233
    response = telegraph.create_page(
234
        title='Test',
235
        html_content='<script>alert("bad")</script>'
236
    )
237
except NotAllowedTag as e:
238
    print(f"Disallowed tag: {e}")
239
except InvalidHTML as e:
240
    print(f"Invalid HTML: {e}")
241
except TelegraphException as e:
242
    print(f"API error: {e}")
243
```