arazzo: 1.0.1
info:
  title: TikTok Research Pinned Video Comments
  summary: Resolve a handle, fetch the user's pinned videos, then pull comments on the first pinned video.
  description: >-
    Inspects the conversation around a creator's highlighted content using the
    Research API. The workflow resolves a handle to its public profile, lists
    the videos the user has pinned to the top of their profile, and then, when a
    pinned video exists, retrieves the full comment thread on the first pinned
    video. This surfaces the discussion attached to the content a creator most
    wants seen. Every step spells out its request inline, including the inline
    Bearer authorization, so the flow can be read and executed without opening
    the underlying OpenAPI description.
  version: 1.0.0
sourceDescriptions:
- name: researchApi
  url: ../openapi/tiktok-research-openapi.yml
  type: openapi
workflows:
- workflowId: research-pinned-video-comments
  summary: Resolve a handle, list pinned videos, then list comments on the first.
  description: >-
    Resolves a TikTok handle, lists the user's pinned videos, and retrieves the
    comment thread on the first pinned video when one exists.
  inputs:
    type: object
    required:
    - accessToken
    - username
    properties:
      accessToken:
        type: string
        description: OAuth 2.0 client-credentials token for the Research API.
      username:
        type: string
        description: TikTok handle to inspect (without the @).
      userFields:
        type: string
        description: Comma-separated user fields to return.
        default: display_name,is_verified,follower_count,video_count
      videoFields:
        type: string
        description: Comma-separated video fields to return.
        default: id,create_time,username,video_description,like_count,comment_count,view_count
      commentFields:
        type: string
        description: Comma-separated comment fields to return.
        default: id,video_id,text,like_count,reply_count,parent_comment_id,create_time
      maxCount:
        type: integer
        description: Maximum number of videos to return per page (1-100).
        default: 100
      maxCommentCount:
        type: integer
        description: Maximum number of comments to return (1-100).
        default: 100
  steps:
  - stepId: getUserInfo
    description: >-
      Resolve the supplied handle to its public profile before fetching pinned
      content.
    operationId: queryResearchUserInfo
    parameters:
    - name: Authorization
      in: header
      value: Bearer $inputs.accessToken
    - name: fields
      in: query
      value: $inputs.userFields
    requestBody:
      contentType: application/json
      payload:
        username: $inputs.username
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      displayName: $response.body#/data/display_name
      videoCount: $response.body#/data/video_count
  - stepId: listPinnedVideos
    description: >-
      List the videos the resolved user has pinned to the top of their profile.
    operationId: listUserPinnedVideos
    parameters:
    - name: Authorization
      in: header
      value: Bearer $inputs.accessToken
    - name: fields
      in: query
      value: $inputs.videoFields
    requestBody:
      contentType: application/json
      payload:
        username: $inputs.username
        max_count: $inputs.maxCount
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      pinnedVideos: $response.body#/data/videos
      firstPinnedVideoId: $response.body#/data/videos/0/id
    onSuccess:
    - name: havePinned
      type: goto
      stepId: listComments
      criteria:
      - context: $response.body
        condition: $.data.videos.length > 0
        type: jsonpath
    - name: noPinned
      type: end
      criteria:
      - context: $response.body
        condition: $.data.videos.length == 0
        type: jsonpath
  - stepId: listComments
    description: >-
      Retrieve the comment thread on the first pinned video, including text,
      like counts, and reply counts.
    operationId: listVideoComments
    parameters:
    - name: Authorization
      in: header
      value: Bearer $inputs.accessToken
    - name: fields
      in: query
      value: $inputs.commentFields
    requestBody:
      contentType: application/json
      payload:
        video_id: $steps.listPinnedVideos.outputs.firstPinnedVideoId
        max_count: $inputs.maxCommentCount
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      comments: $response.body#/data/comments
      hasMore: $response.body#/data/has_more
      cursor: $response.body#/data/cursor
  outputs:
    displayName: $steps.getUserInfo.outputs.displayName
    pinnedVideos: $steps.listPinnedVideos.outputs.pinnedVideos
    comments: $steps.listComments.outputs.comments