0
# Blog Information and Content
1

2
Retrieve comprehensive blog information, posts, and various blog-specific content including queue, drafts, submissions, and avatars.
3

4
## Capabilities
5

6
### Blog Information
7

8
Get detailed information about a specific blog.
9

10
```javascript { .api }
11
/**
12
 * Get information about a blog
13
 * @param blogIdentifier - Blog name or URL
14
 * @param params - Optional field selection parameters
15
 * @returns Promise resolving to blog information
16
 */
17
blogInfo(blogIdentifier: string, params?: { 'fields[blogs]'?: string }): Promise<any>;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
// Get basic blog information
24
const blogInfo = await client.blogInfo('staff');
25
console.log(blogInfo.blog.title);        // "Tumblr Staff"
26
console.log(blogInfo.blog.description);  // Blog description
27
console.log(blogInfo.blog.total_posts);  // Total post count
28

29
// Get specific fields only
30
const limitedInfo = await client.blogInfo('staff', {
31
  'fields[blogs]': 'name,title,description,url'
32
});
33
```
34

35
### Blog Posts
36

37
Retrieve posts from a blog with extensive filtering and pagination options.
38

39
```javascript { .api }
40
/**
41
 * Get posts for a blog
42
 * @param blogIdentifier - Blog name or URL
43
 * @param params - Post filtering and pagination parameters
44
 * @returns Promise resolving to blog posts
45
 */
46
blogPosts(blogIdentifier: string, params?: BlogPostsParams): Promise<any>;
47
```
48

49
**Usage Examples:**
50

51
```javascript
52
// Get recent posts
53
const recentPosts = await client.blogPosts('staff');
54
console.log(recentPosts.posts.length);
55

56
// Get specific post by ID
57
const specificPost = await client.blogPosts('staff', {
58
  id: '12345'
59
});
60

61
// Filter by post type
62
const photoPosts = await client.blogPosts('staff', {
63
  type: 'photo',
64
  limit: 20
65
});
66

67
// Filter by tags (posts must have ALL specified tags)
68
const taggedPosts = await client.blogPosts('staff', {
69
  tag: ['announcement', 'features'],
70
  limit: 10
71
});
72

73
// Get posts with additional metadata
74
const detailedPosts = await client.blogPosts('staff', {
75
  reblog_info: true,
76
  notes_info: true,
77
  npf: true  // Return NPF format instead of legacy
78
});
79

80
// Pagination
81
const olderPosts = await client.blogPosts('staff', {
82
  limit: 20,
83
  offset: 20
84
});
85
```
86

87
### Blog Queue
88

89
Get queued posts for a blog (requires authentication and blog ownership).
90

91
```javascript { .api }
92
/**
93
 * Get the queue for a blog
94
 * @param blogIdentifier - Blog name or URL
95
 * @param params - Queue filtering parameters
96
 * @returns Promise resolving to queued posts
97
 */
98
blogQueue(blogIdentifier: string, params?: QueueParams): Promise<any>;
99
```
100

101
**Usage Examples:**
102

103
```javascript
104
// Get all queued posts
105
const queuedPosts = await client.blogQueue('myblog');
106

107
// Get limited queue with filtering
108
const queue = await client.blogQueue('myblog', {
109
  limit: 10,
110
  offset: 0,
111
  filter: 'text'  // 'text' or 'raw'
112
});
113
```
114

115
### Blog Drafts
116

117
Get draft posts for a blog (requires authentication and blog ownership).
118

119
```javascript { .api }
120
/**
121
 * Get drafts for a blog
122
 * @param blogIdentifier - Blog name or URL
123
 * @param params - Draft filtering parameters
124
 * @returns Promise resolving to draft posts
125
 */
126
blogDrafts(blogIdentifier: string, params?: DraftsParams): Promise<any>;
127
```
128

129
**Usage Examples:**
130

131
```javascript
132
// Get all drafts
133
const drafts = await client.blogDrafts('myblog');
134

135
// Get drafts with filtering
136
const recentDrafts = await client.blogDrafts('myblog', {
137
  before_id: 67890,
138
  filter: 'text'
139
});
140
```
141

142
### Blog Submissions
143

144
Get submission posts for a blog (requires authentication and blog ownership).
145

146
```javascript { .api }
147
/**
148
 * Get submissions for a blog
149
 * @param blogIdentifier - Blog name or URL
150
 * @param params - Submission filtering parameters
151
 * @returns Promise resolving to submission posts
152
 */
153
blogSubmissions(blogIdentifier: string, params?: SubmissionsParams): Promise<any>;
154
```
155

156
**Usage Examples:**
157

158
```javascript
159
// Get all submissions
160
const submissions = await client.blogSubmissions('myblog');
161

162
// Get submissions with pagination
163
const pagedSubmissions = await client.blogSubmissions('myblog', {
164
  offset: 10,
165
  filter: 'raw'
166
});
167
```
168

169
### Blog Avatar
170

171
Get the avatar URL for a blog in various sizes.
172

173
```javascript { .api }
174
/**
175
 * Get avatar URL for a blog
176
 * @param blogIdentifier - Blog name or URL
177
 * @param size - Avatar size in pixels
178
 * @returns Promise resolving to avatar URL data
179
 */
180
blogAvatar(blogIdentifier: string, size?: AvatarSize): Promise<any>;
181
```
182

183
**Usage Examples:**
184

185
```javascript
186
// Get default avatar size
187
const avatar = await client.blogAvatar('staff');
188
console.log(avatar.avatar_url);
189

190
// Get specific avatar size
191
const largeAvatar = await client.blogAvatar('staff', 512);
192
const smallAvatar = await client.blogAvatar('staff', 64);
193
```
194

195
## Parameter Types
196

197
### Blog Posts Parameters
198

199
```javascript { .api }
200
interface BlogPostsParams {
201
  /** Specific post ID - returns single post or 404 */
202
  id?: string;
203
  /** Filter by tags - posts must have ALL specified tags (max 4) */
204
  tag?: string | string[];
205
  /** Filter by post type */
206
  type?: PostType;
207
  /** Number of posts to return (1-20) */
208
  limit?: number;
209
  /** Offset for pagination (0 to start from first post) */
210
  offset?: number;
211
  /** Include reblog information */
212
  reblog_info?: boolean;
213
  /** Include notes information and metadata */
214
  notes_info?: boolean;
215
  /** Return NPF format instead of legacy format */
216
  npf?: boolean;
217
}
218

219
type PostType = 'text' | 'quote' | 'link' | 'answer' | 'video' | 'audio' | 'photo' | 'chat';
220
```
221

222
### Queue Parameters
223

224
```javascript { .api }
225
interface QueueParams {
226
  /** Number of posts to return */
227
  limit?: number;
228
  /** Offset for pagination */
229
  offset?: number;
230
  /** Post format filter */
231
  filter?: PostFormatFilter;
232
}
233

234
type PostFormatFilter = 'text' | 'raw';
235
```
236

237
### Draft Parameters
238

239
```javascript { .api }
240
interface DraftsParams {
241
  /** Return drafts before this post ID */
242
  before_id?: number;
243
  /** Post format filter */
244
  filter?: PostFormatFilter;
245
}
246
```
247

248
### Submission Parameters
249

250
```javascript { .api }
251
interface SubmissionsParams {
252
  /** Offset for pagination */
253
  offset?: number;
254
  /** Post format filter */
255
  filter?: PostFormatFilter;
256
}
257
```
258

259
### Avatar Size Type
260

261
```javascript { .api }
262
type AvatarSize = 16 | 24 | 30 | 40 | 48 | 64 | 96 | 128 | 512;
263
```
264

265
## Response Data Examples
266

267
### Blog Info Response
268

269
```javascript
270
{
271
  blog: {
272
    title: "Tumblr Staff",
273
    name: "staff",
274
    total_posts: 1682,
275
    posts: 1682,
276
    url: "https://staff.tumblr.com/",
277
    updated: 1461979830,
278
    description: "The world's *first* content-free social network",
279
    is_nsfw: false,
280
    ask: false,
281
    ask_anon: false,
282
    followed: true,
283
    can_send_fan_mail: true,
284
    share_likes: false,
285
    subscribed: false,
286
    can_subscribe: true
287
  }
288
}
289
```
290

291
### Blog Posts Response
292

293
```javascript
294
{
295
  posts: [
296
    {
297
      id: "12345",
298
      type: "text",
299
      blog_name: "staff",
300
      timestamp: 1461979830,
301
      date: "2016-04-29 22:23:50 GMT",
302
      format: "html",
303
      reblog_key: "abc123",
304
      tags: ["announcement", "features"],
305
      title: "New Features!",
306
      body: "<p>We've added some great new features...</p>",
307
      note_count: 42,
308
      summary: "New features announcement"
309
    }
310
    // ... more posts
311
  ],
312
  total_posts: 1682
313
}
314
```
315

316
## Authentication Requirements
317

318
### Public Access (No Auth Required)
319
- `blogInfo()` - Basic blog information
320
- `blogPosts()` - Public blog posts  
321
- `blogAvatar()` - Blog avatar URLs
322

323
### API Key Required
324
- `blogInfo()` - Enhanced blog information
325
- `blogPosts()` - Enhanced post data and filtering
326

327
### OAuth Required
328
- `blogQueue()` - Requires blog ownership
329
- `blogDrafts()` - Requires blog ownership  
330
- `blogSubmissions()` - Requires blog ownership
331

332
## Error Handling
333

334
Common error scenarios and handling:
335

336
```javascript
337
try {
338
  const posts = await client.blogPosts('nonexistent-blog');
339
} catch (error) {
340
  if (error.message.includes('404')) {
341
    console.error('Blog not found');
342
  } else if (error.message.includes('403')) {
343
    console.error('Blog is private or restricted');
344
  }
345
}
346

347
try {
348
  const queue = await client.blogQueue('someone-elses-blog');
349
} catch (error) {
350
  if (error.message.includes('401')) {
351
    console.error('Authentication required');
352
  } else if (error.message.includes('403')) {
353
    console.error('Not authorized to access this blog\'s queue');
354
  }
355
}
356
```
357

358
## Pagination Strategies
359

360
### Offset-based Pagination
361

362
```javascript
363
async function getAllPosts(blogName) {
364
  const allPosts = [];
365
  let offset = 0;
366
  const limit = 20;
367
  
368
  while (true) {
369
    const response = await client.blogPosts(blogName, { limit, offset });
370
    
371
    if (response.posts.length === 0) {
372
      break; // No more posts
373
    }
374
    
375
    allPosts.push(...response.posts);
376
    offset += limit;
377
    
378
    if (response.posts.length < limit) {
379
      break; // Last page
380
    }
381
  }
382
  
383
  return allPosts;
384
}
385
```
386

387
### ID-based Pagination (for drafts)
388

389
```javascript
390
async function getAllDrafts(blogName) {
391
  const allDrafts = [];
392
  let beforeId = null;
393
  
394
  while (true) {
395
    const params = beforeId ? { before_id: beforeId } : {};
396
    const response = await client.blogDrafts(blogName, params);
397
    
398
    if (response.posts.length === 0) {
399
      break;
400
    }
401
    
402
    allDrafts.push(...response.posts);
403
    beforeId = response.posts[response.posts.length - 1].id;
404
  }
405
  
406
  return allDrafts;
407
}
408
```