framefetch-net Watch API

openapi: 3.2.0
info:
  title: Framefetch Net Watch API
  version: 1.7.0
  contact:
    name: FrameFetch
    url: https://framefetch.net
  termsOfService: https://framefetch.net/impressum
  description: 'Operations tagged Watch across 2 of this provider''s published API definitions: openapi.json, framefetch-net-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://framefetch.net
security:
- bearerAuth: []
tags:
- name: Watch
paths:
  /v1/watch:
    get:
      operationId: listWatches
      summary: List your channel-monitor subscriptions
      description: Returns the calling account's active subscriptions. Any valid key works; managing subscriptions is not billed per call.
      responses:
        '200':
          description: Subscriptions
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscriptions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
      tags:
      - Watch
    post:
      operationId: createWatch
      summary: Subscribe to a channel — webhook on every new video
      description: Subscribe to a creator/channel URL on a supported platform. FrameFetch polls the channel on a schedule and POSTs a new_video event (see the new_video webhook) to your webhook_url for each new upload — no polling on your side. The webhook_url is SSRF-hardened at creation and re-validated before every delivery (must be a public https URL; localhost, loopback, private/RFC1918, link-local and cloud-metadata addresses are rejected). Subscribing does not backfill the existing catalogue — you only receive videos posted after you subscribe. Up to 50 active subscriptions per account. Creating/listing/deleting a subscription is never billed — but each SUCCESSFULLY delivered new_video webhook costs $0.0001 per delivered notification, charged once per delivery. If the account balance is at or below zero when a new video is found, the subscription is paused (active:false) rather than deleted or left to accrue debt — no further webhooks fire until you top up and re-enable it (top-up alone does not auto-resume a paused subscription).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchRequest'
      responses:
        '200':
          description: Subscription created
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscription:
                    $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
      tags:
      - Watch
    servers:
    - url: https://framefetch.net
  /v1/watch/{id}:
    delete:
      operationId: deleteWatch
      summary: Unsubscribe from a channel-monitor subscription
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The subscription id returned when it was created.
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
                  id:
                    type: string
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
      tags:
      - Watch
    servers:
    - url: https://framefetch.net
components:
  schemas:
    WatchRequest:
      type: object
      required:
      - channel
      - webhook_url
      properties:
        channel:
          type: string
          format: uri
          description: Creator/channel URL on a supported platform (e.g. https://www.youtube.com/@creator).
        webhook_url:
          type: string
          format: uri
          description: 'Public https URL that receives new_video events. SSRF-hardened: private/loopback/link-local/metadata addresses are rejected.'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            hint:
              type: string
    Subscription:
      type: object
      properties:
        id:
          type: string
        platform:
          type: string
        channel:
          type: string
        webhook_url:
          type: string
        last_seen_video_id:
          type:
          - string
          - 'null'
        active:
          type: boolean
        created_at:
          type: string
          description: ISO-8601 timestamp
  responses:
    Error:
      description: Error envelope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key from POST /v1/keys, sent as ''Authorization: Bearer <key>''.'
x-refined-from:
- openapi.json
- framefetch-net-openapi.json