openapi: 3.0.3
info:
  title: Shorts V2 API
  version: "2.0.0"
  description: |
    API for managing connected YouTube/TikTok channels, video and slideshow schedules,
    direct publishing, inbox publishing, post history, and multipart file uploads.
servers:
  - url: https://shortsblink.com
  - url: http://localhost:8080
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    Channel:
      type: object
      properties:
        id:
          type: string
        platform:
          type: string
          enum: [youtube, tiktok]
        name:
          type: string
        handle:
          type: string
        oauth_status:
          type: string
    Schedule:
      type: object
      required: [channel_id, title, content_type, delivery_mode, scheduled_for]
      properties:
        id:
          type: string
        channel_id:
          type: string
        title:
          type: string
        caption:
          type: string
        content_type:
          type: string
          enum: [video, slideshow]
        delivery_mode:
          type: string
          enum: [direct, inbox]
        asset_urls:
          type: array
          items:
            type: string
        scheduled_for:
          type: string
          format: date-time
    ScheduleMultipart:
      type: object
      required: [channel_id, title, content_type, delivery_mode, scheduled_for]
      properties:
        channel_id:
          type: string
        title:
          type: string
        caption:
          type: string
        content_type:
          type: string
          enum: [video, slideshow]
        delivery_mode:
          type: string
          enum: [direct, inbox]
        scheduled_for:
          type: string
          format: date-time
        asset_urls:
          type: string
          description: Optional newline-separated URLs to combine with uploaded files.
        assets:
          type: array
          items:
            type: string
            format: binary
          description: Upload one video file or multiple image files.
security:
  - ApiKeyAuth: []
paths:
  /api/v2/channels:
    get:
      summary: List all connected channels for the API key owner.
      responses:
        "200":
          description: Channel list.
    post:
      summary: Create a connected channel record.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Channel"
      responses:
        "201":
          description: Channel created.
  /api/v2/channels/{channel_id}:
    delete:
      summary: Delete a connected channel.
      parameters:
        - name: channel_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Channel deleted.
  /api/v2/schedules:
    get:
      summary: List all schedules for the API key owner.
      responses:
        "200":
          description: Schedule list.
    post:
      summary: Schedule a video or slideshow for YouTube or TikTok.
      description: |
        Supports both JSON payloads and multipart file uploads.
        Use `application/json` when you already have asset URLs.
        Use `multipart/form-data` with one or more `assets` files when uploading media directly.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Schedule"
            examples:
              tiktokInbox:
                value:
                  channel_id: "6616d4e0a2c1f41234567890"
                  title: "Launch teaser"
                  caption: "First look at the new drop."
                  content_type: "video"
                  delivery_mode: "inbox"
                  asset_urls:
                    - "https://cdn.example.com/videos/launch.mp4"
                  scheduled_for: "2026-04-11T10:00:00Z"
              youtubeSlideshow:
                value:
                  channel_id: "6616d4e0a2c1f41234567891"
                  title: "Top 5 moments"
                  caption: "Built from stills and transitions."
                  content_type: "slideshow"
                  delivery_mode: "direct"
                  asset_urls:
                    - "https://cdn.example.com/slides/1.jpg"
                    - "https://cdn.example.com/slides/2.jpg"
                  scheduled_for: "2026-04-11T14:30:00Z"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/ScheduleMultipart"
            encoding:
              assets:
                style: form
                explode: true
            examples:
              tiktokPhotoDraftUpload:
                value:
                  channel_id: "1"
                  title: "AI History in 3 Photos"
                  caption: "Upload photos directly instead of hosting them first."
                  content_type: "slideshow"
                  delivery_mode: "inbox"
                  scheduled_for: "2026-04-11T15:00:00Z"
      responses:
        "201":
          description: Schedule created.
  /api/v2/schedules/{schedule_id}/publish:
    post:
      summary: Publish a scheduled item immediately.
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Schedule posted.
  /api/v2/schedules/{schedule_id}/status:
    get:
      summary: Refresh and return the latest TikTok publish status for a schedule.
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Refreshed schedule status.
    post:
      summary: Refresh and return the latest TikTok publish status for a schedule.
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Refreshed schedule status.
  /api/v2/posts:
    get:
      summary: List published posts.
      responses:
        "200":
          description: Post list.
