bulkit 0.1.0 → 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/dist/index.d.ts 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 — key durable state off this.
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` — 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.
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 — what `POST /public/v1/posts/{id}/retract` and `POST /public/v1/posts/{id}/revise` can actually do here.
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` — 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.
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` — 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.
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 — rotation is already applied, so a portrait phone clip counts as portrait.
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 — 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.
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 — 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. */
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 — 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. */
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 — a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
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 — 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.
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 — 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.
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 — a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
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 — 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.
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 — 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.
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 — a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
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 — 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.
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 — 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.
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 — see YouTube’s `captionFile` — whose own `mimeTypes` and `maxBytes` are the rules that bind it. */
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 — a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
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 — 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.
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 — 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.
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 — `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.
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 — its own kind included, which is what separates it from the per-kind flag. Mixing them is `attachment_types_mixed`. */
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 — "GIF". Null where the kind name is the right word.
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 — a block with neither is refused as `content_empty`. */
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 — an id belonging to another workspace is refused, not silently ignored. */
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 — 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.
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
- * "med_2f8a": "A hand-drawn logo on a pale background"
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 — 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.
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
- * "med_2f8a": [
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 — 0.5 is the middle, whatever the picture was uploaded at. Not pixels: a fraction is what survives the platform re-encoding the file.
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 — 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`.
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 — 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.
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 — 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.
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` — store it, publish nothing. It still occupies its slot.
526
- * `schedule` — store it and start a durable timer for `scheduledAt`.
527
- * `now` — store it and queue it for immediate publication.
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 — including drafts. */
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 — 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. */
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` — nothing sent to one would reach you.
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 — safe to surface to your own users. Never branch on it.
567
- * @example X (Twitter) allows 280 characters — this one is 300
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 — 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.
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 — a platform rule refuses one thing at a time. Fix them together rather than a round trip per mistake. */
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 — never branch on it.
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 — registering an endpoint and rolling its secret — and by nothing else, ever. */
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 — key durable state off this.
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 — never branch on it.
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 — 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. */
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 — they change when a platform changes, and a client carrying its own copy will be wrong before we are. */
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 — 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.
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 — check an upload's `mimeType` against every platform it's headed for.
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 — `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. */
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 — 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. */
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 — 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. */
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 — 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`. */
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 — 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. */
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 — never branch on it.
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 — 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. */
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 — 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. */
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 — never branch on it.
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 — 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.
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 — going without is `option_required`. */
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 — 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. */
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` — 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`.
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 — 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.
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` — 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.
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 — 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. */
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 — the same promise `acceptedMimeTypes` makes.
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` — 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. */
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 — 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. */
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 — 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.
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 — 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. */
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 — 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. */
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` — the one you also have to send a value for.
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 — 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. */
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 — 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.
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 — 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.
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 — 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. */
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 — 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. */
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 — rotation is already applied, so a portrait phone clip counts as portrait.
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 — 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.
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 — 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. */
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 — 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. */
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 — a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
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 — 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.
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 — 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.
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 — a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
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 — 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.
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 — 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.
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 — a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
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 — 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.
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 — 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.
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 — see YouTube’s `captionFile` — whose own `mimeTypes` and `maxBytes` are the rules that bind it. */
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 — a stored file always has a size, where the duration and dimensions above are measured best-effort and are unknown for every image.
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 — 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.
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 — 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.
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 — `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.
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 — its own kind included, which is what separates it from the per-kind flag. Mixing them is `attachment_types_mixed`. */
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 — "GIF". Null where the kind name is the right word.
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 — 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`. */
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` — Reddit rewrites a post's body and never its title. */
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 — which is every platform today. A revision arriving after it is `edit_window_expired`. */
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 — retracting a submission that includes one deletes our record and reports that channel as one whose copy stays up. */
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 — 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`. */
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 — 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. */
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 — a tweet in a thread, a LinkedIn post or one of its comments. */
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
- * "med_2f8a": [
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 — 0.5 is the middle, whatever the picture was uploaded at. Not pixels: a fraction is what survives the platform re-encoding the file.
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 — the publication and its result survive, the link to a live channel does not.
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 — 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.
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 — 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.
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 — it was not reported at this capture, which on most platforms means it is never reported.
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 — the series behind `GET /public/v1/stats`, which only ever sums the latest reading of each publication.
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 — 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.
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 — omitting it would be indistinguishable from a channel the submission never went to, and "no readings" is the common case. */
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` — 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.
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 — the normal case, not an error. */
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 — that, not an empty `data`, is how a client knows to stop. Opaque by contract: do not parse it. */
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 — a kind of post is a different publication, not a variation on one. */
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 — that an Instagram Story disappears after 24 hours, for instance. Null where there is nothing to add. */
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 — the post outlives the connection, and there is then no token to reach it with. */
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 — several of them are the platform's own words — so branch on which LIST the entry is in, never on this text. */
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 — so `GET /posts/{id}` keeps working and calling retract again takes down what is left. */
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 — the post outlives the connection, and there is then no token to reach it with. */
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 — several of them are the platform's own words — so branch on which LIST the entry is in, never on this text. */
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 — 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". */
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 — what you are describing is how the submission should now read, not a patch against it. */
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 — `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. */
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
- /** @description The platform’s own fields, where `limits.remoteEdit.fields` includes `options`. */
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 — adding or removing a block is `revision_structure_changed`. */
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 — 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. */
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 — call `GET /posts/{id}` and edit what it returns. */
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 — a platform that edits nothing, a field outside its `remoteEdit.fields`, a structural change — is an ERROR instead, because nothing was sent. */
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 — the post outlives the connection, and there is then no token to reach it with. */
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 — several of them are the platform's own words — so branch on which LIST the entry is in, never on this text. */
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 — 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. */
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 — the post outlives the connection, and there is then no token to reach it with. */
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 — several of them are the platform's own words — so branch on which LIST the entry is in, never on this text. */
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 — 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.
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 — 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.
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 — a silent account is a finding, not an absence. */
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 — 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. */
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 — which is what keeps these figures summing to `totals`.
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 — 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.
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 — the names listed in `metrics` on the response.
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 — cumulative since the post went out, not earned during the window.
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 — the denominator. Compare it against the bucket’s `published` before presenting any figure in `values` as a fact about the whole bucket. */
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 — never across tags, which overlap. */
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 — the names listed in `metrics` on the response.
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 — cumulative since the post went out, not earned during the window.
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` — mixing pending work into a window total would produce a number meaning two things at once. */
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 — see the field description on Stats. */
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 — the name is the field a workspace edits.
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 — 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. */
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 — 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.
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 — 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. */
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 — the instant the period figures reset.
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 the monthly allowance is enforced against — the number that will refuse your next write. `published` is what a bill is computed from. */
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: publications that actually reached a platform. Shares `created`’s limit; the allowance is one. */
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 — not "unknown", and not a large number. */
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 — this is what a subscriber dedupes on, and it is also the `id` in the body and the `X-Bulkit-Event-Id` header.
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` — 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.
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 — DNS, TLS, refused, timed out. Your response BODY is never stored or returned. */
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 — never anything your server sent back.
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 — it is returned only when the endpoint is created or its secret is rolled, and no route reads it back. */
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 — either you switched it off, or we did after repeated failures. `disabledReason` tells them apart.
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 — that needs no explanation from us. */
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 — enough to tell which secret a receiver is configured with, after the one time it was shown. */
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 — no operation on this API returns it. */
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 — not when this attempt was sent.
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 — 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. */
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 — `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. */
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` — 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`. */
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;
@@ -2071,7 +2091,16 @@ interface operations {
2071
2091
  'application/json': components['schemas']['Error'];
2072
2092
  };
2073
2093
  };
2074
- /** @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. */
2094
+ /** @description This `Idempotency-Key` was already used with a different request: another route, another id or another body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
2095
+ 422: {
2096
+ headers: {
2097
+ [name: string]: unknown;
2098
+ };
2099
+ content: {
2100
+ 'application/json': components['schemas']['Error'];
2101
+ };
2102
+ };
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. */
2075
2104
  429: {
2076
2105
  headers: {
2077
2106
  /** @description Seconds to wait before retrying. */
@@ -2108,7 +2137,7 @@ interface operations {
2108
2137
  'application/json': components['schemas']['Error'];
2109
2138
  };
2110
2139
  };
2111
- /** @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`. */
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`. */
2112
2141
  503: {
2113
2142
  headers: {
2114
2143
  [name: string]: unknown;
@@ -2183,7 +2212,7 @@ interface operations {
2183
2212
  'application/json': components['schemas']['Error'];
2184
2213
  };
2185
2214
  };
2186
- /** @description This `Idempotency-Key` was already used with a different request body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
2215
+ /** @description This `Idempotency-Key` was already used with a different request: another route, another id or another body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
2187
2216
  422: {
2188
2217
  headers: {
2189
2218
  [name: string]: unknown;
@@ -2192,7 +2221,7 @@ interface operations {
2192
2221
  'application/json': components['schemas']['Error'];
2193
2222
  };
2194
2223
  };
2195
- /** @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. */
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. */
2196
2225
  429: {
2197
2226
  headers: {
2198
2227
  /** @description Seconds to wait before retrying. */
@@ -2229,7 +2258,7 @@ interface operations {
2229
2258
  'application/json': components['schemas']['Error'];
2230
2259
  };
2231
2260
  };
2232
- /** @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`. */
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`. */
2233
2262
  503: {
2234
2263
  headers: {
2235
2264
  [name: string]: unknown;
@@ -2242,20 +2271,34 @@ interface operations {
2242
2271
  };
2243
2272
  PublicMediaController_list: {
2244
2273
  parameters: {
2245
- query?: never;
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
+ };
2246
2280
  header?: never;
2247
2281
  path?: never;
2248
2282
  cookie?: never;
2249
2283
  };
2250
2284
  requestBody?: never;
2251
2285
  responses: {
2252
- /** @description The organization’s library, newest first. */
2286
+ /** @description A page of the organization’s library. */
2253
2287
  200: {
2254
2288
  headers: {
2255
2289
  [name: string]: unknown;
2256
2290
  };
2257
2291
  content: {
2258
- 'application/json': components['schemas']['MediaItem'][];
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'];
2259
2302
  };
2260
2303
  };
2261
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. */
@@ -2267,7 +2310,7 @@ interface operations {
2267
2310
  'application/json': components['schemas']['Error'];
2268
2311
  };
2269
2312
  };
2270
- /** @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. */
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. */
2271
2314
  429: {
2272
2315
  headers: {
2273
2316
  /** @description Seconds to wait before retrying. */
@@ -2295,7 +2338,7 @@ interface operations {
2295
2338
  'application/json': components['schemas']['Error'];
2296
2339
  };
2297
2340
  };
2298
- /** @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`. */
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`. */
2299
2342
  503: {
2300
2343
  headers: {
2301
2344
  [name: string]: unknown;
@@ -2346,7 +2389,7 @@ interface operations {
2346
2389
  'application/json': components['schemas']['Error'];
2347
2390
  };
2348
2391
  };
2349
- /** @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. */
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. */
2350
2393
  402: {
2351
2394
  headers: {
2352
2395
  [name: string]: unknown;
@@ -2364,7 +2407,7 @@ interface operations {
2364
2407
  'application/json': components['schemas']['Error'];
2365
2408
  };
2366
2409
  };
2367
- /** @description `payload_too_large` — an upload past the per-kind ceiling (10 MB for images, 100 MB for video and documents), 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. */
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. */
2368
2411
  413: {
2369
2412
  headers: {
2370
2413
  [name: string]: unknown;
@@ -2373,7 +2416,7 @@ interface operations {
2373
2416
  'application/json': components['schemas']['Error'];
2374
2417
  };
2375
2418
  };
2376
- /** @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. */
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. */
2377
2420
  415: {
2378
2421
  headers: {
2379
2422
  [name: string]: unknown;
@@ -2382,7 +2425,7 @@ interface operations {
2382
2425
  'application/json': components['schemas']['Error'];
2383
2426
  };
2384
2427
  };
2385
- /** @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. */
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. */
2386
2429
  429: {
2387
2430
  headers: {
2388
2431
  /** @description Seconds to wait before retrying. */
@@ -2410,7 +2453,7 @@ interface operations {
2410
2453
  'application/json': components['schemas']['Error'];
2411
2454
  };
2412
2455
  };
2413
- /** @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`. */
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`. */
2414
2457
  503: {
2415
2458
  headers: {
2416
2459
  [name: string]: unknown;
@@ -2426,11 +2469,11 @@ interface operations {
2426
2469
  query?: never;
2427
2470
  header?: {
2428
2471
  /**
2429
- * @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.
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.
2430
2473
  *
2431
- * 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 with a different body is a `422`; a request still running under this key is a `409 request_in_progress`.
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`.
2432
2475
  *
2433
- * 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.
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.
2434
2477
  */
2435
2478
  'Idempotency-Key'?: string;
2436
2479
  };
@@ -2470,7 +2513,7 @@ interface operations {
2470
2513
  'application/json': components['schemas']['Error'];
2471
2514
  };
2472
2515
  };
2473
- /** @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. */
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. */
2474
2517
  402: {
2475
2518
  headers: {
2476
2519
  [name: string]: unknown;
@@ -2488,7 +2531,7 @@ interface operations {
2488
2531
  'application/json': components['schemas']['Error'];
2489
2532
  };
2490
2533
  };
2491
- /** @description `payload_too_large` — an upload past the per-kind ceiling (10 MB for images, 100 MB for video and documents), 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. */
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. */
2492
2535
  413: {
2493
2536
  headers: {
2494
2537
  [name: string]: unknown;
@@ -2497,7 +2540,7 @@ interface operations {
2497
2540
  'application/json': components['schemas']['Error'];
2498
2541
  };
2499
2542
  };
2500
- /** @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. */
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. */
2501
2544
  415: {
2502
2545
  headers: {
2503
2546
  [name: string]: unknown;
@@ -2506,7 +2549,7 @@ interface operations {
2506
2549
  'application/json': components['schemas']['Error'];
2507
2550
  };
2508
2551
  };
2509
- /** @description This `Idempotency-Key` was already used with a different request body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
2552
+ /** @description This `Idempotency-Key` was already used with a different request: another route, another id or another body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
2510
2553
  422: {
2511
2554
  headers: {
2512
2555
  [name: string]: unknown;
@@ -2515,7 +2558,7 @@ interface operations {
2515
2558
  'application/json': components['schemas']['Error'];
2516
2559
  };
2517
2560
  };
2518
- /** @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. */
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. */
2519
2562
  429: {
2520
2563
  headers: {
2521
2564
  /** @description Seconds to wait before retrying. */
@@ -2543,7 +2586,7 @@ interface operations {
2543
2586
  'application/json': components['schemas']['Error'];
2544
2587
  };
2545
2588
  };
2546
- /** @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`. */
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`. */
2547
2590
  503: {
2548
2591
  headers: {
2549
2592
  [name: string]: unknown;
@@ -2600,7 +2643,7 @@ interface operations {
2600
2643
  'application/json': components['schemas']['Error'];
2601
2644
  };
2602
2645
  };
2603
- /** @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. */
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. */
2604
2647
  429: {
2605
2648
  headers: {
2606
2649
  /** @description Seconds to wait before retrying. */
@@ -2628,7 +2671,7 @@ interface operations {
2628
2671
  'application/json': components['schemas']['Error'];
2629
2672
  };
2630
2673
  };
2631
- /** @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`. */
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`. */
2632
2675
  503: {
2633
2676
  headers: {
2634
2677
  [name: string]: unknown;
@@ -2642,7 +2685,16 @@ interface operations {
2642
2685
  PublicMediaController_completeUpload: {
2643
2686
  parameters: {
2644
2687
  query?: never;
2645
- header?: never;
2688
+ header?: {
2689
+ /**
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.
2691
+ *
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`.
2693
+ *
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.
2695
+ */
2696
+ 'Idempotency-Key'?: string;
2697
+ };
2646
2698
  path: {
2647
2699
  /** @description The upload session id. */
2648
2700
  id: string;
@@ -2705,7 +2757,7 @@ interface operations {
2705
2757
  'application/json': components['schemas']['Error'];
2706
2758
  };
2707
2759
  };
2708
- /** @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. */
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. */
2709
2761
  415: {
2710
2762
  headers: {
2711
2763
  [name: string]: unknown;
@@ -2714,7 +2766,16 @@ interface operations {
2714
2766
  'application/json': components['schemas']['Error'];
2715
2767
  };
2716
2768
  };
2717
- /** @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. */
2769
+ /** @description This `Idempotency-Key` was already used with a different request: another route, another id or another body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
2770
+ 422: {
2771
+ headers: {
2772
+ [name: string]: unknown;
2773
+ };
2774
+ content: {
2775
+ 'application/json': components['schemas']['Error'];
2776
+ };
2777
+ };
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. */
2718
2779
  429: {
2719
2780
  headers: {
2720
2781
  /** @description Seconds to wait before retrying. */
@@ -2742,7 +2803,7 @@ interface operations {
2742
2803
  'application/json': components['schemas']['Error'];
2743
2804
  };
2744
2805
  };
2745
- /** @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`. */
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`. */
2746
2807
  503: {
2747
2808
  headers: {
2748
2809
  [name: string]: unknown;
@@ -2814,7 +2875,7 @@ interface operations {
2814
2875
  'application/json': components['schemas']['Error'];
2815
2876
  };
2816
2877
  };
2817
- /** @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. */
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. */
2818
2879
  429: {
2819
2880
  headers: {
2820
2881
  /** @description Seconds to wait before retrying. */
@@ -2842,7 +2903,7 @@ interface operations {
2842
2903
  'application/json': components['schemas']['Error'];
2843
2904
  };
2844
2905
  };
2845
- /** @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`. */
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`. */
2846
2907
  503: {
2847
2908
  headers: {
2848
2909
  [name: string]: unknown;
@@ -2899,7 +2960,7 @@ interface operations {
2899
2960
  'application/json': components['schemas']['Error'];
2900
2961
  };
2901
2962
  };
2902
- /** @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. */
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. */
2903
2964
  429: {
2904
2965
  headers: {
2905
2966
  /** @description Seconds to wait before retrying. */
@@ -2927,7 +2988,7 @@ interface operations {
2927
2988
  'application/json': components['schemas']['Error'];
2928
2989
  };
2929
2990
  };
2930
- /** @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`. */
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`. */
2931
2992
  503: {
2932
2993
  headers: {
2933
2994
  [name: string]: unknown;
@@ -2965,7 +3026,7 @@ interface operations {
2965
3026
  'application/json': components['schemas']['Error'];
2966
3027
  };
2967
3028
  };
2968
- /** @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. */
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. */
2969
3030
  429: {
2970
3031
  headers: {
2971
3032
  /** @description Seconds to wait before retrying. */
@@ -2993,7 +3054,7 @@ interface operations {
2993
3054
  'application/json': components['schemas']['Error'];
2994
3055
  };
2995
3056
  };
2996
- /** @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`. */
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`. */
2997
3058
  503: {
2998
3059
  headers: {
2999
3060
  [name: string]: unknown;
@@ -3007,15 +3068,15 @@ interface operations {
3007
3068
  PublicPostsController_list: {
3008
3069
  parameters: {
3009
3070
  query?: {
3010
- /** @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. */
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. */
3011
3072
  cursor?: unknown;
3012
3073
  /** @description Inclusive start of a scheduling window. */
3013
3074
  from?: string;
3014
3075
  /** @description Page size. Clamped to 100; asking for more is not an error. */
3015
3076
  limit?: number;
3016
- /** @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. */
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. */
3017
3078
  status?: ('draft' | 'scheduled' | 'publishing' | 'published' | 'failed')[];
3018
- /** @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. */
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. */
3019
3080
  tag?: string[];
3020
3081
  /** @description Inclusive end of a scheduling window. */
3021
3082
  to?: string;
@@ -3053,7 +3114,7 @@ interface operations {
3053
3114
  'application/json': components['schemas']['Error'];
3054
3115
  };
3055
3116
  };
3056
- /** @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. */
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. */
3057
3118
  429: {
3058
3119
  headers: {
3059
3120
  /** @description Seconds to wait before retrying. */
@@ -3081,7 +3142,7 @@ interface operations {
3081
3142
  'application/json': components['schemas']['Error'];
3082
3143
  };
3083
3144
  };
3084
- /** @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`. */
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`. */
3085
3146
  503: {
3086
3147
  headers: {
3087
3148
  [name: string]: unknown;
@@ -3097,11 +3158,11 @@ interface operations {
3097
3158
  query?: never;
3098
3159
  header?: {
3099
3160
  /**
3100
- * @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.
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.
3101
3162
  *
3102
- * 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 with a different body is a `422`; a request still running under this key is a `409 request_in_progress`.
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`.
3103
3164
  *
3104
- * 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.
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.
3105
3166
  */
3106
3167
  'Idempotency-Key'?: string;
3107
3168
  };
@@ -3141,7 +3202,7 @@ interface operations {
3141
3202
  'application/json': components['schemas']['Error'];
3142
3203
  };
3143
3204
  };
3144
- /** @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. */
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. */
3145
3206
  402: {
3146
3207
  headers: {
3147
3208
  [name: string]: unknown;
@@ -3159,7 +3220,7 @@ interface operations {
3159
3220
  'application/json': components['schemas']['Error'];
3160
3221
  };
3161
3222
  };
3162
- /** @description `payload_too_large` — an upload past the per-kind ceiling (10 MB for images, 100 MB for video and documents), 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. */
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. */
3163
3224
  413: {
3164
3225
  headers: {
3165
3226
  [name: string]: unknown;
@@ -3168,7 +3229,7 @@ interface operations {
3168
3229
  'application/json': components['schemas']['Error'];
3169
3230
  };
3170
3231
  };
3171
- /** @description This `Idempotency-Key` was already used with a different request body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
3232
+ /** @description This `Idempotency-Key` was already used with a different request: another route, another id or another body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
3172
3233
  422: {
3173
3234
  headers: {
3174
3235
  [name: string]: unknown;
@@ -3177,7 +3238,7 @@ interface operations {
3177
3238
  'application/json': components['schemas']['Error'];
3178
3239
  };
3179
3240
  };
3180
- /** @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. */
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. */
3181
3242
  429: {
3182
3243
  headers: {
3183
3244
  /** @description Seconds to wait before retrying. */
@@ -3205,7 +3266,7 @@ interface operations {
3205
3266
  'application/json': components['schemas']['Error'];
3206
3267
  };
3207
3268
  };
3208
- /** @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`. */
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`. */
3209
3270
  503: {
3210
3271
  headers: {
3211
3272
  [name: string]: unknown;
@@ -3255,7 +3316,7 @@ interface operations {
3255
3316
  'application/json': components['schemas']['Error'];
3256
3317
  };
3257
3318
  };
3258
- /** @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. */
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. */
3259
3320
  429: {
3260
3321
  headers: {
3261
3322
  /** @description Seconds to wait before retrying. */
@@ -3283,7 +3344,7 @@ interface operations {
3283
3344
  'application/json': components['schemas']['Error'];
3284
3345
  };
3285
3346
  };
3286
- /** @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`. */
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`. */
3287
3348
  503: {
3288
3349
  headers: {
3289
3350
  [name: string]: unknown;
@@ -3299,11 +3360,11 @@ interface operations {
3299
3360
  query?: never;
3300
3361
  header?: {
3301
3362
  /**
3302
- * @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.
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.
3303
3364
  *
3304
- * 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 with a different body is a `422`; a request still running under this key is a `409 request_in_progress`.
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`.
3305
3366
  *
3306
- * 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.
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.
3307
3368
  */
3308
3369
  'Idempotency-Key'?: string;
3309
3370
  };
@@ -3346,7 +3407,7 @@ interface operations {
3346
3407
  'application/json': components['schemas']['Error'];
3347
3408
  };
3348
3409
  };
3349
- /** @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. */
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. */
3350
3411
  402: {
3351
3412
  headers: {
3352
3413
  [name: string]: unknown;
@@ -3382,7 +3443,7 @@ interface operations {
3382
3443
  'application/json': components['schemas']['Error'];
3383
3444
  };
3384
3445
  };
3385
- /** @description `payload_too_large` — an upload past the per-kind ceiling (10 MB for images, 100 MB for video and documents), 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. */
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. */
3386
3447
  413: {
3387
3448
  headers: {
3388
3449
  [name: string]: unknown;
@@ -3391,7 +3452,7 @@ interface operations {
3391
3452
  'application/json': components['schemas']['Error'];
3392
3453
  };
3393
3454
  };
3394
- /** @description This `Idempotency-Key` was already used with a different request body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
3455
+ /** @description This `Idempotency-Key` was already used with a different request: another route, another id or another body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
3395
3456
  422: {
3396
3457
  headers: {
3397
3458
  [name: string]: unknown;
@@ -3400,7 +3461,7 @@ interface operations {
3400
3461
  'application/json': components['schemas']['Error'];
3401
3462
  };
3402
3463
  };
3403
- /** @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. */
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. */
3404
3465
  429: {
3405
3466
  headers: {
3406
3467
  /** @description Seconds to wait before retrying. */
@@ -3428,7 +3489,7 @@ interface operations {
3428
3489
  'application/json': components['schemas']['Error'];
3429
3490
  };
3430
3491
  };
3431
- /** @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`. */
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`. */
3432
3493
  503: {
3433
3494
  headers: {
3434
3495
  [name: string]: unknown;
@@ -3485,7 +3546,7 @@ interface operations {
3485
3546
  'application/json': components['schemas']['Error'];
3486
3547
  };
3487
3548
  };
3488
- /** @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. */
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. */
3489
3550
  429: {
3490
3551
  headers: {
3491
3552
  /** @description Seconds to wait before retrying. */
@@ -3513,7 +3574,7 @@ interface operations {
3513
3574
  'application/json': components['schemas']['Error'];
3514
3575
  };
3515
3576
  };
3516
- /** @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`. */
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`. */
3517
3578
  503: {
3518
3579
  headers: {
3519
3580
  [name: string]: unknown;
@@ -3586,7 +3647,7 @@ interface operations {
3586
3647
  'application/json': components['schemas']['Error'];
3587
3648
  };
3588
3649
  };
3589
- /** @description This `Idempotency-Key` was already used with a different request body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
3650
+ /** @description This `Idempotency-Key` was already used with a different request: another route, another id or another body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
3590
3651
  422: {
3591
3652
  headers: {
3592
3653
  [name: string]: unknown;
@@ -3595,7 +3656,7 @@ interface operations {
3595
3656
  'application/json': components['schemas']['Error'];
3596
3657
  };
3597
3658
  };
3598
- /** @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. */
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. */
3599
3660
  429: {
3600
3661
  headers: {
3601
3662
  /** @description Seconds to wait before retrying. */
@@ -3632,7 +3693,7 @@ interface operations {
3632
3693
  'application/json': components['schemas']['Error'];
3633
3694
  };
3634
3695
  };
3635
- /** @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`. */
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`. */
3636
3697
  503: {
3637
3698
  headers: {
3638
3699
  [name: string]: unknown;
@@ -3648,11 +3709,11 @@ interface operations {
3648
3709
  query?: never;
3649
3710
  header?: {
3650
3711
  /**
3651
- * @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.
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.
3652
3713
  *
3653
- * 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 with a different body is a `422`; a request still running under this key is a `409 request_in_progress`.
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`.
3654
3715
  *
3655
- * 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.
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.
3656
3717
  */
3657
3718
  'Idempotency-Key'?: string;
3658
3719
  };
@@ -3697,7 +3758,7 @@ interface operations {
3697
3758
  'application/json': components['schemas']['Error'];
3698
3759
  };
3699
3760
  };
3700
- /** @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. */
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. */
3701
3762
  402: {
3702
3763
  headers: {
3703
3764
  [name: string]: unknown;
@@ -3733,7 +3794,7 @@ interface operations {
3733
3794
  'application/json': components['schemas']['Error'];
3734
3795
  };
3735
3796
  };
3736
- /** @description This `Idempotency-Key` was already used with a different request body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
3797
+ /** @description This `Idempotency-Key` was already used with a different request: another route, another id or another body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
3737
3798
  422: {
3738
3799
  headers: {
3739
3800
  [name: string]: unknown;
@@ -3742,7 +3803,7 @@ interface operations {
3742
3803
  'application/json': components['schemas']['Error'];
3743
3804
  };
3744
3805
  };
3745
- /** @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. */
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. */
3746
3807
  429: {
3747
3808
  headers: {
3748
3809
  /** @description Seconds to wait before retrying. */
@@ -3779,7 +3840,7 @@ interface operations {
3779
3840
  'application/json': components['schemas']['Error'];
3780
3841
  };
3781
3842
  };
3782
- /** @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`. */
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`. */
3783
3844
  503: {
3784
3845
  headers: {
3785
3846
  [name: string]: unknown;
@@ -3829,7 +3890,7 @@ interface operations {
3829
3890
  'application/json': components['schemas']['Error'];
3830
3891
  };
3831
3892
  };
3832
- /** @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. */
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. */
3833
3894
  429: {
3834
3895
  headers: {
3835
3896
  /** @description Seconds to wait before retrying. */
@@ -3857,7 +3918,7 @@ interface operations {
3857
3918
  'application/json': components['schemas']['Error'];
3858
3919
  };
3859
3920
  };
3860
- /** @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`. */
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`. */
3861
3922
  503: {
3862
3923
  headers: {
3863
3924
  [name: string]: unknown;
@@ -3873,11 +3934,11 @@ interface operations {
3873
3934
  query?: never;
3874
3935
  header?: {
3875
3936
  /**
3876
- * @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.
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.
3877
3938
  *
3878
- * 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 with a different body is a `422`; a request still running under this key is a `409 request_in_progress`.
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`.
3879
3940
  *
3880
- * 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.
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.
3881
3942
  */
3882
3943
  'Idempotency-Key'?: string;
3883
3944
  };
@@ -3889,7 +3950,7 @@ interface operations {
3889
3950
  };
3890
3951
  requestBody?: never;
3891
3952
  responses: {
3892
- /** @description The submission, with the queued channels now `publishing`. 201 rather than 200 — the framework default for POST; nothing new was created. */
3953
+ /** @description The submission, with the queued channels now `publishing`. 201 rather than 200 (the framework default for POST); nothing new was created. */
3893
3954
  201: {
3894
3955
  headers: {
3895
3956
  [name: string]: unknown;
@@ -3916,7 +3977,7 @@ interface operations {
3916
3977
  'application/json': components['schemas']['Error'];
3917
3978
  };
3918
3979
  };
3919
- /** @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. */
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. */
3920
3981
  402: {
3921
3982
  headers: {
3922
3983
  [name: string]: unknown;
@@ -3952,7 +4013,7 @@ interface operations {
3952
4013
  'application/json': components['schemas']['Error'];
3953
4014
  };
3954
4015
  };
3955
- /** @description This `Idempotency-Key` was already used with a different request body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
4016
+ /** @description This `Idempotency-Key` was already used with a different request: another route, another id or another body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
3956
4017
  422: {
3957
4018
  headers: {
3958
4019
  [name: string]: unknown;
@@ -3961,7 +4022,7 @@ interface operations {
3961
4022
  'application/json': components['schemas']['Error'];
3962
4023
  };
3963
4024
  };
3964
- /** @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. */
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. */
3965
4026
  429: {
3966
4027
  headers: {
3967
4028
  /** @description Seconds to wait before retrying. */
@@ -3989,7 +4050,7 @@ interface operations {
3989
4050
  'application/json': components['schemas']['Error'];
3990
4051
  };
3991
4052
  };
3992
- /** @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`. */
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`. */
3993
4054
  503: {
3994
4055
  headers: {
3995
4056
  [name: string]: unknown;
@@ -4057,7 +4118,7 @@ interface operations {
4057
4118
  'application/json': components['schemas']['Error'];
4058
4119
  };
4059
4120
  };
4060
- /** @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. */
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. */
4061
4122
  429: {
4062
4123
  headers: {
4063
4124
  /** @description Seconds to wait before retrying. */
@@ -4085,7 +4146,7 @@ interface operations {
4085
4146
  'application/json': components['schemas']['Error'];
4086
4147
  };
4087
4148
  };
4088
- /** @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`. */
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`. */
4089
4150
  503: {
4090
4151
  headers: {
4091
4152
  [name: string]: unknown;
@@ -4166,7 +4227,7 @@ interface operations {
4166
4227
  'application/json': components['schemas']['Error'];
4167
4228
  };
4168
4229
  };
4169
- /** @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. */
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. */
4170
4231
  429: {
4171
4232
  headers: {
4172
4233
  /** @description Seconds to wait before retrying. */
@@ -4194,7 +4255,7 @@ interface operations {
4194
4255
  'application/json': components['schemas']['Error'];
4195
4256
  };
4196
4257
  };
4197
- /** @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`. */
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`. */
4198
4259
  503: {
4199
4260
  headers: {
4200
4261
  [name: string]: unknown;
@@ -4248,7 +4309,7 @@ interface operations {
4248
4309
  'application/json': components['schemas']['Error'];
4249
4310
  };
4250
4311
  };
4251
- /** @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. */
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. */
4252
4313
  429: {
4253
4314
  headers: {
4254
4315
  /** @description Seconds to wait before retrying. */
@@ -4276,7 +4337,7 @@ interface operations {
4276
4337
  'application/json': components['schemas']['Error'];
4277
4338
  };
4278
4339
  };
4279
- /** @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`. */
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`. */
4280
4341
  503: {
4281
4342
  headers: {
4282
4343
  [name: string]: unknown;
@@ -4336,7 +4397,7 @@ interface operations {
4336
4397
  'application/json': components['schemas']['Error'];
4337
4398
  };
4338
4399
  };
4339
- /** @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. */
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. */
4340
4401
  429: {
4341
4402
  headers: {
4342
4403
  /** @description Seconds to wait before retrying. */
@@ -4364,7 +4425,7 @@ interface operations {
4364
4425
  'application/json': components['schemas']['Error'];
4365
4426
  };
4366
4427
  };
4367
- /** @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`. */
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`. */
4368
4429
  503: {
4369
4430
  headers: {
4370
4431
  [name: string]: unknown;
@@ -4402,7 +4463,7 @@ interface operations {
4402
4463
  'application/json': components['schemas']['Error'];
4403
4464
  };
4404
4465
  };
4405
- /** @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. */
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. */
4406
4467
  429: {
4407
4468
  headers: {
4408
4469
  /** @description Seconds to wait before retrying. */
@@ -4430,7 +4491,7 @@ interface operations {
4430
4491
  'application/json': components['schemas']['Error'];
4431
4492
  };
4432
4493
  };
4433
- /** @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`. */
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`. */
4434
4495
  503: {
4435
4496
  headers: {
4436
4497
  [name: string]: unknown;
@@ -4477,7 +4538,7 @@ interface operations {
4477
4538
  'application/json': components['schemas']['Error'];
4478
4539
  };
4479
4540
  };
4480
- /** @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. */
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. */
4481
4542
  429: {
4482
4543
  headers: {
4483
4544
  /** @description Seconds to wait before retrying. */
@@ -4505,7 +4566,7 @@ interface operations {
4505
4566
  'application/json': components['schemas']['Error'];
4506
4567
  };
4507
4568
  };
4508
- /** @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`. */
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`. */
4509
4570
  503: {
4510
4571
  headers: {
4511
4572
  [name: string]: unknown;
@@ -4543,7 +4604,7 @@ interface operations {
4543
4604
  'application/json': components['schemas']['Error'];
4544
4605
  };
4545
4606
  };
4546
- /** @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. */
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. */
4547
4608
  429: {
4548
4609
  headers: {
4549
4610
  /** @description Seconds to wait before retrying. */
@@ -4571,7 +4632,7 @@ interface operations {
4571
4632
  'application/json': components['schemas']['Error'];
4572
4633
  };
4573
4634
  };
4574
- /** @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`. */
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`. */
4575
4636
  503: {
4576
4637
  headers: {
4577
4638
  [name: string]: unknown;
@@ -4587,11 +4648,11 @@ interface operations {
4587
4648
  query?: never;
4588
4649
  header?: {
4589
4650
  /**
4590
- * @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.
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.
4591
4652
  *
4592
- * 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 with a different body is a `422`; a request still running under this key is a `409 request_in_progress`.
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`.
4593
4654
  *
4594
- * 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.
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.
4595
4656
  */
4596
4657
  'Idempotency-Key'?: string;
4597
4658
  };
@@ -4640,7 +4701,7 @@ interface operations {
4640
4701
  'application/json': components['schemas']['Error'];
4641
4702
  };
4642
4703
  };
4643
- /** @description This `Idempotency-Key` was already used with a different request body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
4704
+ /** @description This `Idempotency-Key` was already used with a different request: another route, another id or another body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
4644
4705
  422: {
4645
4706
  headers: {
4646
4707
  [name: string]: unknown;
@@ -4649,7 +4710,7 @@ interface operations {
4649
4710
  'application/json': components['schemas']['Error'];
4650
4711
  };
4651
4712
  };
4652
- /** @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. */
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. */
4653
4714
  429: {
4654
4715
  headers: {
4655
4716
  /** @description Seconds to wait before retrying. */
@@ -4677,7 +4738,7 @@ interface operations {
4677
4738
  'application/json': components['schemas']['Error'];
4678
4739
  };
4679
4740
  };
4680
- /** @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`. */
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`. */
4681
4742
  503: {
4682
4743
  headers: {
4683
4744
  [name: string]: unknown;
@@ -4727,7 +4788,7 @@ interface operations {
4727
4788
  'application/json': components['schemas']['Error'];
4728
4789
  };
4729
4790
  };
4730
- /** @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. */
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. */
4731
4792
  429: {
4732
4793
  headers: {
4733
4794
  /** @description Seconds to wait before retrying. */
@@ -4755,7 +4816,7 @@ interface operations {
4755
4816
  'application/json': components['schemas']['Error'];
4756
4817
  };
4757
4818
  };
4758
- /** @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`. */
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`. */
4759
4820
  503: {
4760
4821
  headers: {
4761
4822
  [name: string]: unknown;
@@ -4771,11 +4832,11 @@ interface operations {
4771
4832
  query?: never;
4772
4833
  header?: {
4773
4834
  /**
4774
- * @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.
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.
4775
4836
  *
4776
- * 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 with a different body is a `422`; a request still running under this key is a `409 request_in_progress`.
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`.
4777
4838
  *
4778
- * 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.
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.
4779
4840
  */
4780
4841
  'Idempotency-Key'?: string;
4781
4842
  };
@@ -4836,7 +4897,7 @@ interface operations {
4836
4897
  'application/json': components['schemas']['Error'];
4837
4898
  };
4838
4899
  };
4839
- /** @description This `Idempotency-Key` was already used with a different request body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
4900
+ /** @description This `Idempotency-Key` was already used with a different request: another route, another id or another body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
4840
4901
  422: {
4841
4902
  headers: {
4842
4903
  [name: string]: unknown;
@@ -4845,7 +4906,7 @@ interface operations {
4845
4906
  'application/json': components['schemas']['Error'];
4846
4907
  };
4847
4908
  };
4848
- /** @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. */
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. */
4849
4910
  429: {
4850
4911
  headers: {
4851
4912
  /** @description Seconds to wait before retrying. */
@@ -4873,7 +4934,7 @@ interface operations {
4873
4934
  'application/json': components['schemas']['Error'];
4874
4935
  };
4875
4936
  };
4876
- /** @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`. */
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`. */
4877
4938
  503: {
4878
4939
  headers: {
4879
4940
  [name: string]: unknown;
@@ -4930,7 +4991,7 @@ interface operations {
4930
4991
  'application/json': components['schemas']['Error'];
4931
4992
  };
4932
4993
  };
4933
- /** @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. */
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. */
4934
4995
  429: {
4935
4996
  headers: {
4936
4997
  /** @description Seconds to wait before retrying. */
@@ -4958,7 +5019,7 @@ interface operations {
4958
5019
  'application/json': components['schemas']['Error'];
4959
5020
  };
4960
5021
  };
4961
- /** @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`. */
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`. */
4962
5023
  503: {
4963
5024
  headers: {
4964
5025
  [name: string]: unknown;
@@ -5022,7 +5083,7 @@ interface operations {
5022
5083
  'application/json': components['schemas']['Error'];
5023
5084
  };
5024
5085
  };
5025
- /** @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. */
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. */
5026
5087
  429: {
5027
5088
  headers: {
5028
5089
  /** @description Seconds to wait before retrying. */
@@ -5050,7 +5111,7 @@ interface operations {
5050
5111
  'application/json': components['schemas']['Error'];
5051
5112
  };
5052
5113
  };
5053
- /** @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`. */
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`. */
5054
5115
  503: {
5055
5116
  headers: {
5056
5117
  [name: string]: unknown;
@@ -5066,11 +5127,11 @@ interface operations {
5066
5127
  query?: never;
5067
5128
  header?: {
5068
5129
  /**
5069
- * @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.
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.
5070
5131
  *
5071
- * 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 with a different body is a `422`; a request still running under this key is a `409 request_in_progress`.
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`.
5072
5133
  *
5073
- * 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.
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.
5074
5135
  */
5075
5136
  'Idempotency-Key'?: string;
5076
5137
  };
@@ -5082,7 +5143,7 @@ interface operations {
5082
5143
  };
5083
5144
  requestBody?: never;
5084
5145
  responses: {
5085
- /** @description The endpoint with its new secret. 201 rather than 200 — the framework default for POST; nothing new was created. */
5146
+ /** @description The endpoint with its new secret. 201 rather than 200 (the framework default for POST); nothing new was created. */
5086
5147
  201: {
5087
5148
  headers: {
5088
5149
  [name: string]: unknown;
@@ -5118,7 +5179,7 @@ interface operations {
5118
5179
  'application/json': components['schemas']['Error'];
5119
5180
  };
5120
5181
  };
5121
- /** @description This `Idempotency-Key` was already used with a different request body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
5182
+ /** @description This `Idempotency-Key` was already used with a different request: another route, another id or another body (`error.field` is `Idempotency-Key`). Replaying the stored response would silently discard what you just asked for, so it is refused instead. `platform_refused`: the platform understood the call and said no, in the words of the message (comments turned off on the post, a locked thread, an app access level that can’t search). The same call will be refused again. */
5122
5183
  422: {
5123
5184
  headers: {
5124
5185
  [name: string]: unknown;
@@ -5127,7 +5188,7 @@ interface operations {
5127
5188
  'application/json': components['schemas']['Error'];
5128
5189
  };
5129
5190
  };
5130
- /** @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. */
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. */
5131
5192
  429: {
5132
5193
  headers: {
5133
5194
  /** @description Seconds to wait before retrying. */
@@ -5155,7 +5216,7 @@ interface operations {
5155
5216
  'application/json': components['schemas']['Error'];
5156
5217
  };
5157
5218
  };
5158
- /** @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`. */
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`. */
5159
5220
  503: {
5160
5221
  headers: {
5161
5222
  [name: string]: unknown;
@@ -5214,7 +5275,7 @@ interface operations {
5214
5275
  'application/json': components['schemas']['Error'];
5215
5276
  };
5216
5277
  };
5217
- /** @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. */
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. */
5218
5279
  429: {
5219
5280
  headers: {
5220
5281
  /** @description Seconds to wait before retrying. */
@@ -5242,7 +5303,7 @@ interface operations {
5242
5303
  'application/json': components['schemas']['Error'];
5243
5304
  };
5244
5305
  };
5245
- /** @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`. */
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`. */
5246
5307
  503: {
5247
5308
  headers: {
5248
5309
  [name: string]: unknown;
@@ -5288,6 +5349,7 @@ type CommentReply = Schemas['CommentReply'];
5288
5349
  type CommentListParams = WithStrings<QueryOf<'PublicPostsController_listComments'>, 'channelId' | 'cursor'>;
5289
5350
  type CommentReplyParams = Schemas['ReplyToCommentRequest'];
5290
5351
  type MediaItem = Schemas['MediaItem'];
5352
+ type MediaListParams = WithStrings<QueryOf<'PublicMediaController_list'>, 'cursor'>;
5291
5353
  type MediaUpload = Schemas['MediaUpload'];
5292
5354
  type MediaUploadPart = Schemas['MediaUploadPart'];
5293
5355
  type MediaUploadStartParams = Schemas['StartMediaUploadRequest'];
@@ -5351,8 +5413,15 @@ interface MultipartUploadParams extends MediaUploadParams {
5351
5413
  declare class Media extends APIResource {
5352
5414
  #private;
5353
5415
  readonly uploads: MediaUploads;
5354
- /** The workspace's media library. */
5355
- list(options?: RequestOptions): APIPromise<MediaItem[]>;
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>;
5356
5425
  /**
5357
5426
  * Upload a file in one request: images up to 10 MB, video and PDFs up to 100 MB,
5358
5427
  * subtitles up to 5 MB. For larger video, use `uploadMultipart()`.
@@ -5361,6 +5430,9 @@ declare class Media extends APIResource {
5361
5430
  /**
5362
5431
  * Upload a large video through an upload session: start it, PUT every part to its
5363
5432
  * signed URL, then complete it. The session is aborted if any step fails.
5433
+ *
5434
+ * An `idempotencyKey` passed here is split per step (`<key>:start`, `<key>:complete`),
5435
+ * since the API holds a key to one route. Keep it under 246 characters so both fit.
5364
5436
  */
5365
5437
  uploadMultipart(file: Uploadable, params?: MultipartUploadParams, options?: RequestOptions): Promise<MediaItem>;
5366
5438
  /** Delete a file from the media library. */
@@ -5705,7 +5777,7 @@ export declare class WebhookVerificationError extends BulkitError {
5705
5777
  }
5706
5778
  //#endregion
5707
5779
  //#region src/version.d.ts
5708
- export declare const VERSION = "0.1.0";
5780
+ export declare const VERSION = "0.2.0";
5709
5781
  //#endregion
5710
- 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 };
5711
5783
  //# sourceMappingURL=index.d.ts.map