docs(GEN-6844): editing a post that is already live

Closes GEN-6844.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: tess

public/llms-full.txt

@@ -1091,6 +1091,26 @@ PATCH  /v1/schedule/post/{post_id}   // same content fields as create + schedule
 DELETE /v1/schedule/post/{post_id}
 ```
 
+### Edit a post that is already live
+
+```
+PATCH /v1/schedule/post/{post_id}/published
+{ "description": "Corrected sourcing figures in the pinned comment." }
+→ { "post_id": 48213,
+    "results": [ { "platform": "youtube", "platform_post_id": "dQw4w9WgXcQ", "result": "updated",
+                   "updated_fields": ["description"], "quota_units": 50,
+                   "metadata": { "title": "Factory price reveal", "description": "Corrected sourcing figures...",
+                                 "tags": ["sourcing","beauty"], "category_id": 22 } } ] }
+```
+
+Editable fields per platform come from `editable_after_publish` in `GET /v1/schedule/platforms`. Today: **YouTube** `title` (≤100, not blank), `description` (≤5,000 **bytes**, not characters; explicit `null` clears it), `tags` (each 2+ chars, ≤400 chars total), `category_id` (positive int). Every other platform is `[]` — TikTok, Instagram and Facebook have no post-publication edit for this content, editing a sent tweet is a paid X plan feature, and LinkedIn's `commentary` PARTIAL_UPDATE is not wired yet.
+
+**Sparse and idempotent.** Only the fields in the body change. GEN reads the platform's current metadata, merges the change onto it and writes it back, so an unsent title is never cleared and the same request twice converges rather than stacking. `metadata` is read back *from the platform* after the write, not echoed from the request.
+
+`result` per platform: `updated` · `unsupported_after_publish` (that network has no edit path; nothing was touched — not an auth error) · `reauthorization_required` (GEN's saved authorization can no longer edit it; reconnect via GEN app → Setup → Accounts) · `failed` (`message` carries the platform's reason, e.g. `quotaExceeded`).
+
+`422`: `post_not_published` (it has not gone out — use `PATCH /v1/schedule/post/{post_id}`), an empty body, or `platform_validation_failed` naming the `field` (a field the platform cannot change after publishing, or one over its limit). Each YouTube update costs 50 units of the connected channel's YouTube API quota.
+
 ### Upload media (upload_asset)
 
 Posts reference media by URL (public at post time; a render URL works directly). Upload a local file to get a hosted URL, also saved to the agent's Assets.

public/llms.txt

@@ -551,6 +551,15 @@ curl "https://api.gen.pro/v1/schedule/post/48213" -H "X-API-Key: $GEN_API_KEY"
 # published: platform_post_id + post_url (the live link). failed: error, error_code, failed_step.
 ```
 
+**Already live and wrong?** `PATCH /v1/schedule/post/:post_id/published` edits a published post's metadata where the network supports it — today YouTube `title`, `description`, `tags`, `category_id`. Sparse: only the fields you send change, everything else on the live post is preserved, and the same request twice converges instead of stacking. The reply is one result per platform — `updated` (with the platform's readback), `unsupported_after_publish` (that network has no edit path; nothing touched), `reauthorization_required` (reconnect the account) or `failed`. `editable_after_publish` in `GET /v1/schedule/platforms` names the editable fields per platform. Each YouTube update costs 50 units of the channel's YouTube quota. For a post that has *not* gone out yet, use `PATCH /v1/schedule/post/:post_id` instead.
+
+```bash
+curl -X PATCH "https://api.gen.pro/v1/schedule/post/48213/published" -H "X-API-Key: $GEN_API_KEY" \
+  -H "Content-Type: application/json" -d '{"description": "Corrected sourcing figures in the pinned comment."}'
+# { "post_id": 48213, "results": [ { "platform": "youtube", "result": "updated",
+#   "updated_fields": ["description"], "metadata": {...}, "quota_units": 50 } ] }
+```
+
 **Limits that bite:** X 280 chars/tweet + max 4 images; YouTube title required (≤100), description ≤5,000, `thumbnail_url` https .jpg/.png <2 MB; TikTok/Instagram 2,200 (Instagram ≤30 hashtags, 2-10 items = carousel); LinkedIn 3,000, ≤9 images or one PDF/PPTX/DOCX document, no mixing; Facebook video only. Instagram/TikTok/Facebook/YouTube need media; X and LinkedIn allow text-only. Per-platform knobs: `instagram_music`, `youtube_options` (visibility, shorts, tags), `linkedin_options` (visibility, alt_text, carousel = PDF of the images; several images alone render as a grid). A 422 `platform_validation_failed` names the `platform` and `field` (dotted for options). `GET /v1/schedule/platforms` (no auth) serves the rules incl. each `options` object.
 
 **Prerequisites for publish.** The agent must have connected the platform (GEN app → Setup → Accounts, or MCP `gen_get_social_connect_url`). Media URLs must be publicly accessible at post time.
@@ -564,7 +573,8 @@ GET    /v1/schedule/platforms                                       — per-plat
 POST   /v1/schedule/with-post                                       — publish now / schedule (all platforms)
 GET    /v1/schedule/post/:post_id                                   — outcome per platform + post_url
 GET    /v1/schedule/posts?agent_id=&start_date=&end_date=           — content calendar
-PATCH  /v1/schedule/post/:post_id · DELETE /v1/schedule/post/:post_id
+PATCH  /v1/schedule/post/:post_id · DELETE /v1/schedule/post/:post_id — before it goes out
+PATCH  /v1/schedule/post/:post_id/published                         — edit a LIVE post's metadata (YouTube)
 POST   /v1/social/upload_asset                                      — upload a local file → hosted URL
 ```
 

public/openapi.yaml

@@ -2178,6 +2178,111 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
+  /schedule/post/{post_id}/published:
+    parameters:
+      - name: post_id
+        in: path
+        required: true
+        description: The `post_id` of a post that has already published.
+        schema:
+          type: integer
+    patch:
+      operationId: updatePublishedPost
+      x-phase: [export]
+      summary: Edit the metadata of a post that is already live
+      description: |
+        Change a published post's metadata where the destination network supports it — today, a YouTube video's `title`, `description`, `tags` and `category_id`. `GET /schedule/platforms` names the editable fields per platform in `editable_after_publish`.
+
+        The edit is **sparse**: only the fields in the request body change. GEN reads the platform's current metadata, merges your change onto it, writes it back, and returns what the platform held afterwards — so a title you did not send is not cleared, and the same request sent twice converges on the same result rather than stacking edits.
+
+        The response is `200` with one result per platform the post went out on, each `updated`, `unsupported_after_publish`, `reauthorization_required` or `failed`. A network with no edit path is reported as `unsupported_after_publish` and nothing is touched; it is never an authentication error. A `422` means the body itself is wrong — a field the platform cannot change after publishing, or one that breaks the platform's limits.
+
+        Use `PATCH /schedule/post/{post_id}` for a post that has **not** gone out yet; that endpoint still refuses published posts.
+
+        Each YouTube update consumes 50 units of the connected channel's YouTube API quota.
+      tags: [Publishing]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PublishedPostUpdate'
+            examples:
+              fixDescription:
+                summary: Fix a typo in a live YouTube description
+                value:
+                  description: "What your $12 beauty sponge really costs — corrected sourcing figures in the pinned comment."
+              retitleAndRetag:
+                summary: Retitle, retag and recategorise
+                value:
+                  title: "Factory price reveal (2026 update)"
+                  tags: [sourcing, beauty, supply chain]
+                  category_id: 24
+      responses:
+        '200':
+          description: One result per platform the post published to.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PublishedPostUpdateResponse'
+              examples:
+                updated:
+                  summary: YouTube accepted the edit
+                  value:
+                    post_id: 120750
+                    results:
+                      - platform: youtube
+                        platform_post_id: "dQw4w9WgXcQ"
+                        result: updated
+                        updated_fields: [description]
+                        metadata:
+                          title: "Factory price reveal"
+                          description: "What your $12 beauty sponge really costs — corrected sourcing figures in the pinned comment."
+                          tags: [sourcing, beauty]
+                          category_id: 22
+                        quota_units: 50
+                unsupported:
+                  summary: The platform has no post-publication edit
+                  value:
+                    post_id: 120751
+                    results:
+                      - platform: tiktok
+                        platform_post_id: "7412..."
+                        result: unsupported_after_publish
+                        message: "tiktok has no supported post-publication edit for this content."
+                reauthorization:
+                  summary: The connected account must be reconnected
+                  value:
+                    post_id: 120750
+                    results:
+                      - platform: youtube
+                        platform_post_id: "dQw4w9WgXcQ"
+                        result: reauthorization_required
+                        message: "Reconnect the YouTube account: GEN's saved authorization is no longer usable."
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: You do not have permission to edit this post.
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '422':
+          description: |
+            The post has not published yet (`post_not_published`), the body is empty, or a field is not editable after publishing / breaks the platform's limits (`platform_validation_failed`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlatformValidationError'
+              example:
+                detail:
+                  error: "YouTube cannot change visibility after publishing"
+                  error_code: platform_validation_failed
+                  platform: youtube
+                  field: visibility
+                  errors:
+                    - platform: youtube
+                      field: visibility
+                      error: "YouTube cannot change visibility after publishing"
+
   /templates/projects:
     get:
       operationId: listTemplates
@@ -5430,9 +5535,82 @@ components:
             linkedin_options:
               visibility: "public (default) | connections | loggedin"
               alt_text: "string[] — alternative text per image, in media order (images only)"
+        editable_after_publish:
+          type: array
+          description: |
+            Fields `PATCH /schedule/post/{post_id}/published` can still change once the post is live. Empty means the network has no supported post-publication edit and that endpoint answers `unsupported_after_publish` for it.
+          items:
+            type: string
+          example: [title, description, tags, category_id]
         notes:
           type: string
 
+    PublishedPostUpdate:
+      type: object
+      description: |
+        A sparse metadata edit for a post that has already published. Send only the fields you want changed; every other field on the live post is preserved. At least one field is required.
+      minProperties: 1
+      properties:
+        title:
+          type: string
+          description: New title. YouTube allows up to 100 characters and rejects a blank title.
+        description:
+          type: string
+          description: |
+            New description / caption. YouTube allows up to 5,000 **bytes** (not characters — emoji and CJK cost several bytes each). An explicit `null` clears the description.
+        tags:
+          type: array
+          description: YouTube only — replaces the video's tags. Each tag is 2+ characters and all tags together are at most 400 characters.
+          items:
+            type: string
+        category_id:
+          type: integer
+          description: YouTube only — video category ID (for example 22 People & Blogs, 24 Entertainment).
+
+    PublishedPostUpdateResult:
+      type: object
+      properties:
+        platform:
+          $ref: '#/components/schemas/PublishPlatform'
+        platform_post_id:
+          type: string
+          nullable: true
+          description: The platform's own ID for the live post (a YouTube video ID).
+        result:
+          type: string
+          enum: [updated, unsupported_after_publish, reauthorization_required, failed]
+          description: |
+            `updated` — the platform accepted the edit and `metadata` is what it holds now.
+            `unsupported_after_publish` — this network has no post-publication edit for this content; nothing was touched.
+            `reauthorization_required` — GEN's saved authorization for this account can no longer edit the post; the user must reconnect it (GEN app → Setup → Accounts).
+            `failed` — the platform rejected the edit; `message` carries its reason.
+        updated_fields:
+          type: array
+          description: Present on `updated` — the fields that were sent to the platform.
+          items:
+            type: string
+        metadata:
+          type: object
+          description: Present on `updated` — the metadata read back from the platform after the write, not the values that were sent.
+        quota_units:
+          type: integer
+          description: Present on `updated` — the platform API quota the update consumed (YouTube charges 50 units per update).
+          example: 50
+        message:
+          type: string
+          description: Why this platform could not be updated. Absent on `updated`.
+
+    PublishedPostUpdateResponse:
+      type: object
+      properties:
+        post_id:
+          type: integer
+        results:
+          type: array
+          description: One entry per platform the post went out on, in the post's platform order.
+          items:
+            $ref: '#/components/schemas/PublishedPostUpdateResult'
+
     InstagramMusic:
       type: object
       description: Instagram only. Mixes a music track under every video item before upload (Instagram cannot attach audio to images or carousels via API). Needs at least one video item.