Add conversation summary (#267)

src/v2/spec.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Farcaster API V2
-  version: "2.3.0"
+  version: "2.4.0"
   description: >
     The Farcaster API allows you to interact with the Farcaster protocol.
     See the [Neynar docs](https://docs.neynar.com/reference) for more details.
@@ -2176,6 +2176,31 @@ components:
                 $ref: "#/components/schemas/CastWithInteractions"
         next:
           $ref: "#/components/schemas/NextCursor"
+    ConversationSummary:
+      type: object
+      required:
+        - summary
+      properties:
+        summary:
+          type: object
+          required:
+            - text
+            - participants
+            - mentioned_profiles
+          properties:
+            text:
+              type: string
+              description: Summary generated by an LLM
+            participants:
+              type: array
+              items:
+                $ref: "#/components/schemas/User"
+              description: Users who casted in a conversation thread
+            mentioned_profiles:
+              type: array
+              items:
+                $ref: "#/components/schemas/User"
+              description: Users who were mentioned in a conversation thread
     SharedSignerPermission:
       type: string
       enum:
@@ -5280,6 +5305,53 @@ paths:
                 $ref: "#/components/schemas/Conversation"
         "400":
           $ref: "#/components/responses/400Response"
+  /farcaster/cast/conversation/summary:
+    get:
+      tags:
+        - Cast
+      summary: Conversation summary for a cast
+      description: >
+        Generates a summary of all casts related to a conversation surrounding
+        a cast by passing in a cast hash or Warpcast URL. 
+        Summary is generated by an LLM and is intended to be passed as a context to AI agents.
+      externalDocs:
+        url: https://docs.neynar.com/reference/lookup-cast-conversation-summary
+      operationId: lookup-cast-conversation-summary
+      parameters:
+        - name: identifier
+          required: true
+          in: query
+          example: "0x9288c1e862aa72bd69d0e383a28b9a76b63cbdb4"
+          description: Cast identifier (Its either a url or a hash)
+          schema:
+            type: string
+        - name: limit
+          in: query
+          description: Number of casts to consider in a summary up to a point of target cast
+          required: false
+          example: 50
+          schema:
+            type: integer
+            default: 20
+            minimum: 1
+            maximum: 50
+          x-is-limit-param: true
+        - name: prompt
+          required: false
+          in: query
+          example: be unreasonably dramatic
+          description: Additional prompt used to generate a summary
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConversationSummary"
+        "400":
+          $ref: "#/components/responses/400Response"
   /farcaster/feed:
     get:
       summary: By filters