bulkit 0.1.1 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -0
- package/dist/index.cjs +13 -5
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +326 -284
- package/dist/index.d.ts +326 -284
- package/dist/index.js +13 -5
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -86,7 +86,7 @@ interface components {
|
|
|
86
86
|
/** @description An attachment carried by one block of a post. */
|
|
87
87
|
Attachment: {
|
|
88
88
|
/**
|
|
89
|
-
* @description Media library id. The stable identifier
|
|
89
|
+
* @description Media library id. The stable identifier: key durable state off this.
|
|
90
90
|
* @example clx3k2p9q0001abcd1234efgh
|
|
91
91
|
*/
|
|
92
92
|
id: string;
|
|
@@ -131,16 +131,16 @@ interface components {
|
|
|
131
131
|
/**
|
|
132
132
|
* @description Whether engagement figures are collected for this channel.
|
|
133
133
|
*
|
|
134
|
-
* `reporting
|
|
134
|
+
* `reporting`: they are, and `GET /public/v1/stats` carries them. `needs-reconnect`: the platform reports engagement but this connection was authorized before the read permission was requested; only the account owner re-authorizing in the app grants it, and no API call can. `unsupported`: the platform does not report engagement to this API at all.
|
|
135
135
|
*
|
|
136
136
|
* Read it before drawing a conclusion from a channel contributing no engagement to `GET /public/v1/stats`: anything other than `reporting` is a gap in COVERAGE, not a finding about the posts.
|
|
137
137
|
* @enum {string}
|
|
138
138
|
*/
|
|
139
139
|
metricsStatus: 'reporting' | 'needs-reconnect' | 'unsupported';
|
|
140
140
|
/**
|
|
141
|
-
* @description Whether a post already published to this channel can be taken down or rewritten
|
|
141
|
+
* @description Whether a post already published to this channel can be taken down or rewritten: what `POST /public/v1/posts/{id}/retract` and `POST /public/v1/posts/{id}/revise` can actually do here.
|
|
142
142
|
*
|
|
143
|
-
* `available
|
|
143
|
+
* `available`: they can, under the permissions this connection holds. `needs-reconnect`: the platform allows it, but this connection was authorized before the permission was requested; only the account owner re-authorizing in the app grants it. `unsupported`: the platform offers no way to reach a post once it is out, so a copy published here is permanent.
|
|
144
144
|
*
|
|
145
145
|
* Read it BEFORE telling a user a post can be recalled. This is the one field here whose false answer nobody can fix: `unsupported` is a property of the platform, not of the connection.
|
|
146
146
|
* @enum {string}
|
|
@@ -149,7 +149,7 @@ interface components {
|
|
|
149
149
|
/**
|
|
150
150
|
* @description Whether this channel may publish a `blocks` entry after the first.
|
|
151
151
|
*
|
|
152
|
-
* `available
|
|
152
|
+
* `available`: it may, up to `limits.maxBlocks` on `GET /public/v1/platforms`. `needs-reconnect`: the platform chains, but continuing a post needs a permission this connection was authorized before we requested it; a second block is refused with `continuation_not_granted`, and only the account owner re-authorizing in the app changes that. `unsupported`: the platform publishes one post and stops.
|
|
153
153
|
*
|
|
154
154
|
* The pair to read with `limits.maxBlocks`: that number is the PLATFORM’s and this is the CONNECTION’s. A client trusting the first alone composes a thread that is accepted nowhere.
|
|
155
155
|
* @enum {string}
|
|
@@ -224,18 +224,18 @@ interface components {
|
|
|
224
224
|
*/
|
|
225
225
|
minAspectRatio: number | null;
|
|
226
226
|
/**
|
|
227
|
-
* @description Highest accepted width ÷ height, measured as the video plays
|
|
227
|
+
* @description Highest accepted width ÷ height, measured as the video plays: rotation is already applied, so a portrait phone clip counts as portrait.
|
|
228
228
|
* @example 10
|
|
229
229
|
*/
|
|
230
230
|
maxAspectRatio: number | null;
|
|
231
231
|
/**
|
|
232
|
-
* @description Most pixels one attachment may contain
|
|
232
|
+
* @description Most pixels one attachment may contain (width × height). Over it is `attachment_too_many_pixels`. Not a byte ceiling in disguise, and the reason it is worth checking before you upload: a 40 megapixel camera JPEG is only a few megabytes, so it satisfies every `maxBytes` here and is still refused. Nothing on this side resizes anything, so a picture over the cap needs saving smaller first.
|
|
233
233
|
* @example 36152320
|
|
234
234
|
*/
|
|
235
235
|
maxPixels: number | null;
|
|
236
|
-
/** @description True when the duration cap belongs to the connected ACCOUNT rather than the platform, so no number published here could be right for every channel
|
|
236
|
+
/** @description True when the duration cap belongs to the connected ACCOUNT rather than the platform, so no number published here could be right for every channel: TikTok grants different creators different maximums. No endpoint will tell you the number: it's resolved when the post publishes, and an over-long video fails then with that account's real limit named in the error. */
|
|
237
237
|
durationIsPerAccount: boolean;
|
|
238
|
-
/** @description Rules that differ by what the file IS, where one number could not be right for both kinds
|
|
238
|
+
/** @description Rules that differ by what the file IS, where one number could not be right for both kinds: Bluesky takes a 1 MB image and a 50 MB video, and a LinkedIn post carries one document OR up to twenty images. `null` on a platform that publishes no per-kind rule. All four kinds are always present when it isn't; a `null` entry means this platform states nothing about that kind, not that it refuses it; `acceptedMimeTypes` is what says which types publish at all. Nothing here widens `maxMedia`; it only narrows it further. */
|
|
239
239
|
perKind: {
|
|
240
240
|
/** @description What this platform allows for images specifically. Null when it publishes no rule about them. */
|
|
241
241
|
image: {
|
|
@@ -245,14 +245,14 @@ interface components {
|
|
|
245
245
|
*/
|
|
246
246
|
maxCount: number | null;
|
|
247
247
|
/**
|
|
248
|
-
* @description Largest ONE image may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment
|
|
248
|
+
* @description Largest ONE image may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment: a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
|
|
249
249
|
* @example 50000000
|
|
250
250
|
*/
|
|
251
251
|
maxBytes: number | null;
|
|
252
252
|
/** @description True when a image may not share a post with a file of any other kind. Mixing them is `attachment_kinds_mixed`. */
|
|
253
253
|
alone: boolean;
|
|
254
254
|
/**
|
|
255
|
-
* @description Lowest width ÷ height accepted for a image, where that differs from the platform-wide `minAspectRatio` above
|
|
255
|
+
* @description Lowest width ÷ height accepted for a image, where that differs from the platform-wide `minAspectRatio` above. It REPLACES that value for this kind rather than narrowing it. Null means the platform-wide one applies. Outside it is `attachment_aspect_unsupported`. Instagram is why: a feed image publishes between 4:5 and 1.91:1 where a video publishes between 0.01:1 and 10:1.
|
|
256
256
|
* @example 0.8
|
|
257
257
|
*/
|
|
258
258
|
minAspectRatio: number | null;
|
|
@@ -262,7 +262,7 @@ interface components {
|
|
|
262
262
|
*/
|
|
263
263
|
maxAspectRatio: number | null;
|
|
264
264
|
/**
|
|
265
|
-
* @description Most pixels ONE image may contain
|
|
265
|
+
* @description Most pixels ONE image may contain (width × height) where that differs from the platform-wide `maxPixels` above, which it REPLACES for this kind rather than narrowing. Null means the platform-wide one applies. Over it is `attachment_too_many_pixels`. LinkedIn is why it sits per kind: its image API refuses anything over 36,152,320 px and its video API publishes no pixel rule at all.
|
|
266
266
|
* @example 36152320
|
|
267
267
|
*/
|
|
268
268
|
maxPixels: number | null;
|
|
@@ -275,14 +275,14 @@ interface components {
|
|
|
275
275
|
*/
|
|
276
276
|
maxCount: number | null;
|
|
277
277
|
/**
|
|
278
|
-
* @description Largest ONE video may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment
|
|
278
|
+
* @description Largest ONE video may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment: a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
|
|
279
279
|
* @example 50000000
|
|
280
280
|
*/
|
|
281
281
|
maxBytes: number | null;
|
|
282
282
|
/** @description True when a video may not share a post with a file of any other kind. Mixing them is `attachment_kinds_mixed`. */
|
|
283
283
|
alone: boolean;
|
|
284
284
|
/**
|
|
285
|
-
* @description Lowest width ÷ height accepted for a video, where that differs from the platform-wide `minAspectRatio` above
|
|
285
|
+
* @description Lowest width ÷ height accepted for a video, where that differs from the platform-wide `minAspectRatio` above. It REPLACES that value for this kind rather than narrowing it. Null means the platform-wide one applies. Outside it is `attachment_aspect_unsupported`. Instagram is why: a feed image publishes between 4:5 and 1.91:1 where a video publishes between 0.01:1 and 10:1.
|
|
286
286
|
* @example 0.8
|
|
287
287
|
*/
|
|
288
288
|
minAspectRatio: number | null;
|
|
@@ -292,7 +292,7 @@ interface components {
|
|
|
292
292
|
*/
|
|
293
293
|
maxAspectRatio: number | null;
|
|
294
294
|
/**
|
|
295
|
-
* @description Most pixels ONE video may contain
|
|
295
|
+
* @description Most pixels ONE video may contain (width × height) where that differs from the platform-wide `maxPixels` above, which it REPLACES for this kind rather than narrowing. Null means the platform-wide one applies. Over it is `attachment_too_many_pixels`. LinkedIn is why it sits per kind: its image API refuses anything over 36,152,320 px and its video API publishes no pixel rule at all.
|
|
296
296
|
* @example 36152320
|
|
297
297
|
*/
|
|
298
298
|
maxPixels: number | null;
|
|
@@ -305,14 +305,14 @@ interface components {
|
|
|
305
305
|
*/
|
|
306
306
|
maxCount: number | null;
|
|
307
307
|
/**
|
|
308
|
-
* @description Largest ONE document may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment
|
|
308
|
+
* @description Largest ONE document may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment: a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
|
|
309
309
|
* @example 50000000
|
|
310
310
|
*/
|
|
311
311
|
maxBytes: number | null;
|
|
312
312
|
/** @description True when a document may not share a post with a file of any other kind. Mixing them is `attachment_kinds_mixed`. */
|
|
313
313
|
alone: boolean;
|
|
314
314
|
/**
|
|
315
|
-
* @description Lowest width ÷ height accepted for a document, where that differs from the platform-wide `minAspectRatio` above
|
|
315
|
+
* @description Lowest width ÷ height accepted for a document, where that differs from the platform-wide `minAspectRatio` above. It REPLACES that value for this kind rather than narrowing it. Null means the platform-wide one applies. Outside it is `attachment_aspect_unsupported`. Instagram is why: a feed image publishes between 4:5 and 1.91:1 where a video publishes between 0.01:1 and 10:1.
|
|
316
316
|
* @example 0.8
|
|
317
317
|
*/
|
|
318
318
|
minAspectRatio: number | null;
|
|
@@ -322,12 +322,12 @@ interface components {
|
|
|
322
322
|
*/
|
|
323
323
|
maxAspectRatio: number | null;
|
|
324
324
|
/**
|
|
325
|
-
* @description Most pixels ONE document may contain
|
|
325
|
+
* @description Most pixels ONE document may contain (width × height) where that differs from the platform-wide `maxPixels` above, which it REPLACES for this kind rather than narrowing. Null means the platform-wide one applies. Over it is `attachment_too_many_pixels`. LinkedIn is why it sits per kind: its image API refuses anything over 36,152,320 px and its video API publishes no pixel rule at all.
|
|
326
326
|
* @example 36152320
|
|
327
327
|
*/
|
|
328
328
|
maxPixels: number | null;
|
|
329
329
|
} | null;
|
|
330
|
-
/** @description Always null. A subtitle file is a kind the media library stores and never a kind a POST carries, so no platform has a rule about how many of them one may hold. Where a subtitle file reaches a platform is a `media` option
|
|
330
|
+
/** @description Always null. A subtitle file is a kind the media library stores and never a kind a POST carries, so no platform has a rule about how many of them one may hold. Where a subtitle file reaches a platform is a `media` option (see YouTube’s `captionFile`) whose own `mimeTypes` and `maxBytes` are the rules that bind it. */
|
|
331
331
|
caption: {
|
|
332
332
|
/**
|
|
333
333
|
* @description Most subtitle files one post may carry, where that is tighter than `maxMedia`. Null means only `maxMedia` binds. Over it is `too_many_attachments_of_kind`.
|
|
@@ -335,14 +335,14 @@ interface components {
|
|
|
335
335
|
*/
|
|
336
336
|
maxCount: number | null;
|
|
337
337
|
/**
|
|
338
|
-
* @description Largest ONE subtitle file may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment
|
|
338
|
+
* @description Largest ONE subtitle file may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment: a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
|
|
339
339
|
* @example 50000000
|
|
340
340
|
*/
|
|
341
341
|
maxBytes: number | null;
|
|
342
342
|
/** @description True when a subtitle file may not share a post with a file of any other kind. Mixing them is `attachment_kinds_mixed`. */
|
|
343
343
|
alone: boolean;
|
|
344
344
|
/**
|
|
345
|
-
* @description Lowest width ÷ height accepted for a subtitle file, where that differs from the platform-wide `minAspectRatio` above
|
|
345
|
+
* @description Lowest width ÷ height accepted for a subtitle file, where that differs from the platform-wide `minAspectRatio` above. It REPLACES that value for this kind rather than narrowing it. Null means the platform-wide one applies. Outside it is `attachment_aspect_unsupported`. Instagram is why: a feed image publishes between 4:5 and 1.91:1 where a video publishes between 0.01:1 and 10:1.
|
|
346
346
|
* @example 0.8
|
|
347
347
|
*/
|
|
348
348
|
minAspectRatio: number | null;
|
|
@@ -352,14 +352,14 @@ interface components {
|
|
|
352
352
|
*/
|
|
353
353
|
maxAspectRatio: number | null;
|
|
354
354
|
/**
|
|
355
|
-
* @description Most pixels ONE subtitle file may contain
|
|
355
|
+
* @description Most pixels ONE subtitle file may contain (width × height) where that differs from the platform-wide `maxPixels` above, which it REPLACES for this kind rather than narrowing. Null means the platform-wide one applies. Over it is `attachment_too_many_pixels`. LinkedIn is why it sits per kind: its image API refuses anything over 36,152,320 px and its video API publishes no pixel rule at all.
|
|
356
356
|
* @example 36152320
|
|
357
357
|
*/
|
|
358
358
|
maxPixels: number | null;
|
|
359
359
|
} | null;
|
|
360
360
|
} | null;
|
|
361
361
|
/**
|
|
362
|
-
* @description Rules for one exact MIME type, where the kind above is too coarse
|
|
362
|
+
* @description Rules for one exact MIME type, where the kind above is too coarse (`null` on a platform that publishes none, which is most of them). Keyed by the mime type as `media.mimeType` reports it. X is why it exists, and it needs every field: X takes "up to 4 photos, 1 animated GIF, or 1 video", where a GIF and a JPEG are both `image`, so the ceiling (15 MB of animation against 5 MB of still), the count and the exclusion are all facts about a type. `maxBytes` REPLACES the kind's ceiling for this file; `maxCount` is counted alongside the kind's cap rather than replacing it, since five images with one GIF among them are five of the kind and one of the type.
|
|
363
363
|
* @example {
|
|
364
364
|
* "image/jpeg": {
|
|
365
365
|
* "maxBytes": 5242880,
|
|
@@ -387,10 +387,10 @@ interface components {
|
|
|
387
387
|
* @example 1
|
|
388
388
|
*/
|
|
389
389
|
maxCount: number | null;
|
|
390
|
-
/** @description True when a file of this type may not share a post with a file of any other type
|
|
390
|
+
/** @description True when a file of this type may not share a post with a file of any other type, its own kind included, which is what separates it from the per-kind flag. Mixing them is `attachment_types_mixed`. */
|
|
391
391
|
alone: boolean;
|
|
392
392
|
/**
|
|
393
|
-
* @description What this platform calls a file of this type in a refusal
|
|
393
|
+
* @description What this platform calls a file of this type in a refusal: "GIF". Null where the kind name is the right word.
|
|
394
394
|
* @example GIF
|
|
395
395
|
*/
|
|
396
396
|
noun: string | null;
|
|
@@ -403,6 +403,11 @@ interface components {
|
|
|
403
403
|
/** Format: uri */
|
|
404
404
|
avatarUrl: string | null;
|
|
405
405
|
} | null;
|
|
406
|
+
/**
|
|
407
|
+
* @description Why this account can’t publish anything right now, such as a TikTok posting cap, in words for the user. Null when nothing is stopping it. Don’t publish to this channel until it clears: the platform refuses the post.
|
|
408
|
+
* @example This TikTok account has reached its posting limit for now. Try again later.
|
|
409
|
+
*/
|
|
410
|
+
postingPaused: string | null;
|
|
406
411
|
};
|
|
407
412
|
/** @description One comment on a published post, read live from the platform. Nothing is stored: a comment deleted on the platform is gone here too. */
|
|
408
413
|
Comment: {
|
|
@@ -443,25 +448,25 @@ interface components {
|
|
|
443
448
|
/** @description A link to the reply on the platform, where one can be built. */
|
|
444
449
|
url: string | null;
|
|
445
450
|
};
|
|
446
|
-
/** @description One block of the chain. Text, attachments, or both
|
|
451
|
+
/** @description One block of the chain. Text, attachments, or both. A block with neither is refused as `content_empty`. */
|
|
447
452
|
CreatePostBlock: {
|
|
448
453
|
/** @description The text. Optional: a block carrying `mediaIds` may omit it, which publishes the image with no caption. The per-platform ceiling is lower and comes from `GET /public/v1/platforms`; this is only the outer bound one request may carry. */
|
|
449
454
|
content?: string;
|
|
450
|
-
/** @description Media ids from `POST /public/v1/media`, in publication order. Ownership is checked server-side
|
|
455
|
+
/** @description Media ids from `POST /public/v1/media`, in publication order. Ownership is checked server-side: an id belonging to another workspace is refused, not silently ignored. */
|
|
451
456
|
mediaIds?: string[];
|
|
452
457
|
/**
|
|
453
|
-
* @description What each attachment shows, for a reader who cannot see it
|
|
458
|
+
* @description What each attachment shows, for a reader who cannot see it, keyed by the media id from `mediaIds` it describes. Overrides the description stored on the library item, so the same photo can read differently here. Omit a key to publish with whatever the library says; a key naming a file this block does not attach is `alt_text_unattached`. Accepted on every platform; `limits.supportsAltText` on GET /platforms says which of them will actually send it.
|
|
454
459
|
* @example {
|
|
455
|
-
* "
|
|
460
|
+
* "clx3k2p9q0003abcd1234efgh": "A hand-drawn logo on a pale background"
|
|
456
461
|
* }
|
|
457
462
|
*/
|
|
458
463
|
mediaAltText?: {
|
|
459
464
|
[key: string]: string;
|
|
460
465
|
};
|
|
461
466
|
/**
|
|
462
|
-
* @description Who each attachment tags, keyed by the media id from `mediaIds` they are tagged on. READ THE OPPOSITE WAY FROM `mediaAltText` above: a description is accepted on every platform because it belongs to the file, while a handle is an account on one platform and the same characters name somebody else on the next
|
|
467
|
+
* @description Who each attachment tags, keyed by the media id from `mediaIds` they are tagged on. READ THE OPPOSITE WAY FROM `mediaAltText` above: a description is accepted on every platform because it belongs to the file, while a handle is an account on one platform and the same characters name somebody else on the next, so this is refused as `user_tags_not_supported` on a channel whose `limits.userTags` is null, rather than accepted and dropped. That declaration also says how many one attachment may carry, which kinds of file take them, and whether a tag needs a point at all.
|
|
463
468
|
* @example {
|
|
464
|
-
* "
|
|
469
|
+
* "clx3k2p9q0003abcd1234efgh": [
|
|
465
470
|
* {
|
|
466
471
|
* "username": "ada",
|
|
467
472
|
* "x": 0.25,
|
|
@@ -478,7 +483,7 @@ interface components {
|
|
|
478
483
|
*/
|
|
479
484
|
username: string;
|
|
480
485
|
/**
|
|
481
|
-
* @description Distance from the LEFT edge as a fraction of the width
|
|
486
|
+
* @description Distance from the LEFT edge as a fraction of the width: 0.5 is the middle, whatever the picture was uploaded at. Not pixels: a fraction is what survives the platform re-encoding the file.
|
|
482
487
|
* @example 0.25
|
|
483
488
|
*/
|
|
484
489
|
x?: number;
|
|
@@ -498,17 +503,17 @@ interface components {
|
|
|
498
503
|
*/
|
|
499
504
|
channelId: string;
|
|
500
505
|
/**
|
|
501
|
-
* @description The post’s title, for channels whose platform has one
|
|
506
|
+
* @description The post’s title, for channels whose platform has one: check `limits.title` on `GET /public/v1/platforms`, which also carries the real cap (this `maxLength` is only the request’s outer bound). Required to publish where that field says `required`; drafts may go without. Sending it to a platform that has no title field is `title_not_supported`.
|
|
502
507
|
* @example How we cut our build time in half
|
|
503
508
|
*/
|
|
504
509
|
title?: string;
|
|
505
510
|
/**
|
|
506
|
-
* @description Which KIND of thing to publish here, on platforms that publish more than one
|
|
511
|
+
* @description Which KIND of thing to publish here, on platforms that publish more than one: an Instagram Story rather than a post on the grid. One of the `key`s in that platform’s `postTypes` on `GET /public/v1/platforms`; omit it for the default, which is what that platform’s top-level `limits` describes. A key it does not declare is `post_type_invalid`, and sending one at all where `postTypes` is empty is `post_type_not_supported`. Read the entry’s own `limits` before composing: a Story takes one attachment against ten, publishes no caption at all, holds a video for a minute rather than fifteen, and declares none of the options a post there has.
|
|
507
512
|
* @example story
|
|
508
513
|
*/
|
|
509
514
|
postType?: string;
|
|
510
515
|
/**
|
|
511
|
-
* @description Values for the fields that belong to this channel's platform alone
|
|
516
|
+
* @description Values for the fields that belong to this channel's platform alone: Pinterest's `link` and `board_section_id`, TikTok's `privacy_level`, X's poll answers. Keyed by the `key` of each entry in that platform's `limits.options` on `GET /public/v1/platforms`, which is also where the caps and accepted values are. A key the platform doesn't declare is `option_not_supported`, not a field we quietly drop. Send a string, unless that entry's `type` is `list`: those take an array of strings, and sending the wrong one of the two shapes is `option_invalid`. The bounds here are the request's outer limits rather than any platform's: the real `minItems`, `maxItems` and per-entry `maxCharacters` are on the declaration.
|
|
512
517
|
* @example {
|
|
513
518
|
* "link": "https://example.com/recipes/pesto"
|
|
514
519
|
* }
|
|
@@ -522,9 +527,9 @@ interface components {
|
|
|
522
527
|
CreatePostRequest: {
|
|
523
528
|
/**
|
|
524
529
|
* @description What to do with it.
|
|
525
|
-
* `draft
|
|
526
|
-
* `schedule
|
|
527
|
-
* `now
|
|
530
|
+
* `draft`: store it, publish nothing. It still occupies its slot.
|
|
531
|
+
* `schedule`: store it and start a durable timer for `scheduledAt`.
|
|
532
|
+
* `now`: store it and queue it for immediate publication.
|
|
528
533
|
*
|
|
529
534
|
* `now` is ASYNCHRONOUS: the response comes back with the submission `publishing`, not published. Publishing takes as long as the platforms take, and a request that blocked on it would time out on exactly the submissions that matter most.
|
|
530
535
|
* @enum {string}
|
|
@@ -535,15 +540,15 @@ interface components {
|
|
|
535
540
|
* @description Required when `intent` is `schedule`. For `draft` it is the slot the post occupies; for `now` it defaults to the moment it was queued.
|
|
536
541
|
*/
|
|
537
542
|
scheduledAt?: string;
|
|
538
|
-
/** @description Where it goes. At least one, for every intent
|
|
543
|
+
/** @description Where it goes. At least one, for every intent, including drafts. */
|
|
539
544
|
channels: components['schemas']['CreatePostChannel'][];
|
|
540
|
-
/** @description The workspace’s own labels for this submission
|
|
545
|
+
/** @description The workspace’s own labels for this submission: ids from `GET /public/v1/tags`. Ids rather than names, because the name is the field a workspace edits. An id this workspace does not own is `tag_not_found`, not a value we drop. On `PUT` this is a replacement like the rest of the body, so omitting it removes every tag. */
|
|
541
546
|
tagIds?: string[];
|
|
542
547
|
};
|
|
543
548
|
CreateWebhookRequest: {
|
|
544
549
|
/**
|
|
545
550
|
* Format: uri
|
|
546
|
-
* @description Absolute `https://` (or `http://` for a local receiver, where the deployment allows it). Addresses only reachable from inside our network are refused as `webhook_url_invalid
|
|
551
|
+
* @description Absolute `https://` (or `http://` for a local receiver, where the deployment allows it). Addresses only reachable from inside our network are refused as `webhook_url_invalid`: nothing sent to one would reach you.
|
|
547
552
|
* @example https://example.com/hooks/bulkit
|
|
548
553
|
*/
|
|
549
554
|
url: string;
|
|
@@ -563,16 +568,16 @@ interface components {
|
|
|
563
568
|
*/
|
|
564
569
|
code: 'unauthorized' | 'forbidden' | 'invalid_request' | 'not_found' | 'conflict' | 'payload_too_large' | 'unsupported_media_type' | 'no_channels' | 'duplicate_channel' | 'content_empty' | 'content_too_long' | 'too_many_blocks' | 'threads_not_supported' | 'continuation_not_granted' | 'too_many_attachments' | 'attachments_not_supported' | 'attachment_type_unsupported' | 'media_required' | 'title_required' | 'title_too_long' | 'title_not_supported' | 'option_required' | 'option_too_long' | 'option_invalid' | 'option_too_many' | 'option_too_few' | 'option_not_supported' | 'post_type_not_supported' | 'post_type_invalid' | 'alt_text_unattached' | 'user_tags_not_supported' | 'user_tags_kind_unsupported' | 'user_tags_unattached' | 'too_many_user_tags' | 'user_tag_position_invalid' | 'tag_not_found' | 'tag_name_taken' | 'tag_limit_reached' | 'hashtag_set_name_taken' | 'hashtag_set_limit_reached' | 'channel_group_name_taken' | 'channel_group_limit_reached' | 'channel_group_channel_not_found' | 'attachment_too_long' | 'attachment_too_short' | 'attachment_aspect_unsupported' | 'attachment_too_many_pixels' | 'attachment_too_large' | 'too_many_attachments_of_kind' | 'attachment_kinds_mixed' | 'too_many_attachments_of_type' | 'attachment_types_mixed' | 'utm_not_supported' | 'utm_too_long' | 'utm_invalid' | 'webhook_url_invalid' | 'webhook_events_invalid' | 'webhook_limit_reached' | 'schedule_required' | 'schedule_in_past' | 'schedule_too_far' | 'schedule_invalid' | 'edit_not_supported' | 'edit_window_expired' | 'revision_structure_changed' | 'retract_failed' | 'comments_not_supported' | 'comments_not_granted' | 'comment_not_found' | 'platform_refused' | 'platform_error' | 'post_already_published' | 'post_publishing' | 'post_changed' | 'post_not_published' | 'post_test_mode' | 'channel_not_connected' | 'request_in_progress' | 'quota_exceeded' | 'workspace_locked' | 'rate_limited' | 'service_unavailable' | 'internal_error';
|
|
565
570
|
/**
|
|
566
|
-
* @description The explanation, in prose, and the best one available
|
|
567
|
-
* @example X (Twitter) allows 280 characters
|
|
571
|
+
* @description The explanation, in prose, and the best one available: safe to surface to your own users. Never branch on it.
|
|
572
|
+
* @example X (Twitter) allows 280 characters; this one is 300
|
|
568
573
|
*/
|
|
569
574
|
message: string;
|
|
570
575
|
/**
|
|
571
|
-
* @description Path into the request body that caused it, where one applies
|
|
576
|
+
* @description Path into the request body that caused it, where one applies, or the name of the offending header, for the failures a header produces (`Idempotency-Key`). When `details` is present this is the first of them.
|
|
572
577
|
* @example channels[1].blocks[0].content
|
|
573
578
|
*/
|
|
574
579
|
field?: string;
|
|
575
|
-
/** @description Every field that failed, when schema validation rejected more than one. Absent otherwise
|
|
580
|
+
/** @description Every field that failed, when schema validation rejected more than one. Absent otherwise: a platform rule refuses one thing at a time. Fix them together rather than a round trip per mistake. */
|
|
576
581
|
details?: components['schemas']['FieldError'][];
|
|
577
582
|
/**
|
|
578
583
|
* @description Echoed from the `x-request-id` response header and logged server-side. Quote it in a support request and the failure is one lookup away.
|
|
@@ -588,7 +593,7 @@ interface components {
|
|
|
588
593
|
*/
|
|
589
594
|
field: string;
|
|
590
595
|
/**
|
|
591
|
-
* @description Why it was rejected. Prose
|
|
596
|
+
* @description Why it was rejected. Prose: never branch on it.
|
|
592
597
|
* @example channels[0].blocks[1].content must be a string
|
|
593
598
|
*/
|
|
594
599
|
message: string;
|
|
@@ -668,7 +673,7 @@ interface components {
|
|
|
668
673
|
*/
|
|
669
674
|
score: number;
|
|
670
675
|
};
|
|
671
|
-
/** @description An endpoint together with its signing secret. Returned by exactly two operations
|
|
676
|
+
/** @description An endpoint together with its signing secret. Returned by exactly two operations (registering an endpoint and rolling its secret) and by nothing else, ever. */
|
|
672
677
|
IssuedWebhookEndpoint: {
|
|
673
678
|
/**
|
|
674
679
|
* @description The signing secret, in the clear. **Store it now.** Only an encrypted copy is kept; the only way to get another is to roll it, which invalidates this one.
|
|
@@ -680,7 +685,7 @@ interface components {
|
|
|
680
685
|
/** @description An item in the workspace’s media library. */
|
|
681
686
|
MediaItem: {
|
|
682
687
|
/**
|
|
683
|
-
* @description Media library id. The stable identifier
|
|
688
|
+
* @description Media library id. The stable identifier: key durable state off this.
|
|
684
689
|
* @example clx3k2p9q0001abcd1234efgh
|
|
685
690
|
*/
|
|
686
691
|
id: string;
|
|
@@ -710,6 +715,14 @@ interface components {
|
|
|
710
715
|
*/
|
|
711
716
|
createdAt: string;
|
|
712
717
|
};
|
|
718
|
+
/** @description A page of the media library, newest first. */
|
|
719
|
+
MediaPage: {
|
|
720
|
+
/** @description The items on this page. */
|
|
721
|
+
data: components['schemas']['MediaItem'][];
|
|
722
|
+
/** @description Pass as `?cursor=` to fetch the next page. Null on the last page. Opaque by contract: do not parse it. */
|
|
723
|
+
nextCursor: string | null;
|
|
724
|
+
hasMore: boolean;
|
|
725
|
+
};
|
|
713
726
|
/** @description An open upload session. Cut the file into `partCount` parts of `partSize` bytes (the last one is whatever is left), ask for their URLs, PUT each part, then complete. */
|
|
714
727
|
MediaUpload: {
|
|
715
728
|
/**
|
|
@@ -754,12 +767,12 @@ interface components {
|
|
|
754
767
|
*/
|
|
755
768
|
id: 'x' | 'linkedin' | 'linkedin_page' | 'instagram' | 'facebook' | 'threads' | 'tiktok' | 'youtube' | 'vimeo' | 'pinterest' | 'bluesky' | 'reddit';
|
|
756
769
|
/**
|
|
757
|
-
* @description Human name, e.g. "X". Display only
|
|
770
|
+
* @description Human name, e.g. "X". Display only: never branch on it.
|
|
758
771
|
* @example X (Twitter)
|
|
759
772
|
*/
|
|
760
773
|
name: string;
|
|
761
774
|
limits: components['schemas']['PlatformLimits'];
|
|
762
|
-
/** @description The KINDS of thing this platform publishes, where it publishes more than one
|
|
775
|
+
/** @description The KINDS of thing this platform publishes, where it publishes more than one: an Instagram Story against a post on the grid. EMPTY on every platform with a single kind, which is all of them but Instagram, so there is always an array to read. Send one entry’s `key` as `channels[].postType`; a key that is not listed is `post_type_invalid`, and sending one at all where this array is empty is `post_type_not_supported`. Omitting it asks for the FIRST entry, which is what `limits` above already describes, so a client that ignores this field reads exactly the platform it read before post types existed. */
|
|
763
776
|
postTypes: components['schemas']['PostType'][];
|
|
764
777
|
/**
|
|
765
778
|
* @description What this platform calls a block after the first: "post" on X, "comment" on LinkedIn. Travels so your own error messages can use the word your user would recognise.
|
|
@@ -767,7 +780,7 @@ interface components {
|
|
|
767
780
|
*/
|
|
768
781
|
continuationNoun: string;
|
|
769
782
|
};
|
|
770
|
-
/** @description What this platform accepts. Read these rather than hardcoding them
|
|
783
|
+
/** @description What this platform accepts. Read these rather than hardcoding them: they change when a platform changes, and a client carrying its own copy will be wrong before we are. */
|
|
771
784
|
PlatformLimits: {
|
|
772
785
|
/**
|
|
773
786
|
* @description Characters one block may carry.
|
|
@@ -775,7 +788,7 @@ interface components {
|
|
|
775
788
|
*/
|
|
776
789
|
maxCharacters: number;
|
|
777
790
|
/**
|
|
778
|
-
* @description The most a block may carry on an account with the platform's paid tier, where one buys more room than `maxCharacters`. Null where every account gets the same number, which is every platform but X. Compose against `maxCharacters` unless you know the account has paid: nothing here says which tier a channel is on, so text between the two numbers is accepted by this API and settled by the platform at publish
|
|
791
|
+
* @description The most a block may carry on an account with the platform's paid tier, where one buys more room than `maxCharacters`. Null where every account gets the same number, which is every platform but X. Compose against `maxCharacters` unless you know the account has paid: nothing here says which tier a channel is on, so text between the two numbers is accepted by this API and settled by the platform at publish: it goes out for an account that pays and comes back as a publish error for one that doesn't. Over this number is `content_too_long`, for anyone.
|
|
779
792
|
* @example 25000
|
|
780
793
|
*/
|
|
781
794
|
maxCharactersPerAccount?: number | null;
|
|
@@ -804,7 +817,7 @@ interface components {
|
|
|
804
817
|
/** @description The platform refuses a post carrying no attachment at all. */
|
|
805
818
|
requiresMedia: boolean;
|
|
806
819
|
/**
|
|
807
|
-
* @description The mime types an attachment may be on this platform. The counts above can't express this, and on a video-only platform it decides whether the post can go out at all
|
|
820
|
+
* @description The mime types an attachment may be on this platform. The counts above can't express this, and on a video-only platform it decides whether the post can go out at all. Check an upload's `mimeType` against every platform it's headed for.
|
|
808
821
|
* @example [
|
|
809
822
|
* "image/jpeg",
|
|
810
823
|
* "image/png",
|
|
@@ -813,9 +826,9 @@ interface components {
|
|
|
813
826
|
* ]
|
|
814
827
|
*/
|
|
815
828
|
acceptedMimeTypes: string[];
|
|
816
|
-
/** @description This platform publishes a per-attachment description and we send it. NOT a rule to validate against
|
|
829
|
+
/** @description This platform publishes a per-attachment description and we send it. NOT a rule to validate against: `blocks[].mediaAltText` is accepted on every platform, because a description belongs to the file and one submission fans out to several channels. Read it to decide whether to ask for a description, and to explain why the one you wrote will not appear on a channel that returns false. */
|
|
817
830
|
supportsAltText: boolean;
|
|
818
|
-
/** @description What this platform does with people tagged on an attachment, or null when it tags nobody. UNLIKE `supportsAltText` above, this IS a rule to validate against: a description belongs to the file and an unused one costs the post nothing, while a handle is an account on THIS platform and the same characters name somebody else on the next one
|
|
831
|
+
/** @description What this platform does with people tagged on an attachment, or null when it tags nobody. UNLIKE `supportsAltText` above, this IS a rule to validate against: a description belongs to the file and an unused one costs the post nothing, while a handle is an account on THIS platform and the same characters name somebody else on the next one, so `blocks[].mediaUserTags` sent to a channel whose value here is null is refused as `user_tags_not_supported`. The whole object changes with `channels[].postType`; read it off the entry in `postTypes` you are publishing. */
|
|
819
832
|
userTags?: {
|
|
820
833
|
/**
|
|
821
834
|
* @description Most people ONE attachment may tag. Per attachment, not per post: a carousel tags this many on every picture it carries.
|
|
@@ -829,12 +842,12 @@ interface components {
|
|
|
829
842
|
* ]
|
|
830
843
|
*/
|
|
831
844
|
kinds: ('image' | 'video' | 'document' | 'caption')[];
|
|
832
|
-
/** @description A tag names a POINT on the attachment as well as a person. Send `x` and `y` when true and neither when false
|
|
845
|
+
/** @description A tag names a POINT on the attachment as well as a person. Send `x` and `y` when true and neither when false: either one the wrong way round is `user_tag_position_invalid`. An Instagram feed photo is true; a Story is false, because it mentions someone without pointing at them. */
|
|
833
846
|
positioned: boolean;
|
|
834
847
|
} | null;
|
|
835
|
-
/** @description This platform publishes the block's text. `false` means it has no caption field at all
|
|
848
|
+
/** @description This platform publishes the block's text. `false` means it has no caption field at all: an Instagram Story, where the words are stored, published on every other channel of the same submission, and dropped here. Not a rule to check against: content is accepted on every platform, because one submission fans out to several and a caption written for four channels is not refused by the fifth. Where it is false there is nothing to count against `maxCharacters`. */
|
|
836
849
|
publishesContent: boolean;
|
|
837
|
-
/** @description Set on platforms whose post has a TITLE field of its own, alongside its body
|
|
850
|
+
/** @description Set on platforms whose post has a TITLE field of its own, alongside its body: send it as `channels[].title` when creating a post. `null` on platforms that have no such field, which is most of them; sending a title to one of those is rejected with `title_not_supported` rather than ignored. Where it is set, `maxCharacters` is the title's own cap (unrelated to `maxCharacters` above, which measures the body) and going over is `title_too_long`; the title is never silently shortened. If `required` is true, publishing without one is `title_required`; drafts are exempt. */
|
|
838
851
|
title: {
|
|
839
852
|
/**
|
|
840
853
|
* @description Characters the title may carry. Counted in code points, so an emoji is one character.
|
|
@@ -842,16 +855,16 @@ interface components {
|
|
|
842
855
|
*/
|
|
843
856
|
maxCharacters: number;
|
|
844
857
|
/**
|
|
845
|
-
* @description What the platform calls the field. Display only
|
|
858
|
+
* @description What the platform calls the field. Display only: never branch on it.
|
|
846
859
|
* @example Title
|
|
847
860
|
*/
|
|
848
861
|
label: string;
|
|
849
862
|
/** @description The platform will not publish a post without a title. Checked when publishing, not when drafting. */
|
|
850
863
|
required: boolean;
|
|
851
|
-
/** @description A first block carrying a title needs nothing else
|
|
864
|
+
/** @description A first block carrying a title needs nothing else: no `content`, no `mediaIds`. True on Reddit, where a link submission is a title and a URL and a self post with an empty body is an ordinary title-only post. False everywhere else, where a block with neither text nor an attachment is `content_empty` whatever its title says. Only the first block: a continuation has no title of its own. */
|
|
852
865
|
standsAlone: boolean;
|
|
853
866
|
} | null;
|
|
854
|
-
/** @description Fields this platform has that others don't
|
|
867
|
+
/** @description Fields this platform has that others don't: Pinterest's destination link and alt text, TikTok's privacy level. Send values as `channels[].options`, keyed by each entry's `key`. Empty on a platform whose post is only its content, so there is always an array here to read. A key that isn't listed is rejected with `option_not_supported` rather than dropped. */
|
|
855
868
|
options: {
|
|
856
869
|
/**
|
|
857
870
|
* @description Send the value under this key in `channels[].options`.
|
|
@@ -859,40 +872,40 @@ interface components {
|
|
|
859
872
|
*/
|
|
860
873
|
key: string;
|
|
861
874
|
/**
|
|
862
|
-
* @description What the platform calls the field. Display only
|
|
875
|
+
* @description What the platform calls the field. Display only: never branch on it.
|
|
863
876
|
* @example Destination link
|
|
864
877
|
*/
|
|
865
878
|
label: string;
|
|
866
879
|
/**
|
|
867
|
-
* @description `text` is free text capped by `maxCharacters`; `url` must be an absolute http(s) address or it is `option_invalid`; `choice` must be one of `choices` when that list is present; `boolean` takes the string `"true"` or `"false"`; `media` is the id of a file you uploaded, and the `media` object on this entry says what that file may be. Those five are all sent as strings whatever they mean. `list` is the one that is not: it is a REPEATED value
|
|
880
|
+
* @description `text` is free text capped by `maxCharacters`; `url` must be an absolute http(s) address or it is `option_invalid`; `choice` must be one of `choices` when that list is present; `boolean` takes the string `"true"` or `"false"`; `media` is the id of a file you uploaded, and the `media` object on this entry says what that file may be. Those five are all sent as strings whatever they mean. `list` is the one that is not: it is a REPEATED value (X’s poll answers) sent as a JSON array of strings, bounded by `minItems`/`maxItems`, with `maxCharacters` applying to each entry rather than to the whole. `search` is a string too, and it is an opaque platform id from a set too large to publish here: Instagram’s `location_id` is one Facebook Page out of every Page that has an address. Its `choices` is null and stays null, because there is no list. Send an id you already hold and nothing validates it on submission; the platform settles it when the post goes out, which for a place that has since closed is the post publishing without one. To turn a NAME into one of these ids, call `GET /channels/{id}/options/{key}/choices?q=...` and send the `value` it returns.
|
|
868
881
|
* @enum {string}
|
|
869
882
|
*/
|
|
870
883
|
type: 'text' | 'url' | 'choice' | 'boolean' | 'list' | 'media' | 'search';
|
|
871
|
-
/** @description The platform will not publish without this field. Checked when publishing, not when drafting
|
|
884
|
+
/** @description The platform will not publish without this field. Checked when publishing, not when drafting: going without is `option_required`. */
|
|
872
885
|
required: boolean;
|
|
873
886
|
/** @description A sentence describing the field, where its label doesn't say enough on its own. */
|
|
874
887
|
help: string | null;
|
|
875
|
-
/** @description Shown in place of `help` while a `boolean` is on
|
|
888
|
+
/** @description Shown in place of `help` while a `boolean` is on: the sentence that only becomes true once it's set. Where a platform requires a declaration before publishing, this is it: TikTok's guidelines set out what a creator undertakes by marking a video a paid partnership, and a client that puts someone in front of that checkbox is expected to put them in front of this too. Null on every non-boolean and on every option with nothing extra to say. */
|
|
876
889
|
helpWhenOn: string | null;
|
|
877
890
|
/**
|
|
878
|
-
* @description Cap for a `text` or `url`, counted in code points, and for ONE ENTRY of a `list`. Over it is `option_too_long`
|
|
891
|
+
* @description Cap for a `text` or `url`, counted in code points, and for ONE ENTRY of a `list`. Over it is `option_too_long` (the value is never silently shortened) and on a list the error’s `field` pointer carries the index of the entry that was too long. The per-entry reading is the only one that means anything on a repeated field: X allows 25 characters per poll answer and states no rule about the four of them together. Null on a `choice`.
|
|
879
892
|
* @example 2048
|
|
880
893
|
*/
|
|
881
894
|
maxCharacters: number | null;
|
|
882
895
|
/**
|
|
883
|
-
* @description Fewest entries a `list` may carry, checked only when publishing
|
|
896
|
+
* @description Fewest entries a `list` may carry, checked only when publishing, like `required`, because a draft carrying one poll answer so far is unfinished rather than wrong. Under it is `option_too_few`. An EMPTY list is not this: it is the same as sending nothing at all, so it answers to `required` and never to `minItems`. Null on every other type, and on a list the platform does not bound from below.
|
|
884
897
|
* @example 2
|
|
885
898
|
*/
|
|
886
899
|
minItems: number | null;
|
|
887
900
|
/**
|
|
888
|
-
* @description Most entries a `list` may carry, checked whenever the field is sent. Over it is `option_too_many
|
|
901
|
+
* @description Most entries a `list` may carry, checked whenever the field is sent. Over it is `option_too_many`, separate from `option_too_long`, which on a list measures one entry, because too many answers and too long an answer are fixed in different places. Null on every other type.
|
|
889
902
|
* @example 4
|
|
890
903
|
*/
|
|
891
904
|
maxItems: number | null;
|
|
892
|
-
/** @description What a `media` option's file may be
|
|
905
|
+
/** @description What a `media` option's file may be: a SECOND attachment, with rules of its own rather than the block's. Deliberately not `acceptedMimeTypes` and `limits.media`, which describe the post's attachments: a YouTube post's attachment is the video and its thumbnail is a still picture, and the same platform refuses each in the other's place. Send the media `id` as this option's value, exactly as `blocks[].mediaIds` takes ids. A file that isn't in your workspace, isn't one of `mimeTypes`, or is over `maxBytes` is `option_invalid` against this key. Null on every other type. */
|
|
893
906
|
media: {
|
|
894
907
|
/**
|
|
895
|
-
* @description The file types this slot publishes. What our publish SENDS today rather than what the platform documents
|
|
908
|
+
* @description The file types this slot publishes. What our publish SENDS today rather than what the platform documents: the same promise `acceptedMimeTypes` makes.
|
|
896
909
|
* @example [
|
|
897
910
|
* "image/jpeg",
|
|
898
911
|
* "image/png"
|
|
@@ -905,7 +918,7 @@ interface components {
|
|
|
905
918
|
*/
|
|
906
919
|
maxBytes: number | null;
|
|
907
920
|
} | null;
|
|
908
|
-
/** @description The accepted values of a `choice
|
|
921
|
+
/** @description The accepted values of a `choice`, or **null when they depend on the connected account rather than the platform**, which is TikTok's privacy levels: what a creator may post as varies by account and by the app's review status, so no list published here would be right for every channel. A null means the value isn't validated on submission; read what one channel allows from `GET /channels/{id}/capabilities`, or send what the account should use and the platform settles it at publish time, falling back to what that account does allow. Always null on a `text` or `url`, and always null on a `search` for a different reason worth telling apart: a dynamic `choice` has a list this endpoint can't publish because it belongs to an account, while a `search` has no list at all. */
|
|
909
922
|
choices: {
|
|
910
923
|
/** @description Send this. */
|
|
911
924
|
value: string;
|
|
@@ -914,7 +927,7 @@ interface components {
|
|
|
914
927
|
/** @description Extra context, where the label needs it. */
|
|
915
928
|
help: string | null;
|
|
916
929
|
}[] | null;
|
|
917
|
-
/** @description What this field rules out elsewhere, read as: while you send a value for this key, the named option may not carry the listed values
|
|
930
|
+
/** @description What this field rules out elsewhere, read as: while you send a value for this key, the named option may not carry the listed values; or, where `values` is null, may not carry any value at all. “Sending a value” is the same reading `rulesOutMedia` uses: a `boolean` counts only as `"true"`, a `list` only with an entry in it. A rule of the platform's rather than of ours (TikTok will not publish a video marked as a paid partnership with a `privacy_level` of `SELF_ONLY`, and Threads will not attach a link preview to a post that is also a poll) and sending the pair anyway is `option_invalid` against the key named here, not against the field that caused it. This is the one case where a `choice` with a null `choices` list is validated on submission: what an account may pick is still not checked, but a combination the platform publishes as impossible needs nothing asked of the account. A MUTUAL exclusion appears on both fields, each carrying the sentence that reads correctly when that field is the one you added. Always an array; empty on the options that have no such rule, which is most of them. */
|
|
918
931
|
rulesOut: {
|
|
919
932
|
/**
|
|
920
933
|
* @description The other option's `key`.
|
|
@@ -922,7 +935,7 @@ interface components {
|
|
|
922
935
|
*/
|
|
923
936
|
key: string;
|
|
924
937
|
/**
|
|
925
|
-
* @description Values of that option you may not send alongside this one, or null where the option may not be sent at all
|
|
938
|
+
* @description Values of that option you may not send alongside this one, or null where the option may not be sent at all: the only reading available where the other field has no enumerable values (a `text`, a `url` or a `list`). Never an empty array: a rule that excludes nothing is not published.
|
|
926
939
|
* @example [
|
|
927
940
|
* "SELF_ONLY"
|
|
928
941
|
* ]
|
|
@@ -931,22 +944,22 @@ interface components {
|
|
|
931
944
|
/** @description Why, in the platform's terms. Safe to show a user verbatim. */
|
|
932
945
|
reason: string;
|
|
933
946
|
}[];
|
|
934
|
-
/** @description Set where sending a value for this field means the post may carry NO ATTACHMENTS, to the platform’s own sentence saying why
|
|
947
|
+
/** @description Set where sending a value for this field means the post may carry NO ATTACHMENTS, to the platform’s own sentence saying why, safe to show a user verbatim. `rulesOut`’s counterpart for the thing a post HAS rather than a field it carries: a tweet is a poll or it is pictures, never both. Sending the pair anyway is `option_invalid`, reported against the `mediaIds` of the block that would have to give something up rather than against this key. Applies while the field has any value at all: a `boolean` that is `"true"`, or a `list` with an entry in it; an empty list rules nothing out. Null where the field and the attachments are independent, which is nearly everywhere. */
|
|
935
948
|
rulesOutMedia: string | null;
|
|
936
|
-
/** @description What sending a value for this field makes REQUIRED elsewhere: while this one carries a value, every option named here has to carry one too. `rulesOut`’s obligation to its prohibition, and it exists because `required` cannot say it
|
|
949
|
+
/** @description What sending a value for this field makes REQUIRED elsewhere: while this one carries a value, every option named here has to carry one too. `rulesOut`’s obligation to its prohibition, and it exists because `required` cannot say it: LinkedIn’s poll needs a question as well as its answers, and declaring the question `required` would demand one of every ordinary status update. “Carrying a value” is the same reading the two rules above use: a `boolean` counts only as `"true"`, a `list` only with an entry in it. Sending one half without the other is `option_required` against the key named here: the same code as a plain missing field, because that is what it is, with the platform’s own sentence in place of ours. Checked only when publishing, like `required` and `minItems`: a draft carrying half a poll is unfinished rather than wrong. A MUTUAL obligation appears on both fields, each carrying the sentence that reads correctly when that field is the half you left out. Always an array; empty on the options that impose nothing, which is nearly all of them. */
|
|
937
950
|
requires: {
|
|
938
951
|
/**
|
|
939
|
-
* @description The other option's `key
|
|
952
|
+
* @description The other option's `key`: the one you also have to send a value for.
|
|
940
953
|
* @example poll_question
|
|
941
954
|
*/
|
|
942
955
|
key: string;
|
|
943
956
|
/** @description Why, in the platform's terms. Safe to show a user verbatim, and it names both repairs: send the missing half, or clear the one you sent. */
|
|
944
957
|
reason: string;
|
|
945
958
|
}[];
|
|
946
|
-
/** @description Set where an ATTACHMENT of one kind makes this field necessary, to that kind and the platform’s own sentence saying why. `requires` read from the other side
|
|
959
|
+
/** @description Set where an ATTACHMENT of one kind makes this field necessary, to that kind and the platform’s own sentence saying why. `requires` read from the other side. There another FIELD makes this one necessary, here it is a file: Pinterest refuses a Pin made from a video that has no cover image, and `required` could not say so, since most Pins are pictures and a picture has no cover. Checked only when publishing, like `required` and `requires`, and refused as `option_required` against this key rather than against the attachment that caused it. Null where nothing a post carries has any bearing on the field, which is nearly everywhere. */
|
|
947
960
|
requiredWithMedia: {
|
|
948
961
|
/**
|
|
949
|
-
* @description The kind of attachment that makes this field necessary
|
|
962
|
+
* @description The kind of attachment that makes this field necessary: the same vocabulary `media.perKind` is keyed by. An attachment of any other kind leaves the field optional. `caption` is in the vocabulary and cannot appear here: a subtitle file is never a post’s attachment.
|
|
950
963
|
* @example video
|
|
951
964
|
* @enum {string}
|
|
952
965
|
*/
|
|
@@ -955,11 +968,11 @@ interface components {
|
|
|
955
968
|
reason: string;
|
|
956
969
|
} | null;
|
|
957
970
|
/**
|
|
958
|
-
* @description The `boolean` option that has to be on before this field may carry a value at all. A FOLLOW-UP QUESTION rather than a rule between two answers, which is what separates it from `rulesOut` and `requires`: those describe what a filled-in field does to another field that is always there, while this says the field is not there yet. TikTok’s commercial-content disclosure is the case
|
|
971
|
+
* @description The `boolean` option that has to be on before this field may carry a value at all. A FOLLOW-UP QUESTION rather than a rule between two answers, which is what separates it from `rulesOut` and `requires`: those describe what a filled-in field does to another field that is always there, while this says the field is not there yet. TikTok’s commercial-content disclosure is the case: the two boxes naming what a post promotes only mean anything once the creator has said it promotes something. Sending a value for this key while the named option is off or absent is `option_invalid` against THIS key, and it is refused whether or not you are publishing: it is not an unfinished answer, it is an answer to a question nobody asked. On TikTok it is also a commercial label, and a label nobody confirmed must not reach a published video. Null where the field always applies, which is nearly everywhere.
|
|
959
972
|
* @example disclose_content
|
|
960
973
|
*/
|
|
961
974
|
revealedBy: string | null;
|
|
962
|
-
/** @description `requires` with the quantifier changed: while this field carries a value, ANY ONE of the named options has to carry one too. That rule names a field and demands it, and two entries mean both; this names a set and demands one of them without preferring either. TikTok’s disclosure parent is the case
|
|
975
|
+
/** @description `requires` with the quantifier changed: while this field carries a value, ANY ONE of the named options has to carry one too. That rule names a field and demands it, and two entries mean both; this names a set and demands one of them without preferring either. TikTok’s disclosure parent is the case: the creator has to say which kind of promotion it is, and either answer is a complete one. Checked only when publishing, like `required` and `requires`, and refused as `option_required` against the first key in the set. Null where the field demands nothing, which is nearly everywhere. */
|
|
963
976
|
requiresAnyOf: {
|
|
964
977
|
/**
|
|
965
978
|
* @description The option keys, one of which must carry a value. “Carrying a value” is the same reading every other rule here uses: a `boolean` counts only as `"true"`, a `list` only with an entry in it.
|
|
@@ -973,7 +986,7 @@ interface components {
|
|
|
973
986
|
reason: string;
|
|
974
987
|
} | null;
|
|
975
988
|
}[];
|
|
976
|
-
/** @description What an attachment must BE here beyond its file type
|
|
989
|
+
/** @description What an attachment must BE here beyond its file type: how long a video runs and what shape it is. `null` on a platform that publishes no such rule, which is most of them. Every field is transcribed from the platform's own spec and nothing is inferred, so a null field means the platform states no rule rather than that anything goes. Worth reading before you upload rather than before you post: these are the limits you can only satisfy with a different file. Checked only against values we measured: duration and dimensions are read from the container at upload, are always unknown for images, and an unknown value never refuses a post. */
|
|
977
990
|
media: {
|
|
978
991
|
/**
|
|
979
992
|
* @description Longest a video may run. Over it is `attachment_too_long`.
|
|
@@ -991,18 +1004,18 @@ interface components {
|
|
|
991
1004
|
*/
|
|
992
1005
|
minAspectRatio: number | null;
|
|
993
1006
|
/**
|
|
994
|
-
* @description Highest accepted width ÷ height, measured as the video plays
|
|
1007
|
+
* @description Highest accepted width ÷ height, measured as the video plays: rotation is already applied, so a portrait phone clip counts as portrait.
|
|
995
1008
|
* @example 10
|
|
996
1009
|
*/
|
|
997
1010
|
maxAspectRatio: number | null;
|
|
998
1011
|
/**
|
|
999
|
-
* @description Most pixels one attachment may contain
|
|
1012
|
+
* @description Most pixels one attachment may contain (width × height). Over it is `attachment_too_many_pixels`. Not a byte ceiling in disguise, and the reason it is worth checking before you upload: a 40 megapixel camera JPEG is only a few megabytes, so it satisfies every `maxBytes` here and is still refused. Nothing on this side resizes anything, so a picture over the cap needs saving smaller first.
|
|
1000
1013
|
* @example 36152320
|
|
1001
1014
|
*/
|
|
1002
1015
|
maxPixels: number | null;
|
|
1003
|
-
/** @description True when the duration cap belongs to the connected ACCOUNT rather than the platform, so no number published here could be right for every channel
|
|
1016
|
+
/** @description True when the duration cap belongs to the connected ACCOUNT rather than the platform, so no number published here could be right for every channel: TikTok grants different creators different maximums. No endpoint will tell you the number: it's resolved when the post publishes, and an over-long video fails then with that account's real limit named in the error. */
|
|
1004
1017
|
durationIsPerAccount: boolean;
|
|
1005
|
-
/** @description Rules that differ by what the file IS, where one number could not be right for both kinds
|
|
1018
|
+
/** @description Rules that differ by what the file IS, where one number could not be right for both kinds: Bluesky takes a 1 MB image and a 50 MB video, and a LinkedIn post carries one document OR up to twenty images. `null` on a platform that publishes no per-kind rule. All four kinds are always present when it isn't; a `null` entry means this platform states nothing about that kind, not that it refuses it; `acceptedMimeTypes` is what says which types publish at all. Nothing here widens `maxMedia`; it only narrows it further. */
|
|
1006
1019
|
perKind: {
|
|
1007
1020
|
/** @description What this platform allows for images specifically. Null when it publishes no rule about them. */
|
|
1008
1021
|
image: {
|
|
@@ -1012,14 +1025,14 @@ interface components {
|
|
|
1012
1025
|
*/
|
|
1013
1026
|
maxCount: number | null;
|
|
1014
1027
|
/**
|
|
1015
|
-
* @description Largest ONE image may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment
|
|
1028
|
+
* @description Largest ONE image may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment: a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
|
|
1016
1029
|
* @example 50000000
|
|
1017
1030
|
*/
|
|
1018
1031
|
maxBytes: number | null;
|
|
1019
1032
|
/** @description True when a image may not share a post with a file of any other kind. Mixing them is `attachment_kinds_mixed`. */
|
|
1020
1033
|
alone: boolean;
|
|
1021
1034
|
/**
|
|
1022
|
-
* @description Lowest width ÷ height accepted for a image, where that differs from the platform-wide `minAspectRatio` above
|
|
1035
|
+
* @description Lowest width ÷ height accepted for a image, where that differs from the platform-wide `minAspectRatio` above. It REPLACES that value for this kind rather than narrowing it. Null means the platform-wide one applies. Outside it is `attachment_aspect_unsupported`. Instagram is why: a feed image publishes between 4:5 and 1.91:1 where a video publishes between 0.01:1 and 10:1.
|
|
1023
1036
|
* @example 0.8
|
|
1024
1037
|
*/
|
|
1025
1038
|
minAspectRatio: number | null;
|
|
@@ -1029,7 +1042,7 @@ interface components {
|
|
|
1029
1042
|
*/
|
|
1030
1043
|
maxAspectRatio: number | null;
|
|
1031
1044
|
/**
|
|
1032
|
-
* @description Most pixels ONE image may contain
|
|
1045
|
+
* @description Most pixels ONE image may contain (width × height) where that differs from the platform-wide `maxPixels` above, which it REPLACES for this kind rather than narrowing. Null means the platform-wide one applies. Over it is `attachment_too_many_pixels`. LinkedIn is why it sits per kind: its image API refuses anything over 36,152,320 px and its video API publishes no pixel rule at all.
|
|
1033
1046
|
* @example 36152320
|
|
1034
1047
|
*/
|
|
1035
1048
|
maxPixels: number | null;
|
|
@@ -1042,14 +1055,14 @@ interface components {
|
|
|
1042
1055
|
*/
|
|
1043
1056
|
maxCount: number | null;
|
|
1044
1057
|
/**
|
|
1045
|
-
* @description Largest ONE video may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment
|
|
1058
|
+
* @description Largest ONE video may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment: a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
|
|
1046
1059
|
* @example 50000000
|
|
1047
1060
|
*/
|
|
1048
1061
|
maxBytes: number | null;
|
|
1049
1062
|
/** @description True when a video may not share a post with a file of any other kind. Mixing them is `attachment_kinds_mixed`. */
|
|
1050
1063
|
alone: boolean;
|
|
1051
1064
|
/**
|
|
1052
|
-
* @description Lowest width ÷ height accepted for a video, where that differs from the platform-wide `minAspectRatio` above
|
|
1065
|
+
* @description Lowest width ÷ height accepted for a video, where that differs from the platform-wide `minAspectRatio` above. It REPLACES that value for this kind rather than narrowing it. Null means the platform-wide one applies. Outside it is `attachment_aspect_unsupported`. Instagram is why: a feed image publishes between 4:5 and 1.91:1 where a video publishes between 0.01:1 and 10:1.
|
|
1053
1066
|
* @example 0.8
|
|
1054
1067
|
*/
|
|
1055
1068
|
minAspectRatio: number | null;
|
|
@@ -1059,7 +1072,7 @@ interface components {
|
|
|
1059
1072
|
*/
|
|
1060
1073
|
maxAspectRatio: number | null;
|
|
1061
1074
|
/**
|
|
1062
|
-
* @description Most pixels ONE video may contain
|
|
1075
|
+
* @description Most pixels ONE video may contain (width × height) where that differs from the platform-wide `maxPixels` above, which it REPLACES for this kind rather than narrowing. Null means the platform-wide one applies. Over it is `attachment_too_many_pixels`. LinkedIn is why it sits per kind: its image API refuses anything over 36,152,320 px and its video API publishes no pixel rule at all.
|
|
1063
1076
|
* @example 36152320
|
|
1064
1077
|
*/
|
|
1065
1078
|
maxPixels: number | null;
|
|
@@ -1072,14 +1085,14 @@ interface components {
|
|
|
1072
1085
|
*/
|
|
1073
1086
|
maxCount: number | null;
|
|
1074
1087
|
/**
|
|
1075
|
-
* @description Largest ONE document may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment
|
|
1088
|
+
* @description Largest ONE document may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment: a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
|
|
1076
1089
|
* @example 50000000
|
|
1077
1090
|
*/
|
|
1078
1091
|
maxBytes: number | null;
|
|
1079
1092
|
/** @description True when a document may not share a post with a file of any other kind. Mixing them is `attachment_kinds_mixed`. */
|
|
1080
1093
|
alone: boolean;
|
|
1081
1094
|
/**
|
|
1082
|
-
* @description Lowest width ÷ height accepted for a document, where that differs from the platform-wide `minAspectRatio` above
|
|
1095
|
+
* @description Lowest width ÷ height accepted for a document, where that differs from the platform-wide `minAspectRatio` above. It REPLACES that value for this kind rather than narrowing it. Null means the platform-wide one applies. Outside it is `attachment_aspect_unsupported`. Instagram is why: a feed image publishes between 4:5 and 1.91:1 where a video publishes between 0.01:1 and 10:1.
|
|
1083
1096
|
* @example 0.8
|
|
1084
1097
|
*/
|
|
1085
1098
|
minAspectRatio: number | null;
|
|
@@ -1089,12 +1102,12 @@ interface components {
|
|
|
1089
1102
|
*/
|
|
1090
1103
|
maxAspectRatio: number | null;
|
|
1091
1104
|
/**
|
|
1092
|
-
* @description Most pixels ONE document may contain
|
|
1105
|
+
* @description Most pixels ONE document may contain (width × height) where that differs from the platform-wide `maxPixels` above, which it REPLACES for this kind rather than narrowing. Null means the platform-wide one applies. Over it is `attachment_too_many_pixels`. LinkedIn is why it sits per kind: its image API refuses anything over 36,152,320 px and its video API publishes no pixel rule at all.
|
|
1093
1106
|
* @example 36152320
|
|
1094
1107
|
*/
|
|
1095
1108
|
maxPixels: number | null;
|
|
1096
1109
|
} | null;
|
|
1097
|
-
/** @description Always null. A subtitle file is a kind the media library stores and never a kind a POST carries, so no platform has a rule about how many of them one may hold. Where a subtitle file reaches a platform is a `media` option
|
|
1110
|
+
/** @description Always null. A subtitle file is a kind the media library stores and never a kind a POST carries, so no platform has a rule about how many of them one may hold. Where a subtitle file reaches a platform is a `media` option (see YouTube’s `captionFile`) whose own `mimeTypes` and `maxBytes` are the rules that bind it. */
|
|
1098
1111
|
caption: {
|
|
1099
1112
|
/**
|
|
1100
1113
|
* @description Most subtitle files one post may carry, where that is tighter than `maxMedia`. Null means only `maxMedia` binds. Over it is `too_many_attachments_of_kind`.
|
|
@@ -1102,14 +1115,14 @@ interface components {
|
|
|
1102
1115
|
*/
|
|
1103
1116
|
maxCount: number | null;
|
|
1104
1117
|
/**
|
|
1105
|
-
* @description Largest ONE subtitle file may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment
|
|
1118
|
+
* @description Largest ONE subtitle file may be, in bytes. Over it is `attachment_too_large`. The only media rule checked on every attachment: a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
|
|
1106
1119
|
* @example 50000000
|
|
1107
1120
|
*/
|
|
1108
1121
|
maxBytes: number | null;
|
|
1109
1122
|
/** @description True when a subtitle file may not share a post with a file of any other kind. Mixing them is `attachment_kinds_mixed`. */
|
|
1110
1123
|
alone: boolean;
|
|
1111
1124
|
/**
|
|
1112
|
-
* @description Lowest width ÷ height accepted for a subtitle file, where that differs from the platform-wide `minAspectRatio` above
|
|
1125
|
+
* @description Lowest width ÷ height accepted for a subtitle file, where that differs from the platform-wide `minAspectRatio` above. It REPLACES that value for this kind rather than narrowing it. Null means the platform-wide one applies. Outside it is `attachment_aspect_unsupported`. Instagram is why: a feed image publishes between 4:5 and 1.91:1 where a video publishes between 0.01:1 and 10:1.
|
|
1113
1126
|
* @example 0.8
|
|
1114
1127
|
*/
|
|
1115
1128
|
minAspectRatio: number | null;
|
|
@@ -1119,14 +1132,14 @@ interface components {
|
|
|
1119
1132
|
*/
|
|
1120
1133
|
maxAspectRatio: number | null;
|
|
1121
1134
|
/**
|
|
1122
|
-
* @description Most pixels ONE subtitle file may contain
|
|
1135
|
+
* @description Most pixels ONE subtitle file may contain (width × height) where that differs from the platform-wide `maxPixels` above, which it REPLACES for this kind rather than narrowing. Null means the platform-wide one applies. Over it is `attachment_too_many_pixels`. LinkedIn is why it sits per kind: its image API refuses anything over 36,152,320 px and its video API publishes no pixel rule at all.
|
|
1123
1136
|
* @example 36152320
|
|
1124
1137
|
*/
|
|
1125
1138
|
maxPixels: number | null;
|
|
1126
1139
|
} | null;
|
|
1127
1140
|
} | null;
|
|
1128
1141
|
/**
|
|
1129
|
-
* @description Rules for one exact MIME type, where the kind above is too coarse
|
|
1142
|
+
* @description Rules for one exact MIME type, where the kind above is too coarse (`null` on a platform that publishes none, which is most of them). Keyed by the mime type as `media.mimeType` reports it. X is why it exists, and it needs every field: X takes "up to 4 photos, 1 animated GIF, or 1 video", where a GIF and a JPEG are both `image`, so the ceiling (15 MB of animation against 5 MB of still), the count and the exclusion are all facts about a type. `maxBytes` REPLACES the kind's ceiling for this file; `maxCount` is counted alongside the kind's cap rather than replacing it, since five images with one GIF among them are five of the kind and one of the type.
|
|
1130
1143
|
* @example {
|
|
1131
1144
|
* "image/jpeg": {
|
|
1132
1145
|
* "maxBytes": 5242880,
|
|
@@ -1154,27 +1167,27 @@ interface components {
|
|
|
1154
1167
|
* @example 1
|
|
1155
1168
|
*/
|
|
1156
1169
|
maxCount: number | null;
|
|
1157
|
-
/** @description True when a file of this type may not share a post with a file of any other type
|
|
1170
|
+
/** @description True when a file of this type may not share a post with a file of any other type, its own kind included, which is what separates it from the per-kind flag. Mixing them is `attachment_types_mixed`. */
|
|
1158
1171
|
alone: boolean;
|
|
1159
1172
|
/**
|
|
1160
|
-
* @description What this platform calls a file of this type in a refusal
|
|
1173
|
+
* @description What this platform calls a file of this type in a refusal: "GIF". Null where the kind name is the right word.
|
|
1161
1174
|
* @example GIF
|
|
1162
1175
|
*/
|
|
1163
1176
|
noun: string | null;
|
|
1164
1177
|
};
|
|
1165
1178
|
} | null;
|
|
1166
1179
|
} | null;
|
|
1167
|
-
/** @description What this platform will change about a post that is ALREADY OUT
|
|
1180
|
+
/** @description What this platform will change about a post that is ALREADY OUT. Send it with `POST /public/v1/posts/{id}/revise`. `null` where a published post is final, which includes every platform that offers no update endpoint at all. Only half the answer: whether a GIVEN channel may use it depends on what its connection was granted, which is `manageStatus` on `GET /public/v1/channels`. */
|
|
1168
1181
|
remoteEdit: {
|
|
1169
|
-
/** @description The parts that change. Attachments are on no platform's list and there is deliberately no member for them: revising cannot change what a post is carrying anywhere. Sending a part that is not listed is `edit_not_supported
|
|
1182
|
+
/** @description The parts that change. Attachments are on no platform's list and there is deliberately no member for them: revising cannot change what a post is carrying anywhere. Sending a part that is not listed is `edit_not_supported`: Reddit rewrites a post's body and never its title. */
|
|
1170
1183
|
fields: ('content' | 'title' | 'options')[];
|
|
1171
|
-
/** @description Milliseconds after publishing during which an edit is still accepted, or `null` for no deadline
|
|
1184
|
+
/** @description Milliseconds after publishing during which an edit is still accepted, or `null` for no deadline, which is every platform today. A revision arriving after it is `edit_window_expired`. */
|
|
1172
1185
|
windowMs: number | null;
|
|
1173
1186
|
} | null;
|
|
1174
|
-
/** @description This platform can take a published post back down, so `POST /public/v1/posts/{id}/retract` reaches it. False means a copy published here is permanent as far as this API is concerned
|
|
1187
|
+
/** @description This platform can take a published post back down, so `POST /public/v1/posts/{id}/retract` reaches it. False means a copy published here is permanent as far as this API is concerned: retracting a submission that includes one deletes our record and reports that channel as one whose copy stays up. */
|
|
1175
1188
|
supportsRemoteDelete: boolean;
|
|
1176
1189
|
};
|
|
1177
|
-
/** @description One submission
|
|
1190
|
+
/** @description One submission: a single thing sent to one or more channels. `id` is the submission, not a per-channel row: each channel publishes independently and carries its own status inside `channels`. */
|
|
1178
1191
|
Post: {
|
|
1179
1192
|
/**
|
|
1180
1193
|
* @description The submission id. Pass this to every `/posts/{id}` route.
|
|
@@ -1200,7 +1213,7 @@ interface components {
|
|
|
1200
1213
|
publishedAt: string | null;
|
|
1201
1214
|
/** @description One entry per target account, in the order they were added. */
|
|
1202
1215
|
channels: components['schemas']['PostChannel'][];
|
|
1203
|
-
/** @description The workspace’s own labels for this submission
|
|
1216
|
+
/** @description The workspace’s own labels for this submission (see `GET /public/v1/tags`). Empty when nothing is tagged. On the submission rather than on a channel, because that is what was tagged: one thing, filed under a word. Never published and never sent to a platform. */
|
|
1204
1217
|
tags: components['schemas']['Tag'][];
|
|
1205
1218
|
/**
|
|
1206
1219
|
* Format: date-time
|
|
@@ -1215,7 +1228,7 @@ interface components {
|
|
|
1215
1228
|
*/
|
|
1216
1229
|
updatedAt: string;
|
|
1217
1230
|
};
|
|
1218
|
-
/** @description One block of a chain
|
|
1231
|
+
/** @description One block of a chain: a tweet in a thread, a LinkedIn post or one of its comments. */
|
|
1219
1232
|
PostBlock: {
|
|
1220
1233
|
/** @description The text of this block. */
|
|
1221
1234
|
content: string;
|
|
@@ -1224,7 +1237,7 @@ interface components {
|
|
|
1224
1237
|
/**
|
|
1225
1238
|
* @description Who this block tags on each attachment, keyed by the media id they are tagged on, holding only the attachments that tag somebody. A map beside `media` rather than a field on each attachment, which is where this differs from `altText`: a description belongs to the file and is resolved onto it, while a tag belongs to this post on this platform. It comes back the way it was sent, so a post read here can be resubmitted verbatim.
|
|
1226
1239
|
* @example {
|
|
1227
|
-
* "
|
|
1240
|
+
* "clx3k2p9q0003abcd1234efgh": [
|
|
1228
1241
|
* {
|
|
1229
1242
|
* "username": "ada",
|
|
1230
1243
|
* "x": 0.25,
|
|
@@ -1241,7 +1254,7 @@ interface components {
|
|
|
1241
1254
|
*/
|
|
1242
1255
|
username: string;
|
|
1243
1256
|
/**
|
|
1244
|
-
* @description Distance from the LEFT edge as a fraction of the width
|
|
1257
|
+
* @description Distance from the LEFT edge as a fraction of the width: 0.5 is the middle, whatever the picture was uploaded at. Not pixels: a fraction is what survives the platform re-encoding the file.
|
|
1245
1258
|
* @example 0.25
|
|
1246
1259
|
*/
|
|
1247
1260
|
x?: number;
|
|
@@ -1261,7 +1274,7 @@ interface components {
|
|
|
1261
1274
|
/** @description One channel’s copy of a submission: its own status and result. */
|
|
1262
1275
|
PostChannel: {
|
|
1263
1276
|
/**
|
|
1264
|
-
* @description The connected account this went to. Null when that account has since been disconnected
|
|
1277
|
+
* @description The connected account this went to. Null when that account has since been disconnected: the publication and its result survive, the link to a live channel does not.
|
|
1265
1278
|
* @example clx3k2p9q0001abcd1234efgh
|
|
1266
1279
|
*/
|
|
1267
1280
|
channelId: string | null;
|
|
@@ -1276,12 +1289,12 @@ interface components {
|
|
|
1276
1289
|
*/
|
|
1277
1290
|
title?: string | null;
|
|
1278
1291
|
/**
|
|
1279
|
-
* @description Which kind of thing this channel published
|
|
1292
|
+
* @description Which kind of thing this channel published: one of the `key`s in that platform’s `postTypes` on `GET /public/v1/platforms`. Null on a platform that publishes a single kind, and null where the submission asked for the default; both read the same way, as the `limits` at the top of that platform.
|
|
1280
1293
|
* @example story
|
|
1281
1294
|
*/
|
|
1282
1295
|
postType?: string | null;
|
|
1283
1296
|
/**
|
|
1284
|
-
* @description What this channel was given for its platform’s own fields
|
|
1297
|
+
* @description What this channel was given for its platform’s own fields: the values sent as `channels[].options`. Always an object, empty where nothing was sent. A value is a string, or an array of them for a field whose `type` on `GET /public/v1/platforms` is `list`; which one a key holds follows that declaration and never varies for a given key.
|
|
1285
1298
|
* @example {
|
|
1286
1299
|
* "link": "https://example.com/recipes/pesto"
|
|
1287
1300
|
* }
|
|
@@ -1321,7 +1334,7 @@ interface components {
|
|
|
1321
1334
|
/**
|
|
1322
1335
|
* @description The platform’s RUNNING counts at that instant, keyed by metric name.
|
|
1323
1336
|
*
|
|
1324
|
-
* AN ABSENT KEY IS NOT A ZERO
|
|
1337
|
+
* AN ABSENT KEY IS NOT A ZERO: it was not reported at this capture, which on most platforms means it is never reported.
|
|
1325
1338
|
*
|
|
1326
1339
|
* Cumulative since the post went out, so a curve only climbs. A value that DROPS between two readings is real and means people undid something.
|
|
1327
1340
|
* @example {
|
|
@@ -1335,7 +1348,7 @@ interface components {
|
|
|
1335
1348
|
};
|
|
1336
1349
|
};
|
|
1337
1350
|
/**
|
|
1338
|
-
* @description One submission’s engagement CURVES, per channel
|
|
1351
|
+
* @description One submission’s engagement CURVES, per channel: the series behind `GET /public/v1/stats`, which only ever sums the latest reading of each publication.
|
|
1339
1352
|
*
|
|
1340
1353
|
* Cumulative and unevenly spaced: sampling decays from roughly hourly to weekly and stops at about thirty days, so plot against `capturedAt` and read an older post as frozen at its last reading rather than as having stopped earning.
|
|
1341
1354
|
*/
|
|
@@ -1346,7 +1359,7 @@ interface components {
|
|
|
1346
1359
|
*/
|
|
1347
1360
|
postId: string;
|
|
1348
1361
|
/**
|
|
1349
|
-
* @description Every metric name appearing anywhere in this response
|
|
1362
|
+
* @description Every metric name appearing anywhere in this response: the union of the per-channel lists, so one legend covers the whole submission. Empty when nothing has been reported for any channel. New names may be ADDED over time; treat an unrecognised one as a number you can display, not as an error.
|
|
1350
1363
|
* @example [
|
|
1351
1364
|
* "impressions",
|
|
1352
1365
|
* "likes",
|
|
@@ -1357,10 +1370,10 @@ interface components {
|
|
|
1357
1370
|
/** @description One entry per channel of the submission, in the same order as `channels` on `GET /public/v1/posts/{id}`. */
|
|
1358
1371
|
channels: components['schemas']['PostMetricsChannel'][];
|
|
1359
1372
|
};
|
|
1360
|
-
/** @description One channel’s curve within the submission. Always present, even with no readings at all
|
|
1373
|
+
/** @description One channel’s curve within the submission. Always present, even with no readings at all: omitting it would be indistinguishable from a channel the submission never went to, and "no readings" is the common case. */
|
|
1361
1374
|
PostMetricsChannel: {
|
|
1362
1375
|
/**
|
|
1363
|
-
* @description The connected account, an id from `GET /public/v1/channels
|
|
1376
|
+
* @description The connected account, an id from `GET /public/v1/channels`, and what to join on for that channel’s `metricsStatus`, which is where the reason for an empty curve lives. Null once the account has been disconnected: the readings survive, the link doesn’t.
|
|
1364
1377
|
* @example clx3k2p9q0001abcd1234efgh
|
|
1365
1378
|
*/
|
|
1366
1379
|
channelId: string | null;
|
|
@@ -1377,18 +1390,18 @@ interface components {
|
|
|
1377
1390
|
* ]
|
|
1378
1391
|
*/
|
|
1379
1392
|
metrics: string[];
|
|
1380
|
-
/** @description Oldest first. Empty when nothing has been sampled for this channel
|
|
1393
|
+
/** @description Oldest first. Empty when nothing has been sampled for this channel: the normal case, not an error. */
|
|
1381
1394
|
readings: components['schemas']['PostMetricReading'][];
|
|
1382
1395
|
};
|
|
1383
1396
|
/** @description A page of submissions, newest first. */
|
|
1384
1397
|
PostPage: {
|
|
1385
1398
|
/** @description The submissions on this page. */
|
|
1386
1399
|
data: components['schemas']['Post'][];
|
|
1387
|
-
/** @description Pass as `?cursor=` to fetch the next page. Null on the last page
|
|
1400
|
+
/** @description Pass as `?cursor=` to fetch the next page. Null on the last page. That, not an empty `data`, is how a client knows to stop. Opaque by contract: do not parse it. */
|
|
1388
1401
|
nextCursor: string | null;
|
|
1389
1402
|
hasMore: boolean;
|
|
1390
1403
|
};
|
|
1391
|
-
/** @description One kind of thing a platform publishes, with the limits that apply when you ask for it. The limits are complete rather than a diff
|
|
1404
|
+
/** @description One kind of thing a platform publishes, with the limits that apply when you ask for it. The limits are complete rather than a diff: a kind of post is a different publication, not a variation on one. */
|
|
1392
1405
|
PostType: {
|
|
1393
1406
|
/**
|
|
1394
1407
|
* @description Send this as `channels[].postType`. Stable; never displayed.
|
|
@@ -1400,7 +1413,7 @@ interface components {
|
|
|
1400
1413
|
* @example Story
|
|
1401
1414
|
*/
|
|
1402
1415
|
label: string;
|
|
1403
|
-
/** @description One sentence about what choosing it means where the limits don't say it
|
|
1416
|
+
/** @description One sentence about what choosing it means where the limits don't say it: that an Instagram Story disappears after 24 hours, for instance. Null where there is nothing to add. */
|
|
1404
1417
|
help: string | null;
|
|
1405
1418
|
limits: components['schemas']['PlatformLimits'];
|
|
1406
1419
|
};
|
|
@@ -1417,79 +1430,84 @@ interface components {
|
|
|
1417
1430
|
RetractResult: {
|
|
1418
1431
|
/** @description Channels whose copy is gone from the platform, and whose record went with it. */
|
|
1419
1432
|
removed: {
|
|
1420
|
-
/** @description The channel, matching `channels[].channelId` on the submission. Null when the account has since been disconnected
|
|
1433
|
+
/** @description The channel, matching `channels[].channelId` on the submission. Null when the account has since been disconnected: the post outlives the connection, and there is then no token to reach it with. */
|
|
1421
1434
|
channelId: string | null;
|
|
1422
1435
|
/**
|
|
1423
1436
|
* @description Its platform. Null for the same reason `channelId` is.
|
|
1424
1437
|
* @enum {string|null}
|
|
1425
1438
|
*/
|
|
1426
1439
|
platform: 'x' | 'linkedin' | 'linkedin_page' | 'instagram' | 'facebook' | 'threads' | 'tiktok' | 'youtube' | 'vimeo' | 'pinterest' | 'bluesky' | 'reddit' | null;
|
|
1427
|
-
/** @description Why this channel is in the list it is in, or null when the takedown succeeded. A sentence for a person to read
|
|
1440
|
+
/** @description Why this channel is in the list it is in, or null when the takedown succeeded. A sentence for a person to read (several of them are the platform's own words), so branch on which LIST the entry is in, never on this text. */
|
|
1428
1441
|
reason: string | null;
|
|
1429
1442
|
}[];
|
|
1430
|
-
/** @description Channels still live, each with a sentence saying why. A non-empty list means the submission still EXISTS, holding exactly these channels
|
|
1443
|
+
/** @description Channels still live, each with a sentence saying why. A non-empty list means the submission still EXISTS, holding exactly these channels, so `GET /posts/{id}` keeps working and calling retract again takes down what is left. */
|
|
1431
1444
|
remaining: {
|
|
1432
|
-
/** @description The channel, matching `channels[].channelId` on the submission. Null when the account has since been disconnected
|
|
1445
|
+
/** @description The channel, matching `channels[].channelId` on the submission. Null when the account has since been disconnected: the post outlives the connection, and there is then no token to reach it with. */
|
|
1433
1446
|
channelId: string | null;
|
|
1434
1447
|
/**
|
|
1435
1448
|
* @description Its platform. Null for the same reason `channelId` is.
|
|
1436
1449
|
* @enum {string|null}
|
|
1437
1450
|
*/
|
|
1438
1451
|
platform: 'x' | 'linkedin' | 'linkedin_page' | 'instagram' | 'facebook' | 'threads' | 'tiktok' | 'youtube' | 'vimeo' | 'pinterest' | 'bluesky' | 'reddit' | null;
|
|
1439
|
-
/** @description Why this channel is in the list it is in, or null when the takedown succeeded. A sentence for a person to read
|
|
1452
|
+
/** @description Why this channel is in the list it is in, or null when the takedown succeeded. A sentence for a person to read (several of them are the platform's own words), so branch on which LIST the entry is in, never on this text. */
|
|
1440
1453
|
reason: string | null;
|
|
1441
1454
|
}[];
|
|
1442
1455
|
};
|
|
1443
1456
|
/** @description One block of the published chain. No attachments: no platform will change what a published post carries. */
|
|
1444
1457
|
RevisePostBlock: {
|
|
1445
|
-
/** @description The block’s new text. Optional and empty is fine
|
|
1458
|
+
/** @description The block’s new text. Optional and empty is fine: clearing the caption on a published image is a real edit. Send the block even when its text has not changed; unchanged blocks are not sent to the platform, so they cost nothing and never mark a post "edited". */
|
|
1446
1459
|
content?: string;
|
|
1447
1460
|
};
|
|
1448
|
-
/** @description One channel’s new wording. Every channel of the submission must appear
|
|
1461
|
+
/** @description One channel’s new wording. Every channel of the submission must appear: what you are describing is how the submission should now read, not a patch against it. */
|
|
1449
1462
|
RevisePostChannel: {
|
|
1450
1463
|
/**
|
|
1451
1464
|
* @description A channel id from `GET /public/v1/channels`.
|
|
1452
1465
|
* @example clx3k2p9q0001abcd1234efgh
|
|
1453
1466
|
*/
|
|
1454
1467
|
channelId: string;
|
|
1455
|
-
/** @description The title, on platforms that have one AND will change it after publishing
|
|
1468
|
+
/** @description The title, on platforms that have one AND will change it after publishing (`limits.remoteEdit.fields` on `GET /public/v1/platforms` says which). YouTube will; Reddit will not, and sending one there is `edit_not_supported` rather than a field quietly ignored. */
|
|
1456
1469
|
title?: string;
|
|
1457
|
-
/**
|
|
1470
|
+
/**
|
|
1471
|
+
* @description The platform’s own fields, where `limits.remoteEdit.fields` includes `options`.
|
|
1472
|
+
* @example {
|
|
1473
|
+
* "link": "https://example.com/recipes/pesto"
|
|
1474
|
+
* }
|
|
1475
|
+
*/
|
|
1458
1476
|
options?: {
|
|
1459
1477
|
[key: string]: string | string[];
|
|
1460
1478
|
};
|
|
1461
|
-
/** @description Every block of the thread, in order, including unchanged ones. The length must equal what was published
|
|
1479
|
+
/** @description Every block of the thread, in order, including unchanged ones. The length must equal what was published: adding or removing a block is `revision_structure_changed`. */
|
|
1462
1480
|
blocks: components['schemas']['RevisePostBlock'][];
|
|
1463
1481
|
};
|
|
1464
|
-
/** @description A revision: the submission as it should now read. Wording only
|
|
1482
|
+
/** @description A revision: the submission as it should now read. Wording only: the channel list and each thread’s length must match what was published, and there is no field for attachments because no platform will change them. */
|
|
1465
1483
|
RevisePostRequest: {
|
|
1466
|
-
/** @description Every channel of the submission. Omitting one is `revision_structure_changed`, not a channel left alone
|
|
1484
|
+
/** @description Every channel of the submission. Omitting one is `revision_structure_changed`, not a channel left alone: call `GET /posts/{id}` and edit what it returns. */
|
|
1467
1485
|
channels: components['schemas']['RevisePostChannel'][];
|
|
1468
1486
|
};
|
|
1469
|
-
/** @description What a revision did, per channel. A refusal the API could see coming
|
|
1487
|
+
/** @description What a revision did, per channel. A refusal the API could see coming (a platform that edits nothing, a field outside its `remoteEdit.fields`, a structural change) is an ERROR instead, because nothing was sent. */
|
|
1470
1488
|
ReviseResult: {
|
|
1471
1489
|
/** @description Channels whose live copy now reads as you sent it. */
|
|
1472
1490
|
revised: {
|
|
1473
|
-
/** @description The channel, matching `channels[].channelId` on the submission. Null when the account has since been disconnected
|
|
1491
|
+
/** @description The channel, matching `channels[].channelId` on the submission. Null when the account has since been disconnected: the post outlives the connection, and there is then no token to reach it with. */
|
|
1474
1492
|
channelId: string | null;
|
|
1475
1493
|
/**
|
|
1476
1494
|
* @description Its platform. Null for the same reason `channelId` is.
|
|
1477
1495
|
* @enum {string|null}
|
|
1478
1496
|
*/
|
|
1479
1497
|
platform: 'x' | 'linkedin' | 'linkedin_page' | 'instagram' | 'facebook' | 'threads' | 'tiktok' | 'youtube' | 'vimeo' | 'pinterest' | 'bluesky' | 'reddit' | null;
|
|
1480
|
-
/** @description Why this channel is in the list it is in, or null when the rewrite succeeded. A sentence for a person to read
|
|
1498
|
+
/** @description Why this channel is in the list it is in, or null when the rewrite succeeded. A sentence for a person to read (several of them are the platform's own words), so branch on which LIST the entry is in, never on this text. */
|
|
1481
1499
|
reason: string | null;
|
|
1482
1500
|
}[];
|
|
1483
|
-
/** @description Channels that were not rewritten. `reason` tells the two cases apart: null means there was nothing to send
|
|
1501
|
+
/** @description Channels that were not rewritten. `reason` tells the two cases apart: null means there was nothing to send (the text already matched) and a sentence means the platform refused. They share a list because the common case is a submission where one channel was fixed and the rest were left alone, which is not a partial failure. */
|
|
1484
1502
|
unchanged: {
|
|
1485
|
-
/** @description The channel, matching `channels[].channelId` on the submission. Null when the account has since been disconnected
|
|
1503
|
+
/** @description The channel, matching `channels[].channelId` on the submission. Null when the account has since been disconnected: the post outlives the connection, and there is then no token to reach it with. */
|
|
1486
1504
|
channelId: string | null;
|
|
1487
1505
|
/**
|
|
1488
1506
|
* @description Its platform. Null for the same reason `channelId` is.
|
|
1489
1507
|
* @enum {string|null}
|
|
1490
1508
|
*/
|
|
1491
1509
|
platform: 'x' | 'linkedin' | 'linkedin_page' | 'instagram' | 'facebook' | 'threads' | 'tiktok' | 'youtube' | 'vimeo' | 'pinterest' | 'bluesky' | 'reddit' | null;
|
|
1492
|
-
/** @description Why this channel is in the list it is in, or null when the rewrite succeeded. A sentence for a person to read
|
|
1510
|
+
/** @description Why this channel is in the list it is in, or null when the rewrite succeeded. A sentence for a person to read (several of them are the platform's own words), so branch on which LIST the entry is in, never on this text. */
|
|
1493
1511
|
reason: string | null;
|
|
1494
1512
|
}[];
|
|
1495
1513
|
};
|
|
@@ -1533,14 +1551,14 @@ interface components {
|
|
|
1533
1551
|
*/
|
|
1534
1552
|
to: string;
|
|
1535
1553
|
/**
|
|
1536
|
-
* @description The IANA zone `daily[].date` was bucketed in
|
|
1554
|
+
* @description The IANA zone `daily[].date` was bucketed in: the one requested, or `UTC`. Echoed because a day boundary is the whole meaning of a daily series: the same publication falls on different dates in different zones.
|
|
1537
1555
|
* @example UTC
|
|
1538
1556
|
*/
|
|
1539
1557
|
timezone: string;
|
|
1540
1558
|
totals: components['schemas']['StatsTotals'];
|
|
1541
1559
|
engagement: components['schemas']['StatsEngagementTotals'];
|
|
1542
1560
|
/**
|
|
1543
|
-
* @description Metric names appearing anywhere in this response, in a stable render order. Empty when nothing was measured
|
|
1561
|
+
* @description Metric names appearing anywhere in this response, in a stable render order. Empty when nothing was measured, which is how you tell "no engagement reported" from "this API has no engagement". New names may be ADDED over time; treat an unrecognised one as a number you can display, not as an error.
|
|
1544
1562
|
* @example [
|
|
1545
1563
|
* "impressions",
|
|
1546
1564
|
* "likes",
|
|
@@ -1552,15 +1570,15 @@ interface components {
|
|
|
1552
1570
|
queue: components['schemas']['StatsQueue'];
|
|
1553
1571
|
/** @description One entry per day in the window, zero-filled and ascending. */
|
|
1554
1572
|
daily: components['schemas']['StatsDay'][];
|
|
1555
|
-
/** @description Busiest first. Every channel connected right now appears, including those that published nothing
|
|
1573
|
+
/** @description Busiest first. Every channel connected right now appears, including those that published nothing: a silent account is a finding, not an absence. */
|
|
1556
1574
|
channels: components['schemas']['StatsChannel'][];
|
|
1557
|
-
/** @description Busiest first, and only tags something landed under
|
|
1575
|
+
/** @description Busiest first, and only tags something landed under: unlike `channels`, an unused label is omitted. These figures OVERLAP and do not partition `totals`: a publication carrying two tags is counted under both, one carrying none under neither. Do not render them as shares of a whole. */
|
|
1558
1576
|
tags: components['schemas']['StatsTag'][];
|
|
1559
1577
|
};
|
|
1560
1578
|
/** @description One connected account's share of the window. */
|
|
1561
1579
|
StatsChannel: {
|
|
1562
1580
|
/**
|
|
1563
|
-
* @description The connected account, an id from `GET /public/v1/channels`. Null on the single row collecting publications whose account has since been disconnected
|
|
1581
|
+
* @description The connected account, an id from `GET /public/v1/channels`. Null on the single row collecting publications whose account has since been disconnected, which is what keeps these figures summing to `totals`.
|
|
1564
1582
|
* @example clx3k2p9q0001abcd1234efgh
|
|
1565
1583
|
*/
|
|
1566
1584
|
channelId: string | null;
|
|
@@ -1576,7 +1594,7 @@ interface components {
|
|
|
1576
1594
|
/**
|
|
1577
1595
|
* @description One calendar day of the window.
|
|
1578
1596
|
*
|
|
1579
|
-
* `engagement` here is what the posts published ON THIS DAY have earned, counted since each went out and still moving
|
|
1597
|
+
* `engagement` here is what the posts published ON THIS DAY have earned, counted since each went out and still moving, NOT engagement earned on this day. The two are easy to confuse into a chart that is wrong in a way nobody can see; the second is not derivable from cumulative readings and this API does not offer it.
|
|
1580
1598
|
*
|
|
1581
1599
|
* Days PARTITION the window, so unlike `tags` these do sum to the response-level `engagement`.
|
|
1582
1600
|
*/
|
|
@@ -1594,11 +1612,11 @@ interface components {
|
|
|
1594
1612
|
/** @description What one bucket's publications EARNED, read back from the platforms. */
|
|
1595
1613
|
StatsEngagement: {
|
|
1596
1614
|
/**
|
|
1597
|
-
* @description Summed cumulative counts keyed by metric name
|
|
1615
|
+
* @description Summed cumulative counts keyed by metric name: the names listed in `metrics` on the response.
|
|
1598
1616
|
*
|
|
1599
1617
|
* AN ABSENT KEY IS NOT A ZERO. It means no publication in this bucket reported that metric: either its platform does not measure it, or the platform reports no engagement to this API at all. Rendering a missing key as `0` states a fact about engagement that nothing measured.
|
|
1600
1618
|
*
|
|
1601
|
-
* Every value is the LATEST reading of each publication, summed
|
|
1619
|
+
* Every value is the LATEST reading of each publication, summed: cumulative since the post went out, not earned during the window.
|
|
1602
1620
|
* @example {
|
|
1603
1621
|
* "likes": 412,
|
|
1604
1622
|
* "comments": 37,
|
|
@@ -1608,17 +1626,17 @@ interface components {
|
|
|
1608
1626
|
values: {
|
|
1609
1627
|
[key: string]: number;
|
|
1610
1628
|
};
|
|
1611
|
-
/** @description Publications in this bucket carrying any reading at all
|
|
1629
|
+
/** @description Publications in this bucket carrying any reading at all: the denominator. Compare it against the bucket’s `published` before presenting any figure in `values` as a fact about the whole bucket. */
|
|
1612
1630
|
measured: number;
|
|
1613
1631
|
};
|
|
1614
|
-
/** @description Engagement for the whole window, with per-metric coverage. Summed across CHANNELS, which partition the window
|
|
1632
|
+
/** @description Engagement for the whole window, with per-metric coverage. Summed across CHANNELS, which partition the window, never across tags, which overlap. */
|
|
1615
1633
|
StatsEngagementTotals: {
|
|
1616
1634
|
/**
|
|
1617
|
-
* @description Summed cumulative counts keyed by metric name
|
|
1635
|
+
* @description Summed cumulative counts keyed by metric name: the names listed in `metrics` on the response.
|
|
1618
1636
|
*
|
|
1619
1637
|
* AN ABSENT KEY IS NOT A ZERO. It means no publication in this bucket reported that metric: either its platform does not measure it, or the platform reports no engagement to this API at all. Rendering a missing key as `0` states a fact about engagement that nothing measured.
|
|
1620
1638
|
*
|
|
1621
|
-
* Every value is the LATEST reading of each publication, summed
|
|
1639
|
+
* Every value is the LATEST reading of each publication, summed: cumulative since the post went out, not earned during the window.
|
|
1622
1640
|
* @example {
|
|
1623
1641
|
* "likes": 412,
|
|
1624
1642
|
* "comments": 37,
|
|
@@ -1676,14 +1694,14 @@ interface components {
|
|
|
1676
1694
|
/** @description Busiest first. OVERLAPPING: a post with two tags is in both, and an untagged post in none. */
|
|
1677
1695
|
tags: components['schemas']['InsightTag'][];
|
|
1678
1696
|
};
|
|
1679
|
-
/** @description A snapshot of RIGHT NOW. Unaffected by `from`/`to
|
|
1697
|
+
/** @description A snapshot of RIGHT NOW. Unaffected by `from`/`to`: mixing pending work into a window total would produce a number meaning two things at once. */
|
|
1680
1698
|
StatsQueue: {
|
|
1681
1699
|
/** @description Publications scheduled ahead of now, including any mid-flight. */
|
|
1682
1700
|
scheduled: number;
|
|
1683
1701
|
/** @description Drafts held in the workspace, at any age. */
|
|
1684
1702
|
drafts: number;
|
|
1685
1703
|
};
|
|
1686
|
-
/** @description One tag's share of the window. Overlapping rather than a partition
|
|
1704
|
+
/** @description One tag's share of the window. Overlapping rather than a partition (see the field description on Stats). */
|
|
1687
1705
|
StatsTag: {
|
|
1688
1706
|
/**
|
|
1689
1707
|
* @description A tag id from `GET /public/v1/tags`.
|
|
@@ -1704,7 +1722,7 @@ interface components {
|
|
|
1704
1722
|
/** @description A workspace’s own label for a submission. Ours, not any platform’s: a tag is not a hashtag, is never published, and no provider is told it exists. */
|
|
1705
1723
|
Tag: {
|
|
1706
1724
|
/**
|
|
1707
|
-
* @description Use this in `tagIds` when creating a submission, and as `?tag=` when listing them. Address tags by id, never by name
|
|
1725
|
+
* @description Use this in `tagIds` when creating a submission, and as `?tag=` when listing them. Address tags by id, never by name: the name is the field a workspace edits.
|
|
1708
1726
|
* @example clx3k2p9q0001abcd1234efgh
|
|
1709
1727
|
*/
|
|
1710
1728
|
id: string;
|
|
@@ -1724,7 +1742,7 @@ interface components {
|
|
|
1724
1742
|
*/
|
|
1725
1743
|
postCount: number;
|
|
1726
1744
|
};
|
|
1727
|
-
/** @description Only the fields you send are changed
|
|
1745
|
+
/** @description Only the fields you send are changed: a partial update, despite the PUT. An endpoint has no parts to reconcile, so there is no half-state a partial body could leave behind. */
|
|
1728
1746
|
UpdateWebhookRequest: {
|
|
1729
1747
|
/**
|
|
1730
1748
|
* Format: uri
|
|
@@ -1740,11 +1758,11 @@ interface components {
|
|
|
1740
1758
|
UploadMediaRequest: {
|
|
1741
1759
|
/**
|
|
1742
1760
|
* Format: binary
|
|
1743
|
-
* @description JPEG, PNG, WebP, GIF, MP4, MOV, PDF, VTT or SRT. Images up to 10 MB, video and PDFs up to 100 MB, subtitle files up to 5 MB. A larger video, up to the plan’s video cap, goes through `POST /media/uploads` instead. Not every platform publishes every type
|
|
1761
|
+
* @description JPEG, PNG, WebP, GIF, MP4, MOV, PDF, VTT or SRT. Images up to 10 MB, video and PDFs up to 100 MB, subtitle files up to 5 MB. A larger video, up to the plan’s video cap, goes through `POST /media/uploads` instead. Not every platform publishes every type: check `acceptedMimeTypes` on `GET /platforms`, where a PDF appears only for the platforms that publish a document post, and where a subtitle file appears on none: it is never an attachment, and reaches a platform through a `media` option instead (see YouTube’s `captionFile`). The bytes are proxied through the API rather than handed a presigned bucket URL, so the server sees the real content and a file whose bytes disagree with its declared type is rejected. A subtitle file sent as `application/octet-stream` (which is what an unconfigured client sends, since no system registers a type for `.srt`) is read from the filename’s extension instead, and then verified like everything else.
|
|
1744
1762
|
*/
|
|
1745
1763
|
file: string;
|
|
1746
1764
|
};
|
|
1747
|
-
/** @description Consumption against the plan, for the whole ACCOUNT this workspace belongs to
|
|
1765
|
+
/** @description Consumption against the plan, for the whole ACCOUNT this workspace belongs to: a plan is bought once and every workspace its owner owns draws from one pool. These are the same events an invoice is computed from; a usage endpoint that disagreed with the bill would be worse than none. */
|
|
1748
1766
|
Usage: {
|
|
1749
1767
|
/**
|
|
1750
1768
|
* @description The tier the account behind this workspace is on.
|
|
@@ -1759,15 +1777,17 @@ interface components {
|
|
|
1759
1777
|
periodStart: string;
|
|
1760
1778
|
/**
|
|
1761
1779
|
* Format: date-time
|
|
1762
|
-
* @description EXCLUSIVE end
|
|
1780
|
+
* @description EXCLUSIVE end: the instant the period figures reset.
|
|
1763
1781
|
* @example 2026-08-04T09:30:00.000Z
|
|
1764
1782
|
*/
|
|
1765
1783
|
periodEnd: string;
|
|
1766
|
-
/** @description Two figures because they answer different questions. `created` is what
|
|
1784
|
+
/** @description Two figures because they answer different questions. `created` is what a hard cap is enforced against: posts published this period plus posts still waiting to publish, so a deleted or failed post gives its place back. Only a trial, or an account whose last payment failed, has a cap; `limit` is null otherwise. `published` is what a bill is computed from. */
|
|
1767
1785
|
posts: {
|
|
1768
1786
|
created: components['schemas']['UsageMetric'];
|
|
1769
|
-
/** @description The billable figure:
|
|
1787
|
+
/** @description The billable figure: posts and comment replies that actually reached a platform this billing period. */
|
|
1770
1788
|
published: number;
|
|
1789
|
+
/** @description How many published actions the plan includes this period. Each one past it is billed per action, not refused. Null when nothing is metered. */
|
|
1790
|
+
included: number | null;
|
|
1771
1791
|
};
|
|
1772
1792
|
channels: components['schemas']['UsageMetric'];
|
|
1773
1793
|
storage: {
|
|
@@ -1778,7 +1798,7 @@ interface components {
|
|
|
1778
1798
|
/** @description One metered resource: what has been used, and the ceiling. */
|
|
1779
1799
|
UsageMetric: {
|
|
1780
1800
|
used: number;
|
|
1781
|
-
/** @description Null means unlimited
|
|
1801
|
+
/** @description Null means unlimited, not "unknown", and not a large number. */
|
|
1782
1802
|
limit: number | null;
|
|
1783
1803
|
};
|
|
1784
1804
|
/** @description The `data` of a `channel.needs_reconnect` event. */
|
|
@@ -1798,7 +1818,7 @@ interface components {
|
|
|
1798
1818
|
*/
|
|
1799
1819
|
id: string;
|
|
1800
1820
|
/**
|
|
1801
|
-
* @description The event. Stable across every redelivery
|
|
1821
|
+
* @description The event. Stable across every redelivery: this is what a subscriber dedupes on, and it is also the `id` in the body and the `X-Bulkit-Event-Id` header.
|
|
1802
1822
|
* @example clx3k2p9q0001abcd1234efgh
|
|
1803
1823
|
*/
|
|
1804
1824
|
eventId: string;
|
|
@@ -1813,16 +1833,16 @@ interface components {
|
|
|
1813
1833
|
*/
|
|
1814
1834
|
endpointId: string;
|
|
1815
1835
|
/**
|
|
1816
|
-
* @description `pending
|
|
1836
|
+
* @description `pending`: not accepted yet, and may still be retried. `succeeded`: your server returned a 2xx. `failed`: the retry budget is spent and nothing further will be attempted.
|
|
1817
1837
|
* @enum {string}
|
|
1818
1838
|
*/
|
|
1819
1839
|
status: 'pending' | 'succeeded' | 'failed';
|
|
1820
1840
|
/** @description How many times we have sent it. */
|
|
1821
1841
|
attempts: number;
|
|
1822
|
-
/** @description Your server’s HTTP status on the last attempt. Null when we never got one
|
|
1842
|
+
/** @description Your server’s HTTP status on the last attempt. Null when we never got one: DNS, TLS, refused, timed out. Your response BODY is never stored or returned. */
|
|
1823
1843
|
responseStatus: number | null;
|
|
1824
1844
|
/**
|
|
1825
|
-
* @description Why the last attempt failed, in OUR words
|
|
1845
|
+
* @description Why the last attempt failed, in OUR words, never anything your server sent back.
|
|
1826
1846
|
* @example No response within 10s
|
|
1827
1847
|
*/
|
|
1828
1848
|
error: string | null;
|
|
@@ -1849,7 +1869,7 @@ interface components {
|
|
|
1849
1869
|
nextCursor: string | null;
|
|
1850
1870
|
hasMore: boolean;
|
|
1851
1871
|
};
|
|
1852
|
-
/** @description A registered destination for events. The signing secret is deliberately absent
|
|
1872
|
+
/** @description A registered destination for events. The signing secret is deliberately absent: it is returned only when the endpoint is created or its secret is rolled, and no route reads it back. */
|
|
1853
1873
|
WebhookEndpoint: {
|
|
1854
1874
|
/**
|
|
1855
1875
|
* @description The endpoint id.
|
|
@@ -1867,11 +1887,11 @@ interface components {
|
|
|
1867
1887
|
/** @description What this endpoint receives. Never empty. */
|
|
1868
1888
|
events: ('post.published' | 'post.failed' | 'post.partially_failed' | 'channel.needs_reconnect')[];
|
|
1869
1889
|
/**
|
|
1870
|
-
* @description `disabled` means nothing is being delivered
|
|
1890
|
+
* @description `disabled` means nothing is being delivered: either you switched it off, or we did after repeated failures. `disabledReason` tells them apart.
|
|
1871
1891
|
* @enum {string}
|
|
1872
1892
|
*/
|
|
1873
1893
|
status: 'enabled' | 'disabled';
|
|
1874
|
-
/** @description Why WE stopped delivering. Null while enabled, and null when you disabled it yourself
|
|
1894
|
+
/** @description Why WE stopped delivering. Null while enabled, and null when you disabled it yourself; that needs no explanation from us. */
|
|
1875
1895
|
disabledReason: string | null;
|
|
1876
1896
|
/**
|
|
1877
1897
|
* Format: date-time
|
|
@@ -1879,7 +1899,7 @@ interface components {
|
|
|
1879
1899
|
* @example 2026-08-04T09:30:00.000Z
|
|
1880
1900
|
*/
|
|
1881
1901
|
disabledAt: string | null;
|
|
1882
|
-
/** @description Last 4 characters of the signing secret currently in force
|
|
1902
|
+
/** @description Last 4 characters of the signing secret currently in force: enough to tell which secret a receiver is configured with, after the one time it was shown. */
|
|
1883
1903
|
secretLast4: string;
|
|
1884
1904
|
/**
|
|
1885
1905
|
* Format: date-time
|
|
@@ -1894,7 +1914,7 @@ interface components {
|
|
|
1894
1914
|
*/
|
|
1895
1915
|
updatedAt: string;
|
|
1896
1916
|
};
|
|
1897
|
-
/** @description The body POSTed to your endpoint. Documented here for reference
|
|
1917
|
+
/** @description The body POSTed to your endpoint. Documented here for reference: no operation on this API returns it. */
|
|
1898
1918
|
WebhookEvent: {
|
|
1899
1919
|
/**
|
|
1900
1920
|
* @description The event id, stable across every redelivery. Dedupe on this: delivery is at-least-once, so a receiver that 200s after its own timeout will be sent the same event again.
|
|
@@ -1908,7 +1928,7 @@ interface components {
|
|
|
1908
1928
|
type: 'post.published' | 'post.failed' | 'post.partially_failed' | 'channel.needs_reconnect';
|
|
1909
1929
|
/**
|
|
1910
1930
|
* Format: date-time
|
|
1911
|
-
* @description When the fact became true
|
|
1931
|
+
* @description When the fact became true, not when this attempt was sent.
|
|
1912
1932
|
* @example 2026-08-04T09:30:00.000Z
|
|
1913
1933
|
*/
|
|
1914
1934
|
createdAt: string;
|
|
@@ -1918,7 +1938,7 @@ interface components {
|
|
|
1918
1938
|
/** @description The `data` of a `post.*` event. The whole submission travels with it, in the shape `GET /posts/{id}` returns, so an ordinary subscriber never has to call back. */
|
|
1919
1939
|
WebhookPostData: {
|
|
1920
1940
|
post: components['schemas']['Post'];
|
|
1921
|
-
/** @description The channel this event is about. `post.*` events fire ONCE PER CHANNEL
|
|
1941
|
+
/** @description The channel this event is about. `post.*` events fire ONCE PER CHANNEL: each channel of a submission publishes independently, with its own status and its own retry, so there is no single moment at which "the submission" published. */
|
|
1922
1942
|
channelId: string | null;
|
|
1923
1943
|
/**
|
|
1924
1944
|
* @description That channel’s platform.
|
|
@@ -1984,7 +2004,7 @@ interface operations {
|
|
|
1984
2004
|
'application/json': components['schemas']['Error'];
|
|
1985
2005
|
};
|
|
1986
2006
|
};
|
|
1987
|
-
/** @description Too fast. RETRYABLE
|
|
2007
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
1988
2008
|
429: {
|
|
1989
2009
|
headers: {
|
|
1990
2010
|
/** @description Seconds to wait before retrying. */
|
|
@@ -2012,7 +2032,7 @@ interface operations {
|
|
|
2012
2032
|
'application/json': components['schemas']['Error'];
|
|
2013
2033
|
};
|
|
2014
2034
|
};
|
|
2015
|
-
/** @description `service_unavailable
|
|
2035
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
2016
2036
|
503: {
|
|
2017
2037
|
headers: {
|
|
2018
2038
|
[name: string]: unknown;
|
|
@@ -2080,7 +2100,7 @@ interface operations {
|
|
|
2080
2100
|
'application/json': components['schemas']['Error'];
|
|
2081
2101
|
};
|
|
2082
2102
|
};
|
|
2083
|
-
/** @description Too fast. RETRYABLE
|
|
2103
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
2084
2104
|
429: {
|
|
2085
2105
|
headers: {
|
|
2086
2106
|
/** @description Seconds to wait before retrying. */
|
|
@@ -2117,7 +2137,7 @@ interface operations {
|
|
|
2117
2137
|
'application/json': components['schemas']['Error'];
|
|
2118
2138
|
};
|
|
2119
2139
|
};
|
|
2120
|
-
/** @description `service_unavailable
|
|
2140
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
2121
2141
|
503: {
|
|
2122
2142
|
headers: {
|
|
2123
2143
|
[name: string]: unknown;
|
|
@@ -2201,7 +2221,7 @@ interface operations {
|
|
|
2201
2221
|
'application/json': components['schemas']['Error'];
|
|
2202
2222
|
};
|
|
2203
2223
|
};
|
|
2204
|
-
/** @description Too fast. RETRYABLE
|
|
2224
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
2205
2225
|
429: {
|
|
2206
2226
|
headers: {
|
|
2207
2227
|
/** @description Seconds to wait before retrying. */
|
|
@@ -2238,7 +2258,7 @@ interface operations {
|
|
|
2238
2258
|
'application/json': components['schemas']['Error'];
|
|
2239
2259
|
};
|
|
2240
2260
|
};
|
|
2241
|
-
/** @description `service_unavailable
|
|
2261
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
2242
2262
|
503: {
|
|
2243
2263
|
headers: {
|
|
2244
2264
|
[name: string]: unknown;
|
|
@@ -2251,20 +2271,34 @@ interface operations {
|
|
|
2251
2271
|
};
|
|
2252
2272
|
PublicMediaController_list: {
|
|
2253
2273
|
parameters: {
|
|
2254
|
-
query?:
|
|
2274
|
+
query?: {
|
|
2275
|
+
/** @description The previous page’s `nextCursor`. Opaque: a value we did not issue is rejected rather than silently restarting at page one. */
|
|
2276
|
+
cursor?: unknown;
|
|
2277
|
+
/** @description Page size. Clamped to 100; asking for more is not an error. */
|
|
2278
|
+
limit?: number;
|
|
2279
|
+
};
|
|
2255
2280
|
header?: never;
|
|
2256
2281
|
path?: never;
|
|
2257
2282
|
cookie?: never;
|
|
2258
2283
|
};
|
|
2259
2284
|
requestBody?: never;
|
|
2260
2285
|
responses: {
|
|
2261
|
-
/** @description
|
|
2286
|
+
/** @description A page of the organization’s library. */
|
|
2262
2287
|
200: {
|
|
2263
2288
|
headers: {
|
|
2264
2289
|
[name: string]: unknown;
|
|
2265
2290
|
};
|
|
2266
2291
|
content: {
|
|
2267
|
-
'application/json': components['schemas']['
|
|
2292
|
+
'application/json': components['schemas']['MediaPage'];
|
|
2293
|
+
};
|
|
2294
|
+
};
|
|
2295
|
+
/** @description The request is malformed, or a platform rule rejects it. `error.field` points at the part of the body that caused it, and `error.details` lists every field when validation rejected more than one. */
|
|
2296
|
+
400: {
|
|
2297
|
+
headers: {
|
|
2298
|
+
[name: string]: unknown;
|
|
2299
|
+
};
|
|
2300
|
+
content: {
|
|
2301
|
+
'application/json': components['schemas']['Error'];
|
|
2268
2302
|
};
|
|
2269
2303
|
};
|
|
2270
2304
|
/** @description No API key was presented, or the one presented is unknown, revoked or expired. Presented-but-rejected and never-presented are told apart in `error.message`; *why* a presented key failed is deliberately not. */
|
|
@@ -2276,7 +2310,7 @@ interface operations {
|
|
|
2276
2310
|
'application/json': components['schemas']['Error'];
|
|
2277
2311
|
};
|
|
2278
2312
|
};
|
|
2279
|
-
/** @description Too fast. RETRYABLE
|
|
2313
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
2280
2314
|
429: {
|
|
2281
2315
|
headers: {
|
|
2282
2316
|
/** @description Seconds to wait before retrying. */
|
|
@@ -2304,7 +2338,7 @@ interface operations {
|
|
|
2304
2338
|
'application/json': components['schemas']['Error'];
|
|
2305
2339
|
};
|
|
2306
2340
|
};
|
|
2307
|
-
/** @description `service_unavailable
|
|
2341
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
2308
2342
|
503: {
|
|
2309
2343
|
headers: {
|
|
2310
2344
|
[name: string]: unknown;
|
|
@@ -2355,7 +2389,7 @@ interface operations {
|
|
|
2355
2389
|
'application/json': components['schemas']['Error'];
|
|
2356
2390
|
};
|
|
2357
2391
|
};
|
|
2358
|
-
/** @description The plan’s allowance for this period is spent (`quota_exceeded`). NOT retryable
|
|
2392
|
+
/** @description The plan’s allowance for this period is spent (`quota_exceeded`). NOT retryable: nothing about your request timing will help, and the limit resets at `periodEnd` from `GET /public/v1/usage`. Distinct from 429 on purpose. */
|
|
2359
2393
|
402: {
|
|
2360
2394
|
headers: {
|
|
2361
2395
|
[name: string]: unknown;
|
|
@@ -2373,7 +2407,7 @@ interface operations {
|
|
|
2373
2407
|
'application/json': components['schemas']['Error'];
|
|
2374
2408
|
};
|
|
2375
2409
|
};
|
|
2376
|
-
/** @description `payload_too_large
|
|
2410
|
+
/** @description `payload_too_large`: an upload past the per-kind ceiling (10 MB for images, 100 MB for video and documents, 5 MB for subtitle files), or a JSON body past the one a request may carry. A larger video goes through `POST /media/uploads`, where the ceiling is the plan’s video cap instead and going over it is a 402. A limit on the resource, not on the plan: a bigger plan does not raise it. */
|
|
2377
2411
|
413: {
|
|
2378
2412
|
headers: {
|
|
2379
2413
|
[name: string]: unknown;
|
|
@@ -2382,7 +2416,7 @@ interface operations {
|
|
|
2382
2416
|
'application/json': components['schemas']['Error'];
|
|
2383
2417
|
};
|
|
2384
2418
|
};
|
|
2385
|
-
/** @description `unsupported_media_type
|
|
2419
|
+
/** @description `unsupported_media_type`: that file type is not something any supported platform can publish. Accepting it would upload cleanly and then fail at publish, which is the failure this refusal exists to prevent. */
|
|
2386
2420
|
415: {
|
|
2387
2421
|
headers: {
|
|
2388
2422
|
[name: string]: unknown;
|
|
@@ -2391,7 +2425,7 @@ interface operations {
|
|
|
2391
2425
|
'application/json': components['schemas']['Error'];
|
|
2392
2426
|
};
|
|
2393
2427
|
};
|
|
2394
|
-
/** @description Too fast. RETRYABLE
|
|
2428
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
2395
2429
|
429: {
|
|
2396
2430
|
headers: {
|
|
2397
2431
|
/** @description Seconds to wait before retrying. */
|
|
@@ -2419,7 +2453,7 @@ interface operations {
|
|
|
2419
2453
|
'application/json': components['schemas']['Error'];
|
|
2420
2454
|
};
|
|
2421
2455
|
};
|
|
2422
|
-
/** @description `service_unavailable
|
|
2456
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
2423
2457
|
503: {
|
|
2424
2458
|
headers: {
|
|
2425
2459
|
[name: string]: unknown;
|
|
@@ -2435,11 +2469,11 @@ interface operations {
|
|
|
2435
2469
|
query?: never;
|
|
2436
2470
|
header?: {
|
|
2437
2471
|
/**
|
|
2438
|
-
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice
|
|
2472
|
+
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice. Without it, a client that times out and retries schedules the post a second time, and the first is already queued.
|
|
2439
2473
|
*
|
|
2440
2474
|
* Any string up to 255 characters; a UUID per logical operation is the usual choice. Keys are scoped to your workspace and honoured for 24 hours. The same key on a different route or id, or with a different body, is a `422`; a request still running under this key is a `409 request_in_progress`.
|
|
2441
2475
|
*
|
|
2442
|
-
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it
|
|
2476
|
+
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it: every one of them is raised before we write a thing, so fix the input and retry with the same key. A `5xx` pins it, and the retry replays that failure instead of doing the work: a write is several posts and several workflows, so a fault partway through leaves some of them done, and a fresh attempt would publish those a second time. Read `GET /posts/{id}` to see what exists, then continue with a new key.
|
|
2443
2477
|
*/
|
|
2444
2478
|
'Idempotency-Key'?: string;
|
|
2445
2479
|
};
|
|
@@ -2479,7 +2513,7 @@ interface operations {
|
|
|
2479
2513
|
'application/json': components['schemas']['Error'];
|
|
2480
2514
|
};
|
|
2481
2515
|
};
|
|
2482
|
-
/** @description The plan’s allowance for this period is spent (`quota_exceeded`). NOT retryable
|
|
2516
|
+
/** @description The plan’s allowance for this period is spent (`quota_exceeded`). NOT retryable: nothing about your request timing will help, and the limit resets at `periodEnd` from `GET /public/v1/usage`. Distinct from 429 on purpose. */
|
|
2483
2517
|
402: {
|
|
2484
2518
|
headers: {
|
|
2485
2519
|
[name: string]: unknown;
|
|
@@ -2497,7 +2531,7 @@ interface operations {
|
|
|
2497
2531
|
'application/json': components['schemas']['Error'];
|
|
2498
2532
|
};
|
|
2499
2533
|
};
|
|
2500
|
-
/** @description `payload_too_large
|
|
2534
|
+
/** @description `payload_too_large`: an upload past the per-kind ceiling (10 MB for images, 100 MB for video and documents, 5 MB for subtitle files), or a JSON body past the one a request may carry. A larger video goes through `POST /media/uploads`, where the ceiling is the plan’s video cap instead and going over it is a 402. A limit on the resource, not on the plan: a bigger plan does not raise it. */
|
|
2501
2535
|
413: {
|
|
2502
2536
|
headers: {
|
|
2503
2537
|
[name: string]: unknown;
|
|
@@ -2506,7 +2540,7 @@ interface operations {
|
|
|
2506
2540
|
'application/json': components['schemas']['Error'];
|
|
2507
2541
|
};
|
|
2508
2542
|
};
|
|
2509
|
-
/** @description `unsupported_media_type
|
|
2543
|
+
/** @description `unsupported_media_type`: that file type is not something any supported platform can publish. Accepting it would upload cleanly and then fail at publish, which is the failure this refusal exists to prevent. */
|
|
2510
2544
|
415: {
|
|
2511
2545
|
headers: {
|
|
2512
2546
|
[name: string]: unknown;
|
|
@@ -2524,7 +2558,7 @@ interface operations {
|
|
|
2524
2558
|
'application/json': components['schemas']['Error'];
|
|
2525
2559
|
};
|
|
2526
2560
|
};
|
|
2527
|
-
/** @description Too fast. RETRYABLE
|
|
2561
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
2528
2562
|
429: {
|
|
2529
2563
|
headers: {
|
|
2530
2564
|
/** @description Seconds to wait before retrying. */
|
|
@@ -2552,7 +2586,7 @@ interface operations {
|
|
|
2552
2586
|
'application/json': components['schemas']['Error'];
|
|
2553
2587
|
};
|
|
2554
2588
|
};
|
|
2555
|
-
/** @description `service_unavailable
|
|
2589
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
2556
2590
|
503: {
|
|
2557
2591
|
headers: {
|
|
2558
2592
|
[name: string]: unknown;
|
|
@@ -2609,7 +2643,7 @@ interface operations {
|
|
|
2609
2643
|
'application/json': components['schemas']['Error'];
|
|
2610
2644
|
};
|
|
2611
2645
|
};
|
|
2612
|
-
/** @description Too fast. RETRYABLE
|
|
2646
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
2613
2647
|
429: {
|
|
2614
2648
|
headers: {
|
|
2615
2649
|
/** @description Seconds to wait before retrying. */
|
|
@@ -2637,7 +2671,7 @@ interface operations {
|
|
|
2637
2671
|
'application/json': components['schemas']['Error'];
|
|
2638
2672
|
};
|
|
2639
2673
|
};
|
|
2640
|
-
/** @description `service_unavailable
|
|
2674
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
2641
2675
|
503: {
|
|
2642
2676
|
headers: {
|
|
2643
2677
|
[name: string]: unknown;
|
|
@@ -2653,11 +2687,11 @@ interface operations {
|
|
|
2653
2687
|
query?: never;
|
|
2654
2688
|
header?: {
|
|
2655
2689
|
/**
|
|
2656
|
-
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice
|
|
2690
|
+
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice. Without it, a client that times out and retries schedules the post a second time, and the first is already queued.
|
|
2657
2691
|
*
|
|
2658
2692
|
* Any string up to 255 characters; a UUID per logical operation is the usual choice. Keys are scoped to your workspace and honoured for 24 hours. The same key on a different route or id, or with a different body, is a `422`; a request still running under this key is a `409 request_in_progress`.
|
|
2659
2693
|
*
|
|
2660
|
-
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it
|
|
2694
|
+
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it: every one of them is raised before we write a thing, so fix the input and retry with the same key. A `5xx` pins it, and the retry replays that failure instead of doing the work: a write is several posts and several workflows, so a fault partway through leaves some of them done, and a fresh attempt would publish those a second time. Read `GET /posts/{id}` to see what exists, then continue with a new key.
|
|
2661
2695
|
*/
|
|
2662
2696
|
'Idempotency-Key'?: string;
|
|
2663
2697
|
};
|
|
@@ -2723,7 +2757,7 @@ interface operations {
|
|
|
2723
2757
|
'application/json': components['schemas']['Error'];
|
|
2724
2758
|
};
|
|
2725
2759
|
};
|
|
2726
|
-
/** @description `unsupported_media_type
|
|
2760
|
+
/** @description `unsupported_media_type`: that file type is not something any supported platform can publish. Accepting it would upload cleanly and then fail at publish, which is the failure this refusal exists to prevent. */
|
|
2727
2761
|
415: {
|
|
2728
2762
|
headers: {
|
|
2729
2763
|
[name: string]: unknown;
|
|
@@ -2741,7 +2775,7 @@ interface operations {
|
|
|
2741
2775
|
'application/json': components['schemas']['Error'];
|
|
2742
2776
|
};
|
|
2743
2777
|
};
|
|
2744
|
-
/** @description Too fast. RETRYABLE
|
|
2778
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
2745
2779
|
429: {
|
|
2746
2780
|
headers: {
|
|
2747
2781
|
/** @description Seconds to wait before retrying. */
|
|
@@ -2769,7 +2803,7 @@ interface operations {
|
|
|
2769
2803
|
'application/json': components['schemas']['Error'];
|
|
2770
2804
|
};
|
|
2771
2805
|
};
|
|
2772
|
-
/** @description `service_unavailable
|
|
2806
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
2773
2807
|
503: {
|
|
2774
2808
|
headers: {
|
|
2775
2809
|
[name: string]: unknown;
|
|
@@ -2841,7 +2875,7 @@ interface operations {
|
|
|
2841
2875
|
'application/json': components['schemas']['Error'];
|
|
2842
2876
|
};
|
|
2843
2877
|
};
|
|
2844
|
-
/** @description Too fast. RETRYABLE
|
|
2878
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
2845
2879
|
429: {
|
|
2846
2880
|
headers: {
|
|
2847
2881
|
/** @description Seconds to wait before retrying. */
|
|
@@ -2869,7 +2903,7 @@ interface operations {
|
|
|
2869
2903
|
'application/json': components['schemas']['Error'];
|
|
2870
2904
|
};
|
|
2871
2905
|
};
|
|
2872
|
-
/** @description `service_unavailable
|
|
2906
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
2873
2907
|
503: {
|
|
2874
2908
|
headers: {
|
|
2875
2909
|
[name: string]: unknown;
|
|
@@ -2926,7 +2960,7 @@ interface operations {
|
|
|
2926
2960
|
'application/json': components['schemas']['Error'];
|
|
2927
2961
|
};
|
|
2928
2962
|
};
|
|
2929
|
-
/** @description Too fast. RETRYABLE
|
|
2963
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
2930
2964
|
429: {
|
|
2931
2965
|
headers: {
|
|
2932
2966
|
/** @description Seconds to wait before retrying. */
|
|
@@ -2954,7 +2988,7 @@ interface operations {
|
|
|
2954
2988
|
'application/json': components['schemas']['Error'];
|
|
2955
2989
|
};
|
|
2956
2990
|
};
|
|
2957
|
-
/** @description `service_unavailable
|
|
2991
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
2958
2992
|
503: {
|
|
2959
2993
|
headers: {
|
|
2960
2994
|
[name: string]: unknown;
|
|
@@ -2992,7 +3026,7 @@ interface operations {
|
|
|
2992
3026
|
'application/json': components['schemas']['Error'];
|
|
2993
3027
|
};
|
|
2994
3028
|
};
|
|
2995
|
-
/** @description Too fast. RETRYABLE
|
|
3029
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
2996
3030
|
429: {
|
|
2997
3031
|
headers: {
|
|
2998
3032
|
/** @description Seconds to wait before retrying. */
|
|
@@ -3020,7 +3054,7 @@ interface operations {
|
|
|
3020
3054
|
'application/json': components['schemas']['Error'];
|
|
3021
3055
|
};
|
|
3022
3056
|
};
|
|
3023
|
-
/** @description `service_unavailable
|
|
3057
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
3024
3058
|
503: {
|
|
3025
3059
|
headers: {
|
|
3026
3060
|
[name: string]: unknown;
|
|
@@ -3034,15 +3068,15 @@ interface operations {
|
|
|
3034
3068
|
PublicPostsController_list: {
|
|
3035
3069
|
parameters: {
|
|
3036
3070
|
query?: {
|
|
3037
|
-
/** @description The previous page’s `nextCursor`. Opaque
|
|
3071
|
+
/** @description The previous page’s `nextCursor`. Opaque: a value we did not issue is rejected rather than silently restarting at page one, because a paged export that quietly rewinds re-processes everything and the client has no way to notice. */
|
|
3038
3072
|
cursor?: unknown;
|
|
3039
3073
|
/** @description Inclusive start of a scheduling window. */
|
|
3040
3074
|
from?: string;
|
|
3041
3075
|
/** @description Page size. Clamped to 100; asking for more is not an error. */
|
|
3042
3076
|
limit?: number;
|
|
3043
|
-
/** @description Repeatable: `?status=scheduled&status=failed`. `partially_published` is absent because it is computed across a submission’s channels rather than stored on any of them
|
|
3077
|
+
/** @description Repeatable: `?status=scheduled&status=failed`. `partially_published` is absent because it is computed across a submission’s channels rather than stored on any of them. Filter on `published` or `failed` and read the rolled-up `status` you get back. */
|
|
3044
3078
|
status?: ('draft' | 'scheduled' | 'publishing' | 'published' | 'failed')[];
|
|
3045
|
-
/** @description Repeatable: `?tag=tag_a&tag=tag_b`. Tag ids from `GET /public/v1/tags`. ORs, like `status
|
|
3079
|
+
/** @description Repeatable: `?tag=tag_a&tag=tag_b`. Tag ids from `GET /public/v1/tags`. ORs, like `status`: a submission matches if it carries any of them. An id this workspace does not own matches nothing rather than erroring. */
|
|
3046
3080
|
tag?: string[];
|
|
3047
3081
|
/** @description Inclusive end of a scheduling window. */
|
|
3048
3082
|
to?: string;
|
|
@@ -3080,7 +3114,7 @@ interface operations {
|
|
|
3080
3114
|
'application/json': components['schemas']['Error'];
|
|
3081
3115
|
};
|
|
3082
3116
|
};
|
|
3083
|
-
/** @description Too fast. RETRYABLE
|
|
3117
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
3084
3118
|
429: {
|
|
3085
3119
|
headers: {
|
|
3086
3120
|
/** @description Seconds to wait before retrying. */
|
|
@@ -3108,7 +3142,7 @@ interface operations {
|
|
|
3108
3142
|
'application/json': components['schemas']['Error'];
|
|
3109
3143
|
};
|
|
3110
3144
|
};
|
|
3111
|
-
/** @description `service_unavailable
|
|
3145
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
3112
3146
|
503: {
|
|
3113
3147
|
headers: {
|
|
3114
3148
|
[name: string]: unknown;
|
|
@@ -3124,11 +3158,11 @@ interface operations {
|
|
|
3124
3158
|
query?: never;
|
|
3125
3159
|
header?: {
|
|
3126
3160
|
/**
|
|
3127
|
-
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice
|
|
3161
|
+
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice. Without it, a client that times out and retries schedules the post a second time, and the first is already queued.
|
|
3128
3162
|
*
|
|
3129
3163
|
* Any string up to 255 characters; a UUID per logical operation is the usual choice. Keys are scoped to your workspace and honoured for 24 hours. The same key on a different route or id, or with a different body, is a `422`; a request still running under this key is a `409 request_in_progress`.
|
|
3130
3164
|
*
|
|
3131
|
-
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it
|
|
3165
|
+
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it: every one of them is raised before we write a thing, so fix the input and retry with the same key. A `5xx` pins it, and the retry replays that failure instead of doing the work: a write is several posts and several workflows, so a fault partway through leaves some of them done, and a fresh attempt would publish those a second time. Read `GET /posts/{id}` to see what exists, then continue with a new key.
|
|
3132
3166
|
*/
|
|
3133
3167
|
'Idempotency-Key'?: string;
|
|
3134
3168
|
};
|
|
@@ -3168,7 +3202,7 @@ interface operations {
|
|
|
3168
3202
|
'application/json': components['schemas']['Error'];
|
|
3169
3203
|
};
|
|
3170
3204
|
};
|
|
3171
|
-
/** @description The plan’s allowance for this period is spent (`quota_exceeded`). NOT retryable
|
|
3205
|
+
/** @description The plan’s allowance for this period is spent (`quota_exceeded`). NOT retryable: nothing about your request timing will help, and the limit resets at `periodEnd` from `GET /public/v1/usage`. Distinct from 429 on purpose. */
|
|
3172
3206
|
402: {
|
|
3173
3207
|
headers: {
|
|
3174
3208
|
[name: string]: unknown;
|
|
@@ -3186,7 +3220,7 @@ interface operations {
|
|
|
3186
3220
|
'application/json': components['schemas']['Error'];
|
|
3187
3221
|
};
|
|
3188
3222
|
};
|
|
3189
|
-
/** @description `payload_too_large
|
|
3223
|
+
/** @description `payload_too_large`: an upload past the per-kind ceiling (10 MB for images, 100 MB for video and documents, 5 MB for subtitle files), or a JSON body past the one a request may carry. A larger video goes through `POST /media/uploads`, where the ceiling is the plan’s video cap instead and going over it is a 402. A limit on the resource, not on the plan: a bigger plan does not raise it. */
|
|
3190
3224
|
413: {
|
|
3191
3225
|
headers: {
|
|
3192
3226
|
[name: string]: unknown;
|
|
@@ -3204,7 +3238,7 @@ interface operations {
|
|
|
3204
3238
|
'application/json': components['schemas']['Error'];
|
|
3205
3239
|
};
|
|
3206
3240
|
};
|
|
3207
|
-
/** @description Too fast. RETRYABLE
|
|
3241
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
3208
3242
|
429: {
|
|
3209
3243
|
headers: {
|
|
3210
3244
|
/** @description Seconds to wait before retrying. */
|
|
@@ -3232,7 +3266,7 @@ interface operations {
|
|
|
3232
3266
|
'application/json': components['schemas']['Error'];
|
|
3233
3267
|
};
|
|
3234
3268
|
};
|
|
3235
|
-
/** @description `service_unavailable
|
|
3269
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
3236
3270
|
503: {
|
|
3237
3271
|
headers: {
|
|
3238
3272
|
[name: string]: unknown;
|
|
@@ -3282,7 +3316,7 @@ interface operations {
|
|
|
3282
3316
|
'application/json': components['schemas']['Error'];
|
|
3283
3317
|
};
|
|
3284
3318
|
};
|
|
3285
|
-
/** @description Too fast. RETRYABLE
|
|
3319
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
3286
3320
|
429: {
|
|
3287
3321
|
headers: {
|
|
3288
3322
|
/** @description Seconds to wait before retrying. */
|
|
@@ -3310,7 +3344,7 @@ interface operations {
|
|
|
3310
3344
|
'application/json': components['schemas']['Error'];
|
|
3311
3345
|
};
|
|
3312
3346
|
};
|
|
3313
|
-
/** @description `service_unavailable
|
|
3347
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
3314
3348
|
503: {
|
|
3315
3349
|
headers: {
|
|
3316
3350
|
[name: string]: unknown;
|
|
@@ -3326,11 +3360,11 @@ interface operations {
|
|
|
3326
3360
|
query?: never;
|
|
3327
3361
|
header?: {
|
|
3328
3362
|
/**
|
|
3329
|
-
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice
|
|
3363
|
+
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice. Without it, a client that times out and retries schedules the post a second time, and the first is already queued.
|
|
3330
3364
|
*
|
|
3331
3365
|
* Any string up to 255 characters; a UUID per logical operation is the usual choice. Keys are scoped to your workspace and honoured for 24 hours. The same key on a different route or id, or with a different body, is a `422`; a request still running under this key is a `409 request_in_progress`.
|
|
3332
3366
|
*
|
|
3333
|
-
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it
|
|
3367
|
+
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it: every one of them is raised before we write a thing, so fix the input and retry with the same key. A `5xx` pins it, and the retry replays that failure instead of doing the work: a write is several posts and several workflows, so a fault partway through leaves some of them done, and a fresh attempt would publish those a second time. Read `GET /posts/{id}` to see what exists, then continue with a new key.
|
|
3334
3368
|
*/
|
|
3335
3369
|
'Idempotency-Key'?: string;
|
|
3336
3370
|
};
|
|
@@ -3373,7 +3407,7 @@ interface operations {
|
|
|
3373
3407
|
'application/json': components['schemas']['Error'];
|
|
3374
3408
|
};
|
|
3375
3409
|
};
|
|
3376
|
-
/** @description The plan’s allowance for this period is spent (`quota_exceeded`). NOT retryable
|
|
3410
|
+
/** @description The plan’s allowance for this period is spent (`quota_exceeded`). NOT retryable: nothing about your request timing will help, and the limit resets at `periodEnd` from `GET /public/v1/usage`. Distinct from 429 on purpose. */
|
|
3377
3411
|
402: {
|
|
3378
3412
|
headers: {
|
|
3379
3413
|
[name: string]: unknown;
|
|
@@ -3409,7 +3443,7 @@ interface operations {
|
|
|
3409
3443
|
'application/json': components['schemas']['Error'];
|
|
3410
3444
|
};
|
|
3411
3445
|
};
|
|
3412
|
-
/** @description `payload_too_large
|
|
3446
|
+
/** @description `payload_too_large`: an upload past the per-kind ceiling (10 MB for images, 100 MB for video and documents, 5 MB for subtitle files), or a JSON body past the one a request may carry. A larger video goes through `POST /media/uploads`, where the ceiling is the plan’s video cap instead and going over it is a 402. A limit on the resource, not on the plan: a bigger plan does not raise it. */
|
|
3413
3447
|
413: {
|
|
3414
3448
|
headers: {
|
|
3415
3449
|
[name: string]: unknown;
|
|
@@ -3427,7 +3461,7 @@ interface operations {
|
|
|
3427
3461
|
'application/json': components['schemas']['Error'];
|
|
3428
3462
|
};
|
|
3429
3463
|
};
|
|
3430
|
-
/** @description Too fast. RETRYABLE
|
|
3464
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
3431
3465
|
429: {
|
|
3432
3466
|
headers: {
|
|
3433
3467
|
/** @description Seconds to wait before retrying. */
|
|
@@ -3455,7 +3489,7 @@ interface operations {
|
|
|
3455
3489
|
'application/json': components['schemas']['Error'];
|
|
3456
3490
|
};
|
|
3457
3491
|
};
|
|
3458
|
-
/** @description `service_unavailable
|
|
3492
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
3459
3493
|
503: {
|
|
3460
3494
|
headers: {
|
|
3461
3495
|
[name: string]: unknown;
|
|
@@ -3512,7 +3546,7 @@ interface operations {
|
|
|
3512
3546
|
'application/json': components['schemas']['Error'];
|
|
3513
3547
|
};
|
|
3514
3548
|
};
|
|
3515
|
-
/** @description Too fast. RETRYABLE
|
|
3549
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
3516
3550
|
429: {
|
|
3517
3551
|
headers: {
|
|
3518
3552
|
/** @description Seconds to wait before retrying. */
|
|
@@ -3540,7 +3574,7 @@ interface operations {
|
|
|
3540
3574
|
'application/json': components['schemas']['Error'];
|
|
3541
3575
|
};
|
|
3542
3576
|
};
|
|
3543
|
-
/** @description `service_unavailable
|
|
3577
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
3544
3578
|
503: {
|
|
3545
3579
|
headers: {
|
|
3546
3580
|
[name: string]: unknown;
|
|
@@ -3622,7 +3656,7 @@ interface operations {
|
|
|
3622
3656
|
'application/json': components['schemas']['Error'];
|
|
3623
3657
|
};
|
|
3624
3658
|
};
|
|
3625
|
-
/** @description Too fast. RETRYABLE
|
|
3659
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
3626
3660
|
429: {
|
|
3627
3661
|
headers: {
|
|
3628
3662
|
/** @description Seconds to wait before retrying. */
|
|
@@ -3659,7 +3693,7 @@ interface operations {
|
|
|
3659
3693
|
'application/json': components['schemas']['Error'];
|
|
3660
3694
|
};
|
|
3661
3695
|
};
|
|
3662
|
-
/** @description `service_unavailable
|
|
3696
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
3663
3697
|
503: {
|
|
3664
3698
|
headers: {
|
|
3665
3699
|
[name: string]: unknown;
|
|
@@ -3675,11 +3709,11 @@ interface operations {
|
|
|
3675
3709
|
query?: never;
|
|
3676
3710
|
header?: {
|
|
3677
3711
|
/**
|
|
3678
|
-
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice
|
|
3712
|
+
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice. Without it, a client that times out and retries schedules the post a second time, and the first is already queued.
|
|
3679
3713
|
*
|
|
3680
3714
|
* Any string up to 255 characters; a UUID per logical operation is the usual choice. Keys are scoped to your workspace and honoured for 24 hours. The same key on a different route or id, or with a different body, is a `422`; a request still running under this key is a `409 request_in_progress`.
|
|
3681
3715
|
*
|
|
3682
|
-
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it
|
|
3716
|
+
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it: every one of them is raised before we write a thing, so fix the input and retry with the same key. A `5xx` pins it, and the retry replays that failure instead of doing the work: a write is several posts and several workflows, so a fault partway through leaves some of them done, and a fresh attempt would publish those a second time. Read `GET /posts/{id}` to see what exists, then continue with a new key.
|
|
3683
3717
|
*/
|
|
3684
3718
|
'Idempotency-Key'?: string;
|
|
3685
3719
|
};
|
|
@@ -3724,7 +3758,7 @@ interface operations {
|
|
|
3724
3758
|
'application/json': components['schemas']['Error'];
|
|
3725
3759
|
};
|
|
3726
3760
|
};
|
|
3727
|
-
/** @description The plan’s allowance for this period is spent (`quota_exceeded`). NOT retryable
|
|
3761
|
+
/** @description The plan’s allowance for this period is spent (`quota_exceeded`). NOT retryable: nothing about your request timing will help, and the limit resets at `periodEnd` from `GET /public/v1/usage`. Distinct from 429 on purpose. */
|
|
3728
3762
|
402: {
|
|
3729
3763
|
headers: {
|
|
3730
3764
|
[name: string]: unknown;
|
|
@@ -3769,7 +3803,7 @@ interface operations {
|
|
|
3769
3803
|
'application/json': components['schemas']['Error'];
|
|
3770
3804
|
};
|
|
3771
3805
|
};
|
|
3772
|
-
/** @description Too fast. RETRYABLE
|
|
3806
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
3773
3807
|
429: {
|
|
3774
3808
|
headers: {
|
|
3775
3809
|
/** @description Seconds to wait before retrying. */
|
|
@@ -3806,7 +3840,7 @@ interface operations {
|
|
|
3806
3840
|
'application/json': components['schemas']['Error'];
|
|
3807
3841
|
};
|
|
3808
3842
|
};
|
|
3809
|
-
/** @description `service_unavailable
|
|
3843
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
3810
3844
|
503: {
|
|
3811
3845
|
headers: {
|
|
3812
3846
|
[name: string]: unknown;
|
|
@@ -3856,7 +3890,7 @@ interface operations {
|
|
|
3856
3890
|
'application/json': components['schemas']['Error'];
|
|
3857
3891
|
};
|
|
3858
3892
|
};
|
|
3859
|
-
/** @description Too fast. RETRYABLE
|
|
3893
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
3860
3894
|
429: {
|
|
3861
3895
|
headers: {
|
|
3862
3896
|
/** @description Seconds to wait before retrying. */
|
|
@@ -3884,7 +3918,7 @@ interface operations {
|
|
|
3884
3918
|
'application/json': components['schemas']['Error'];
|
|
3885
3919
|
};
|
|
3886
3920
|
};
|
|
3887
|
-
/** @description `service_unavailable
|
|
3921
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
3888
3922
|
503: {
|
|
3889
3923
|
headers: {
|
|
3890
3924
|
[name: string]: unknown;
|
|
@@ -3900,11 +3934,11 @@ interface operations {
|
|
|
3900
3934
|
query?: never;
|
|
3901
3935
|
header?: {
|
|
3902
3936
|
/**
|
|
3903
|
-
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice
|
|
3937
|
+
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice. Without it, a client that times out and retries schedules the post a second time, and the first is already queued.
|
|
3904
3938
|
*
|
|
3905
3939
|
* Any string up to 255 characters; a UUID per logical operation is the usual choice. Keys are scoped to your workspace and honoured for 24 hours. The same key on a different route or id, or with a different body, is a `422`; a request still running under this key is a `409 request_in_progress`.
|
|
3906
3940
|
*
|
|
3907
|
-
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it
|
|
3941
|
+
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it: every one of them is raised before we write a thing, so fix the input and retry with the same key. A `5xx` pins it, and the retry replays that failure instead of doing the work: a write is several posts and several workflows, so a fault partway through leaves some of them done, and a fresh attempt would publish those a second time. Read `GET /posts/{id}` to see what exists, then continue with a new key.
|
|
3908
3942
|
*/
|
|
3909
3943
|
'Idempotency-Key'?: string;
|
|
3910
3944
|
};
|
|
@@ -3916,7 +3950,7 @@ interface operations {
|
|
|
3916
3950
|
};
|
|
3917
3951
|
requestBody?: never;
|
|
3918
3952
|
responses: {
|
|
3919
|
-
/** @description The submission, with the queued channels now `publishing`. 201 rather than 200
|
|
3953
|
+
/** @description The submission, with the queued channels now `publishing`. 201 rather than 200 (the framework default for POST); nothing new was created. */
|
|
3920
3954
|
201: {
|
|
3921
3955
|
headers: {
|
|
3922
3956
|
[name: string]: unknown;
|
|
@@ -3943,7 +3977,7 @@ interface operations {
|
|
|
3943
3977
|
'application/json': components['schemas']['Error'];
|
|
3944
3978
|
};
|
|
3945
3979
|
};
|
|
3946
|
-
/** @description The plan’s allowance for this period is spent (`quota_exceeded`). NOT retryable
|
|
3980
|
+
/** @description The plan’s allowance for this period is spent (`quota_exceeded`). NOT retryable: nothing about your request timing will help, and the limit resets at `periodEnd` from `GET /public/v1/usage`. Distinct from 429 on purpose. */
|
|
3947
3981
|
402: {
|
|
3948
3982
|
headers: {
|
|
3949
3983
|
[name: string]: unknown;
|
|
@@ -3988,7 +4022,7 @@ interface operations {
|
|
|
3988
4022
|
'application/json': components['schemas']['Error'];
|
|
3989
4023
|
};
|
|
3990
4024
|
};
|
|
3991
|
-
/** @description Too fast. RETRYABLE
|
|
4025
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
3992
4026
|
429: {
|
|
3993
4027
|
headers: {
|
|
3994
4028
|
/** @description Seconds to wait before retrying. */
|
|
@@ -4016,7 +4050,7 @@ interface operations {
|
|
|
4016
4050
|
'application/json': components['schemas']['Error'];
|
|
4017
4051
|
};
|
|
4018
4052
|
};
|
|
4019
|
-
/** @description `service_unavailable
|
|
4053
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
4020
4054
|
503: {
|
|
4021
4055
|
headers: {
|
|
4022
4056
|
[name: string]: unknown;
|
|
@@ -4084,7 +4118,7 @@ interface operations {
|
|
|
4084
4118
|
'application/json': components['schemas']['Error'];
|
|
4085
4119
|
};
|
|
4086
4120
|
};
|
|
4087
|
-
/** @description Too fast. RETRYABLE
|
|
4121
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
4088
4122
|
429: {
|
|
4089
4123
|
headers: {
|
|
4090
4124
|
/** @description Seconds to wait before retrying. */
|
|
@@ -4112,7 +4146,7 @@ interface operations {
|
|
|
4112
4146
|
'application/json': components['schemas']['Error'];
|
|
4113
4147
|
};
|
|
4114
4148
|
};
|
|
4115
|
-
/** @description `service_unavailable
|
|
4149
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
4116
4150
|
503: {
|
|
4117
4151
|
headers: {
|
|
4118
4152
|
[name: string]: unknown;
|
|
@@ -4193,7 +4227,7 @@ interface operations {
|
|
|
4193
4227
|
'application/json': components['schemas']['Error'];
|
|
4194
4228
|
};
|
|
4195
4229
|
};
|
|
4196
|
-
/** @description Too fast. RETRYABLE
|
|
4230
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
4197
4231
|
429: {
|
|
4198
4232
|
headers: {
|
|
4199
4233
|
/** @description Seconds to wait before retrying. */
|
|
@@ -4221,7 +4255,7 @@ interface operations {
|
|
|
4221
4255
|
'application/json': components['schemas']['Error'];
|
|
4222
4256
|
};
|
|
4223
4257
|
};
|
|
4224
|
-
/** @description `service_unavailable
|
|
4258
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
4225
4259
|
503: {
|
|
4226
4260
|
headers: {
|
|
4227
4261
|
[name: string]: unknown;
|
|
@@ -4275,7 +4309,7 @@ interface operations {
|
|
|
4275
4309
|
'application/json': components['schemas']['Error'];
|
|
4276
4310
|
};
|
|
4277
4311
|
};
|
|
4278
|
-
/** @description Too fast. RETRYABLE
|
|
4312
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
4279
4313
|
429: {
|
|
4280
4314
|
headers: {
|
|
4281
4315
|
/** @description Seconds to wait before retrying. */
|
|
@@ -4303,7 +4337,7 @@ interface operations {
|
|
|
4303
4337
|
'application/json': components['schemas']['Error'];
|
|
4304
4338
|
};
|
|
4305
4339
|
};
|
|
4306
|
-
/** @description `service_unavailable
|
|
4340
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
4307
4341
|
503: {
|
|
4308
4342
|
headers: {
|
|
4309
4343
|
[name: string]: unknown;
|
|
@@ -4363,7 +4397,7 @@ interface operations {
|
|
|
4363
4397
|
'application/json': components['schemas']['Error'];
|
|
4364
4398
|
};
|
|
4365
4399
|
};
|
|
4366
|
-
/** @description Too fast. RETRYABLE
|
|
4400
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
4367
4401
|
429: {
|
|
4368
4402
|
headers: {
|
|
4369
4403
|
/** @description Seconds to wait before retrying. */
|
|
@@ -4391,7 +4425,7 @@ interface operations {
|
|
|
4391
4425
|
'application/json': components['schemas']['Error'];
|
|
4392
4426
|
};
|
|
4393
4427
|
};
|
|
4394
|
-
/** @description `service_unavailable
|
|
4428
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
4395
4429
|
503: {
|
|
4396
4430
|
headers: {
|
|
4397
4431
|
[name: string]: unknown;
|
|
@@ -4429,7 +4463,7 @@ interface operations {
|
|
|
4429
4463
|
'application/json': components['schemas']['Error'];
|
|
4430
4464
|
};
|
|
4431
4465
|
};
|
|
4432
|
-
/** @description Too fast. RETRYABLE
|
|
4466
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
4433
4467
|
429: {
|
|
4434
4468
|
headers: {
|
|
4435
4469
|
/** @description Seconds to wait before retrying. */
|
|
@@ -4457,7 +4491,7 @@ interface operations {
|
|
|
4457
4491
|
'application/json': components['schemas']['Error'];
|
|
4458
4492
|
};
|
|
4459
4493
|
};
|
|
4460
|
-
/** @description `service_unavailable
|
|
4494
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
4461
4495
|
503: {
|
|
4462
4496
|
headers: {
|
|
4463
4497
|
[name: string]: unknown;
|
|
@@ -4504,7 +4538,7 @@ interface operations {
|
|
|
4504
4538
|
'application/json': components['schemas']['Error'];
|
|
4505
4539
|
};
|
|
4506
4540
|
};
|
|
4507
|
-
/** @description Too fast. RETRYABLE
|
|
4541
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
4508
4542
|
429: {
|
|
4509
4543
|
headers: {
|
|
4510
4544
|
/** @description Seconds to wait before retrying. */
|
|
@@ -4532,7 +4566,7 @@ interface operations {
|
|
|
4532
4566
|
'application/json': components['schemas']['Error'];
|
|
4533
4567
|
};
|
|
4534
4568
|
};
|
|
4535
|
-
/** @description `service_unavailable
|
|
4569
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
4536
4570
|
503: {
|
|
4537
4571
|
headers: {
|
|
4538
4572
|
[name: string]: unknown;
|
|
@@ -4570,7 +4604,7 @@ interface operations {
|
|
|
4570
4604
|
'application/json': components['schemas']['Error'];
|
|
4571
4605
|
};
|
|
4572
4606
|
};
|
|
4573
|
-
/** @description Too fast. RETRYABLE
|
|
4607
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
4574
4608
|
429: {
|
|
4575
4609
|
headers: {
|
|
4576
4610
|
/** @description Seconds to wait before retrying. */
|
|
@@ -4598,7 +4632,7 @@ interface operations {
|
|
|
4598
4632
|
'application/json': components['schemas']['Error'];
|
|
4599
4633
|
};
|
|
4600
4634
|
};
|
|
4601
|
-
/** @description `service_unavailable
|
|
4635
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
4602
4636
|
503: {
|
|
4603
4637
|
headers: {
|
|
4604
4638
|
[name: string]: unknown;
|
|
@@ -4614,11 +4648,11 @@ interface operations {
|
|
|
4614
4648
|
query?: never;
|
|
4615
4649
|
header?: {
|
|
4616
4650
|
/**
|
|
4617
|
-
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice
|
|
4651
|
+
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice. Without it, a client that times out and retries schedules the post a second time, and the first is already queued.
|
|
4618
4652
|
*
|
|
4619
4653
|
* Any string up to 255 characters; a UUID per logical operation is the usual choice. Keys are scoped to your workspace and honoured for 24 hours. The same key on a different route or id, or with a different body, is a `422`; a request still running under this key is a `409 request_in_progress`.
|
|
4620
4654
|
*
|
|
4621
|
-
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it
|
|
4655
|
+
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it: every one of them is raised before we write a thing, so fix the input and retry with the same key. A `5xx` pins it, and the retry replays that failure instead of doing the work: a write is several posts and several workflows, so a fault partway through leaves some of them done, and a fresh attempt would publish those a second time. Read `GET /posts/{id}` to see what exists, then continue with a new key.
|
|
4622
4656
|
*/
|
|
4623
4657
|
'Idempotency-Key'?: string;
|
|
4624
4658
|
};
|
|
@@ -4676,7 +4710,7 @@ interface operations {
|
|
|
4676
4710
|
'application/json': components['schemas']['Error'];
|
|
4677
4711
|
};
|
|
4678
4712
|
};
|
|
4679
|
-
/** @description Too fast. RETRYABLE
|
|
4713
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
4680
4714
|
429: {
|
|
4681
4715
|
headers: {
|
|
4682
4716
|
/** @description Seconds to wait before retrying. */
|
|
@@ -4704,7 +4738,7 @@ interface operations {
|
|
|
4704
4738
|
'application/json': components['schemas']['Error'];
|
|
4705
4739
|
};
|
|
4706
4740
|
};
|
|
4707
|
-
/** @description `service_unavailable
|
|
4741
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
4708
4742
|
503: {
|
|
4709
4743
|
headers: {
|
|
4710
4744
|
[name: string]: unknown;
|
|
@@ -4754,7 +4788,7 @@ interface operations {
|
|
|
4754
4788
|
'application/json': components['schemas']['Error'];
|
|
4755
4789
|
};
|
|
4756
4790
|
};
|
|
4757
|
-
/** @description Too fast. RETRYABLE
|
|
4791
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
4758
4792
|
429: {
|
|
4759
4793
|
headers: {
|
|
4760
4794
|
/** @description Seconds to wait before retrying. */
|
|
@@ -4782,7 +4816,7 @@ interface operations {
|
|
|
4782
4816
|
'application/json': components['schemas']['Error'];
|
|
4783
4817
|
};
|
|
4784
4818
|
};
|
|
4785
|
-
/** @description `service_unavailable
|
|
4819
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
4786
4820
|
503: {
|
|
4787
4821
|
headers: {
|
|
4788
4822
|
[name: string]: unknown;
|
|
@@ -4798,11 +4832,11 @@ interface operations {
|
|
|
4798
4832
|
query?: never;
|
|
4799
4833
|
header?: {
|
|
4800
4834
|
/**
|
|
4801
|
-
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice
|
|
4835
|
+
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice. Without it, a client that times out and retries schedules the post a second time, and the first is already queued.
|
|
4802
4836
|
*
|
|
4803
4837
|
* Any string up to 255 characters; a UUID per logical operation is the usual choice. Keys are scoped to your workspace and honoured for 24 hours. The same key on a different route or id, or with a different body, is a `422`; a request still running under this key is a `409 request_in_progress`.
|
|
4804
4838
|
*
|
|
4805
|
-
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it
|
|
4839
|
+
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it: every one of them is raised before we write a thing, so fix the input and retry with the same key. A `5xx` pins it, and the retry replays that failure instead of doing the work: a write is several posts and several workflows, so a fault partway through leaves some of them done, and a fresh attempt would publish those a second time. Read `GET /posts/{id}` to see what exists, then continue with a new key.
|
|
4806
4840
|
*/
|
|
4807
4841
|
'Idempotency-Key'?: string;
|
|
4808
4842
|
};
|
|
@@ -4872,7 +4906,7 @@ interface operations {
|
|
|
4872
4906
|
'application/json': components['schemas']['Error'];
|
|
4873
4907
|
};
|
|
4874
4908
|
};
|
|
4875
|
-
/** @description Too fast. RETRYABLE
|
|
4909
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
4876
4910
|
429: {
|
|
4877
4911
|
headers: {
|
|
4878
4912
|
/** @description Seconds to wait before retrying. */
|
|
@@ -4900,7 +4934,7 @@ interface operations {
|
|
|
4900
4934
|
'application/json': components['schemas']['Error'];
|
|
4901
4935
|
};
|
|
4902
4936
|
};
|
|
4903
|
-
/** @description `service_unavailable
|
|
4937
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
4904
4938
|
503: {
|
|
4905
4939
|
headers: {
|
|
4906
4940
|
[name: string]: unknown;
|
|
@@ -4957,7 +4991,7 @@ interface operations {
|
|
|
4957
4991
|
'application/json': components['schemas']['Error'];
|
|
4958
4992
|
};
|
|
4959
4993
|
};
|
|
4960
|
-
/** @description Too fast. RETRYABLE
|
|
4994
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
4961
4995
|
429: {
|
|
4962
4996
|
headers: {
|
|
4963
4997
|
/** @description Seconds to wait before retrying. */
|
|
@@ -4985,7 +5019,7 @@ interface operations {
|
|
|
4985
5019
|
'application/json': components['schemas']['Error'];
|
|
4986
5020
|
};
|
|
4987
5021
|
};
|
|
4988
|
-
/** @description `service_unavailable
|
|
5022
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
4989
5023
|
503: {
|
|
4990
5024
|
headers: {
|
|
4991
5025
|
[name: string]: unknown;
|
|
@@ -5049,7 +5083,7 @@ interface operations {
|
|
|
5049
5083
|
'application/json': components['schemas']['Error'];
|
|
5050
5084
|
};
|
|
5051
5085
|
};
|
|
5052
|
-
/** @description Too fast. RETRYABLE
|
|
5086
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
5053
5087
|
429: {
|
|
5054
5088
|
headers: {
|
|
5055
5089
|
/** @description Seconds to wait before retrying. */
|
|
@@ -5077,7 +5111,7 @@ interface operations {
|
|
|
5077
5111
|
'application/json': components['schemas']['Error'];
|
|
5078
5112
|
};
|
|
5079
5113
|
};
|
|
5080
|
-
/** @description `service_unavailable
|
|
5114
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
5081
5115
|
503: {
|
|
5082
5116
|
headers: {
|
|
5083
5117
|
[name: string]: unknown;
|
|
@@ -5093,11 +5127,11 @@ interface operations {
|
|
|
5093
5127
|
query?: never;
|
|
5094
5128
|
header?: {
|
|
5095
5129
|
/**
|
|
5096
|
-
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice
|
|
5130
|
+
* @description Send one on every write. A retry carrying the same key returns the FIRST response instead of doing the work twice. Without it, a client that times out and retries schedules the post a second time, and the first is already queued.
|
|
5097
5131
|
*
|
|
5098
5132
|
* Any string up to 255 characters; a UUID per logical operation is the usual choice. Keys are scoped to your workspace and honoured for 24 hours. The same key on a different route or id, or with a different body, is a `422`; a request still running under this key is a `409 request_in_progress`.
|
|
5099
5133
|
*
|
|
5100
|
-
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it
|
|
5134
|
+
* What a FAILED request does to its key depends on whether it could have changed anything. A `4xx` releases it: every one of them is raised before we write a thing, so fix the input and retry with the same key. A `5xx` pins it, and the retry replays that failure instead of doing the work: a write is several posts and several workflows, so a fault partway through leaves some of them done, and a fresh attempt would publish those a second time. Read `GET /posts/{id}` to see what exists, then continue with a new key.
|
|
5101
5135
|
*/
|
|
5102
5136
|
'Idempotency-Key'?: string;
|
|
5103
5137
|
};
|
|
@@ -5109,7 +5143,7 @@ interface operations {
|
|
|
5109
5143
|
};
|
|
5110
5144
|
requestBody?: never;
|
|
5111
5145
|
responses: {
|
|
5112
|
-
/** @description The endpoint with its new secret. 201 rather than 200
|
|
5146
|
+
/** @description The endpoint with its new secret. 201 rather than 200 (the framework default for POST); nothing new was created. */
|
|
5113
5147
|
201: {
|
|
5114
5148
|
headers: {
|
|
5115
5149
|
[name: string]: unknown;
|
|
@@ -5154,7 +5188,7 @@ interface operations {
|
|
|
5154
5188
|
'application/json': components['schemas']['Error'];
|
|
5155
5189
|
};
|
|
5156
5190
|
};
|
|
5157
|
-
/** @description Too fast. RETRYABLE
|
|
5191
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
5158
5192
|
429: {
|
|
5159
5193
|
headers: {
|
|
5160
5194
|
/** @description Seconds to wait before retrying. */
|
|
@@ -5182,7 +5216,7 @@ interface operations {
|
|
|
5182
5216
|
'application/json': components['schemas']['Error'];
|
|
5183
5217
|
};
|
|
5184
5218
|
};
|
|
5185
|
-
/** @description `service_unavailable
|
|
5219
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
5186
5220
|
503: {
|
|
5187
5221
|
headers: {
|
|
5188
5222
|
[name: string]: unknown;
|
|
@@ -5241,7 +5275,7 @@ interface operations {
|
|
|
5241
5275
|
'application/json': components['schemas']['Error'];
|
|
5242
5276
|
};
|
|
5243
5277
|
};
|
|
5244
|
-
/** @description Too fast. RETRYABLE
|
|
5278
|
+
/** @description Too fast. RETRYABLE: `Retry-After` says when, and `X-RateLimit-*` say what the ceiling was. Distinct from 402: no upgrade is needed to make this exact call succeed. */
|
|
5245
5279
|
429: {
|
|
5246
5280
|
headers: {
|
|
5247
5281
|
/** @description Seconds to wait before retrying. */
|
|
@@ -5269,7 +5303,7 @@ interface operations {
|
|
|
5269
5303
|
'application/json': components['schemas']['Error'];
|
|
5270
5304
|
};
|
|
5271
5305
|
};
|
|
5272
|
-
/** @description `service_unavailable
|
|
5306
|
+
/** @description `service_unavailable`: a dependency we need was unreachable and the request was not attempted, or not completed. Retryable, unlike a 500, and safe to retry with the same `Idempotency-Key`. */
|
|
5273
5307
|
503: {
|
|
5274
5308
|
headers: {
|
|
5275
5309
|
[name: string]: unknown;
|
|
@@ -5315,6 +5349,7 @@ type CommentReply = Schemas['CommentReply'];
|
|
|
5315
5349
|
type CommentListParams = WithStrings<QueryOf<'PublicPostsController_listComments'>, 'channelId' | 'cursor'>;
|
|
5316
5350
|
type CommentReplyParams = Schemas['ReplyToCommentRequest'];
|
|
5317
5351
|
type MediaItem = Schemas['MediaItem'];
|
|
5352
|
+
type MediaListParams = WithStrings<QueryOf<'PublicMediaController_list'>, 'cursor'>;
|
|
5318
5353
|
type MediaUpload = Schemas['MediaUpload'];
|
|
5319
5354
|
type MediaUploadPart = Schemas['MediaUploadPart'];
|
|
5320
5355
|
type MediaUploadStartParams = Schemas['StartMediaUploadRequest'];
|
|
@@ -5378,8 +5413,15 @@ interface MultipartUploadParams extends MediaUploadParams {
|
|
|
5378
5413
|
declare class Media extends APIResource {
|
|
5379
5414
|
#private;
|
|
5380
5415
|
readonly uploads: MediaUploads;
|
|
5381
|
-
/**
|
|
5382
|
-
|
|
5416
|
+
/**
|
|
5417
|
+
* The workspace's media library, newest first. Await it for one page, or iterate it
|
|
5418
|
+
* for every file:
|
|
5419
|
+
*
|
|
5420
|
+
* ```ts
|
|
5421
|
+
* for await (const item of bulkit.media.list()) { ... }
|
|
5422
|
+
* ```
|
|
5423
|
+
*/
|
|
5424
|
+
list(params?: MediaListParams, options?: RequestOptions): PagePromise<MediaItem>;
|
|
5383
5425
|
/**
|
|
5384
5426
|
* Upload a file in one request: images up to 10 MB, video and PDFs up to 100 MB,
|
|
5385
5427
|
* subtitles up to 5 MB. For larger video, use `uploadMultipart()`.
|
|
@@ -5735,7 +5777,7 @@ export declare class WebhookVerificationError extends BulkitError {
|
|
|
5735
5777
|
}
|
|
5736
5778
|
//#endregion
|
|
5737
5779
|
//#region src/version.d.ts
|
|
5738
|
-
export declare const VERSION = "0.
|
|
5780
|
+
export declare const VERSION = "0.2.0";
|
|
5739
5781
|
//#endregion
|
|
5740
|
-
export type { APIResponse, Attachment, Channel, ChannelCapabilities, ClientOptions, Comment, CommentListParams, CommentReply, CommentReplyParams, ErrorCode, Fetch, FieldError, HeadersLike, IssuedWebhookEndpoint, MediaItem, MediaUpload, MediaUploadParams, MediaUploadPart, MediaUploadStartParams, MultipartUploadParams, OptionChoices, OptionChoicesParams, Platform, PlatformLimits, Post, PostBlock, PostChannel, PostCreateBlock, PostCreateChannel, PostCreateParams, PostListParams, PostMetrics, PostReviseParams, PostStatus, PostType, RateLimitInfo, RequestOptions, RetractResult, ReviseResult, Stats, StatsInsights, StatsInsightsParams, StatsParams, Tag, Uploadable, Usage, UsageMetric, VerifyWebhookOptions, WebhookChannelData, WebhookCreateParams, WebhookDelivery, WebhookDeliveryListParams, WebhookEndpoint, WebhookEvent, WebhookEventType, WebhookPostData, WebhookTestResult, WebhookUpdateParams };
|
|
5782
|
+
export type { APIResponse, Attachment, Channel, ChannelCapabilities, ClientOptions, Comment, CommentListParams, CommentReply, CommentReplyParams, ErrorCode, Fetch, FieldError, HeadersLike, IssuedWebhookEndpoint, MediaItem, MediaListParams, MediaUpload, MediaUploadParams, MediaUploadPart, MediaUploadStartParams, MultipartUploadParams, OptionChoices, OptionChoicesParams, Platform, PlatformLimits, Post, PostBlock, PostChannel, PostCreateBlock, PostCreateChannel, PostCreateParams, PostListParams, PostMetrics, PostReviseParams, PostStatus, PostType, RateLimitInfo, RequestOptions, RetractResult, ReviseResult, Stats, StatsInsights, StatsInsightsParams, StatsParams, Tag, Uploadable, Usage, UsageMetric, VerifyWebhookOptions, WebhookChannelData, WebhookCreateParams, WebhookDelivery, WebhookDeliveryListParams, WebhookEndpoint, WebhookEvent, WebhookEventType, WebhookPostData, WebhookTestResult, WebhookUpdateParams };
|
|
5741
5783
|
//# sourceMappingURL=index.d.cts.map
|