GEN Watchlists API

openapi: 3.2.0
info:
  title: Auto Content Engine Watchlists API
  description: 'The GEN Auto Content Engine API takes a raw idea all the way to a published video — agent setup, idea research, vidsheet production, layer composition, render, and publish.


    ## The 5-step journey


    Every operation belongs to one phase of a 5-step user journey. Each operation carries an `x-phase` extension you can filter on:


    | Phase | Meaning |

    |-------|---------|

    | `setup` | Step 1 — Set Up Your Agent (identity, voice, personality, API keys, workspaces) |

    | `ideas` | Step 2 — Generate Content Ideas (trending data, research, refinement, preferences) |

    | `convert` | Step 3 — Convert Idea to Vidsheet (clone template or build custom engine) |

    | `edit` | Step 4 — Edit & Generate (cells, layers, creation cards, trigger + poll) |

    | `export` | Step 5 — Export & Publish (render, download, publish to social) |


    Full journey-oriented docs: https://api.gen.pro


    ## Authentication


    All endpoints require authentication via one of:


    - **API Key** (recommended): Pass your API key in the `X-API-Key` header. Create keys on the agent''s API page in the GEN dashboard.

    - **JWT**: Pass a Bearer JWT in the `Authorization: Bearer ` header.


    ## Base URLs


    ```

    https://api.gen.pro/v1 — agent setup, vidsheets, generations, renders, publishing

    https://agent.gen.pro/v1 — content ideas, research, conversations, chat

    https://agent-core.gen.pro/v1 — agent core (brand profile, watchlists, scheduled tasks)

    https://python.gen.pro — social publishing integration (connect, schedule, remove posts)

    ```


    Each operation carries its own `servers` entry, so a generated client or a

    hand-written call goes to the backend that serves the route.


    ## Credits


    All `/v1/vidsheet/` endpoints require an active GEN credit balance.

    If your organization has no usable credits, requests return `422` with error code `usable_gen_credit_required`.


    Credits can be funded with x402 by calling `POST /v1/x402_credit_purchase`

    with `workspace_id` plus `amount_usd` or `credits`. If `network` is omitted,

    GEN returns every configured payment option in `payment_methods` and

    `payment_required.accepts`; show the Sui, Solana, and Base options to the

    user or calling agent and sign one selected accept entry. Workspace funding

    wallets are backend settlement infrastructure; the user-facing payment

    choices are the returned payment methods.'
  version: 1.0.0
  contact:
    name: GEN Support
    url: https://gen.pro
  license:
    name: Proprietary
servers:
- url: https://api.gen.pro/v1
  description: Auto Content Engine API
- url: https://agent.gen.pro/v1
  description: Agent Chat API
- url: https://agent-core.gen.pro/v1
  description: Agent Core API (watchlists)
- url: https://python.gen.pro
  description: Publishing integration API (social connect and scheduling)
security:
- apiKey: []
- bearerAuth: []
tags:
- name: Watchlists
  description: 'Named collections of monitoring sources (accounts, hashtags, keywords) per

    agent. Base URL `https://agent-core.gen.pro/v1`. Scraped data feeds back

    into agent chat and content idea generation. CRUD operations are free;

    downstream scrapes bill normally.'
paths:
  /agents/{agent_id}/watchlists:
    get:
      operationId: listWatchlists
      servers:
      - url: https://agent-core.gen.pro/v1
      x-mcp-tool: gen_discover
      x-mcp-branch: watchlist.list
      x-phase: monitoring
      summary: List active watchlists for an agent
      tags:
      - Watchlists
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Active watchlists, newest first
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Watchlist'
        '401':
          $ref: '#/components/responses/AgentCoreUnauthorized'
        '422':
          $ref: '#/components/responses/AgentCoreValidationError'
    post:
      operationId: createWatchlist
      servers:
      - url: https://agent-core.gen.pro/v1
      x-mcp-tool: gen_watchlist_action
      x-mcp-branch: create_watchlist
      x-phase: monitoring
      summary: Create a watchlist (idempotent on name)
      description: 'Create a new watchlist with optional initial sources. Idempotent on

        `name` (case-insensitive): if a watchlist with the same name already

        exists for this agent, the provided sources are merged into the

        existing watchlist instead of creating a duplicate.'
      tags:
      - Watchlists
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistCreateRequest'
      responses:
        '201':
          description: Watchlist created or merged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
        '401':
          $ref: '#/components/responses/AgentCoreUnauthorized'
        '422':
          $ref: '#/components/responses/AgentCoreValidationError'
  /agents/{agent_id}/watchlists/{watchlist_id}:
    get:
      operationId: getWatchlist
      servers:
      - url: https://agent-core.gen.pro/v1
      x-mcp-tool: gen_discover
      x-mcp-branch: watchlist.detail
      x-phase: monitoring
      summary: Get a single watchlist with sources
      tags:
      - Watchlists
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Watchlist record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/AgentCoreUnauthorized'
        '422':
          $ref: '#/components/responses/AgentCoreValidationError'
    patch:
      operationId: updateWatchlist
      servers:
      - url: https://agent-core.gen.pro/v1
      x-mcp-tool: gen_watchlist_action
      x-mcp-branch: pause_watchlist
      x-phase: monitoring
      summary: Update a watchlist (also used for pause/resume)
      description: 'Update mutable fields. Set `intent_active=false` to pause monitoring

        without deleting the watchlist; `true` to resume. Only fields you

        send are updated.'
      tags:
      - Watchlists
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistUpdateRequest'
      responses:
        '200':
          description: Updated watchlist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/AgentCoreUnauthorized'
        '422':
          $ref: '#/components/responses/AgentCoreValidationError'
    delete:
      operationId: deleteWatchlist
      servers:
      - url: https://agent-core.gen.pro/v1
      x-mcp-tool: gen_watchlist_action
      x-mcp-branch: delete_watchlist
      x-phase: monitoring
      summary: Soft-delete a watchlist
      description: 'Marks the watchlist and all its sources inactive and deleted. The

        rows are retained in the database. Use PATCH with `intent_active=false`

        for a reversible pause.'
      tags:
      - Watchlists
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Watchlist deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  deleted:
                    type: boolean
        '401':
          $ref: '#/components/responses/AgentCoreUnauthorized'
        '422':
          $ref: '#/components/responses/AgentCoreValidationError'
  /agents/{agent_id}/watchlists/{watchlist_id}/sources:
    post:
      operationId: addWatchlistSource
      servers:
      - url: https://agent-core.gen.pro/v1
      x-mcp-tool: gen_watchlist_action
      x-mcp-branch: add_watchlist_source
      x-phase: monitoring
      summary: Add or restore a source on a watchlist
      description: 'Idempotent on (platform, target_type, target_value). Re-adding the

        same source returns the existing row (restored if it had been

        soft-deleted).'
      tags:
      - Watchlists
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchSourceInput'
      responses:
        '201':
          description: Source added or restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchSource'
        '401':
          $ref: '#/components/responses/AgentCoreUnauthorized'
        '422':
          $ref: '#/components/responses/AgentCoreValidationError'
    delete:
      operationId: removeWatchlistSourceByKey
      servers:
      - url: https://agent-core.gen.pro/v1
      x-mcp-tool: gen_watchlist_action
      x-mcp-branch: remove_watchlist_source
      x-phase: monitoring
      summary: Remove a source by (platform, target_type, target_value)
      tags:
      - Watchlists
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
      - name: platform
        in: query
        required: true
        schema:
          type: string
      - name: target_type
        in: query
        required: true
        schema:
          type: string
          enum:
          - account
          - hashtag
          - keyword
      - name: target_value
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Source removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  removed:
                    type: boolean
        '401':
          $ref: '#/components/responses/AgentCoreUnauthorized'
        '422':
          $ref: '#/components/responses/AgentCoreValidationError'
  /agents/{agent_id}/watchlists/{watchlist_id}/sources/{source_id}:
    delete:
      operationId: removeWatchlistSource
      servers:
      - url: https://agent-core.gen.pro/v1
      x-mcp-tool: gen_watchlist_action
      x-mcp-branch: remove_watchlist_source
      x-phase: monitoring
      summary: Remove a source by id
      tags:
      - Watchlists
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
      - name: source_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Source removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  removed:
                    type: boolean
        '401':
          $ref: '#/components/responses/AgentCoreUnauthorized'
        '422':
          $ref: '#/components/responses/AgentCoreValidationError'
components:
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not found
            error_code: not_found
    AgentCoreValidationError:
      description: Validation failed or the request could not be processed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AgentCoreError'
    AgentCoreUnauthorized:
      description: Missing or invalid authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AgentCoreError'
  schemas:
    Watchlist:
      type: object
      required:
      - id
      - user_id
      - agent_id
      - name
      - intent_active
      - sources
      properties:
        id:
          type: string
        user_id:
          type: string
        agent_id:
          type: string
        name:
          type: string
        intent_active:
          type: boolean
        project_id:
          type: string
          nullable: true
        project_error:
          type: string
          nullable: true
          description: Read-only. Last project-link sync error, if any.
        conversation_id:
          type: string
          nullable: true
        created_by_run_id:
          type: string
          nullable: true
        sources:
          type: array
          items:
            $ref: '#/components/schemas/WatchSource'
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message.
        error_code:
          type: string
          description: Machine-readable error code.
    WatchlistUpdateRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        intent_active:
          type: boolean
          description: Set false to pause monitoring; true to resume.
        project_id:
          oneOf:
          - type: string
          - type: integer
          nullable: true
    WatchSource:
      allOf:
      - $ref: '#/components/schemas/WatchSourceInput'
      - type: object
        required:
        - id
        - watchlist_id
        - agent_id
        - intent_active
        properties:
          id:
            type: string
          watchlist_id:
            type: string
          agent_id:
            type: string
          intent_active:
            type: boolean
          created_at:
            type: string
            format: date-time
            nullable: true
          updated_at:
            type: string
            format: date-time
            nullable: true
    AgentCoreError:
      type: object
      required:
      - code
      properties:
        code:
          type: string
          description: The stable machine-readable failure code.
        message:
          type: string
          description: Human-readable failure detail.
    WatchlistCreateRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: 'Display name. Idempotent: same name reuses existing watchlist.'
        sources:
          type: array
          items:
            $ref: '#/components/schemas/WatchSourceInput'
        project_id:
          oneOf:
          - type: string
          - type: integer
          nullable: true
        conversation_id:
          type: string
          nullable: true
        created_by_run_id:
          type: string
          nullable: true
    WatchSourceInput:
      type: object
      required:
      - platform
      - target_type
      - target_value
      properties:
        platform:
          type: string
          description: e.g. "tiktok", "instagram", "youtube"
        target_type:
          type: string
          enum:
          - account
          - hashtag
          - keyword
        target_value:
          type: string
          description: '@handle, hashtag name (no #), or keyword text'
        original_display_value:
          type: string
          nullable: true
          description: Optional original display form (e.g. "#glassskin" or "@drunkelephant")
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Personal Access Token (PAT). Create one in Settings > API Keys.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT issued by the GEN dashboard sign-in.