From d81b644d7f177011cf40c04aa0904ddbe8c206f4 Mon Sep 17 00:00:00 2001
From: Julian Lam <julian@nodebb.org>
Date: Mon, 5 Jan 2026 12:24:00 -0500
Subject: [PATCH] docs: update openapi schema for missing routes related to
 crossposting

---
 .../components/schemas/CrosspostObject.yaml   | 74 ++++++++++++-------
 public/openapi/read/topic/topic_id.yaml       |  4 +
 .../openapi/write/topics/tid/crossposts.yaml  | 28 +++++++
 3 files changed, 78 insertions(+), 28 deletions(-)

diff --git a/public/openapi/components/schemas/CrosspostObject.yaml b/public/openapi/components/schemas/CrosspostObject.yaml
index 53a4183055..54f36a4f5f 100644
--- a/public/openapi/components/schemas/CrosspostObject.yaml
+++ b/public/openapi/components/schemas/CrosspostObject.yaml
@@ -1,32 +1,50 @@
 CrosspostObject:
-  type: object
-  properties:
-    id:
-      type: string
-      description: The cross-post ID
-    cid:
-      type: object
-      description: The category id that the topic was cross-posted to
-      additionalProperties:
-        oneOf:
-          - type: string
-          - type: number
-    tid:
-      type: object
-      description: The topic id that was cross-posted
-      additionalProperties:
-        oneOf:
-          - type: string
-          - type: number
-    timestamp:
-      type: number
-    uid:
-      type: object
-      description: The user id that initiated the cross-post
-      additionalProperties:
-        oneOf:
-          - type: string
-          - type: number
+  anyOf:
+    - type: object
+      properties:
+        id:
+          type: string
+          description: The cross-post ID
+        cid:
+          type: object
+          description: The category id that the topic was cross-posted to
+          additionalProperties:
+            oneOf:
+              - type: string
+              - type: number
+        tid:
+          type: object
+          description: The topic id that was cross-posted
+          additionalProperties:
+            oneOf:
+              - type: string
+              - type: number
+        timestamp:
+          type: number
+        uid:
+          type: object
+          description: The user id that initiated the cross-post
+          additionalProperties:
+            oneOf:
+              - type: string
+              - type: number
+    - type: object
+      properties:
+        category:
+          type: object
+          properties:
+            cid:
+              type: number
+            name:
+              type: string
+            icon:
+              type: string
+            bgColor:
+              type: string
+            color:
+              type: string
+            slug:
+              type: string
 CrosspostsArray:
   type: array
   description: A list of crosspost objects
diff --git a/public/openapi/read/topic/topic_id.yaml b/public/openapi/read/topic/topic_id.yaml
index 302d39dbcc..81b3e9531f 100644
--- a/public/openapi/read/topic/topic_id.yaml
+++ b/public/openapi/read/topic/topic_id.yaml
@@ -212,6 +212,10 @@ get:
                       isLocal:
                         type: boolean
                         description: Whether the user belongs to the local installation or not.
+                  crossposts:
+                    type: array
+                    items:
+                      $ref: ../../components/schemas/CrosspostObject.yaml#/CrosspostObject
               - type: object
                 description: Optional properties that may or may not be present (except for `tid`, which is always present, and is only here as a hack to pass validation)
                 properties:
diff --git a/public/openapi/write/topics/tid/crossposts.yaml b/public/openapi/write/topics/tid/crossposts.yaml
index 212a1f6469..f292292e0a 100644
--- a/public/openapi/write/topics/tid/crossposts.yaml
+++ b/public/openapi/write/topics/tid/crossposts.yaml
@@ -1,3 +1,31 @@
+get:
+  tags:
+     - topics
+  summary: get topic crossposts
+  description: This operation retrieves a list of crossposts for the requested topic
+  parameters:
+    - in: path
+      name: tid
+      schema:
+        type: string
+      required: true
+      description: a valid topic id
+      example: 1
+  responses:
+    '200':
+      description: Topic crossposts retrieved
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+                properties:
+                  crossposts:
+                    $ref: ../../../components/schemas/CrosspostObject.yaml#/CrosspostsArray
 post:
   tags:
     - topics