GEN Recurring Jobs API

openapi: 3.2.0
info:
  title: Auto Content Engine Recurring Jobs 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: Recurring Jobs
  description: 'Scheduled agent runs ("daily tasks"). Base URL

    `https://agent.gen.pro/v1`. Each scheduled run is gated by available

    credits: a job remains configured if credits run out and resumes when

    they return.'
paths:
  /agents/{agent_id}/recurring-jobs:
    get:
      operationId: listRecurringJobs
      servers:
      - url: https://agent.gen.pro/v1
      x-mcp-tool: gen_discover
      x-mcp-branch: task.list
      x-phase: monitoring
      summary: List recurring jobs (daily tasks) for an agent
      tags:
      - Recurring Jobs
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Recurring jobs, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  recurring_jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecurringJob'
        '401':
          $ref: '#/components/responses/AgentUnauthorized'
        '422':
          $ref: '#/components/responses/AgentValidationError'
    post:
      operationId: createRecurringJob
      servers:
      - url: https://agent.gen.pro/v1
      x-mcp-tool: gen_task_action
      x-mcp-branch: create_recurring_job
      x-phase: monitoring
      summary: Create a recurring agent job
      tags:
      - Recurring Jobs
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecurringJobCreate'
      responses:
        '201':
          description: Created recurring job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringJob'
        '401':
          $ref: '#/components/responses/AgentUnauthorized'
        '422':
          $ref: '#/components/responses/AgentValidationError'
  /agents/{agent_id}/recurring-jobs/defaults:
    post:
      operationId: ensureDefaultRecurringJob
      servers:
      - url: https://agent.gen.pro/v1
      x-mcp-tool: gen_task_action
      x-mcp-branch: ensure_default_recurring_job
      x-schema-status: missing
      x-phase: monitoring
      summary: Idempotently ensure the default daily content-ideas job
      description: 'Returns the agent''s existing default content-ideas recurring job if

        one exists, otherwise creates it with the standard prompt, daily

        cadence at 09:00 UTC, and `chat_only` delivery. The response `created`

        boolean indicates whether a new job was created.'
      tags:
      - Recurring Jobs
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Default job ensured
          content:
            application/json:
              schema:
                type: object
                properties:
                  recurring_jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecurringJob'
                  created:
                    type: boolean
        '401':
          $ref: '#/components/responses/AgentUnauthorized'
        '422':
          $ref: '#/components/responses/AgentValidationError'
  /agents/{agent_id}/recurring-jobs/{job_id}:
    get:
      operationId: getRecurringJob
      servers:
      - url: https://agent.gen.pro/v1
      x-mcp-tool: gen_discover
      x-mcp-branch: task.job
      x-phase: monitoring
      summary: Get one recurring job
      tags:
      - Recurring Jobs
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Recurring job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringJob'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/AgentUnauthorized'
        '422':
          $ref: '#/components/responses/AgentValidationError'
    patch:
      operationId: updateRecurringJob
      servers:
      - url: https://agent.gen.pro/v1
      x-mcp-tool: gen_task_action
      x-mcp-branch: update_recurring_job
      x-phase: monitoring
      summary: Update a recurring job's mutable fields
      tags:
      - Recurring Jobs
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecurringJobUpdate'
      responses:
        '200':
          description: Updated job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringJob'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/AgentUnauthorized'
        '422':
          $ref: '#/components/responses/AgentValidationError'
    delete:
      operationId: deleteRecurringJob
      servers:
      - url: https://agent.gen.pro/v1
      x-mcp-tool: gen_task_action
      x-mcp-branch: delete_recurring_job
      x-phase: monitoring
      summary: Soft-delete a recurring job
      tags:
      - Recurring Jobs
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Deleted (no content)
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/AgentUnauthorized'
        '422':
          $ref: '#/components/responses/AgentValidationError'
  /agents/{agent_id}/recurring-jobs/{job_id}/pause:
    post:
      operationId: pauseRecurringJob
      servers:
      - url: https://agent.gen.pro/v1
      x-mcp-tool: gen_task_action
      x-mcp-branch: pause_recurring_job
      x-schema-status: missing
      x-phase: monitoring
      summary: Pause a recurring job
      tags:
      - Recurring Jobs
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Paused job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringJob'
        '401':
          $ref: '#/components/responses/AgentUnauthorized'
        '422':
          $ref: '#/components/responses/AgentValidationError'
  /agents/{agent_id}/recurring-jobs/{job_id}/resume:
    post:
      operationId: resumeRecurringJob
      servers:
      - url: https://agent.gen.pro/v1
      x-mcp-tool: gen_task_action
      x-mcp-branch: resume_recurring_job
      x-schema-status: missing
      x-phase: monitoring
      summary: Resume a paused recurring job
      tags:
      - Recurring Jobs
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Resumed job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringJob'
        '401':
          $ref: '#/components/responses/AgentUnauthorized'
        '422':
          $ref: '#/components/responses/AgentValidationError'
components:
  responses:
    AgentUnauthorized:
      description: Missing or invalid authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AgentError'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not found
            error_code: not_found
    AgentValidationError:
      description: Validation failed or the request could not be processed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AgentError'
  schemas:
    RecurringJob:
      type: object
      required:
      - id
      - user_id
      - agent_id
      - name
      - job_type
      - prompt
      - schedule
      - delivery
      - status
      - created_at
      - updated_at
      properties:
        id:
          type: string
        user_id:
          type: integer
        agent_id:
          type: string
        name:
          type: string
        job_type:
          type: string
          description: e.g. "generate_content_ideas"
        prompt:
          type: string
        schedule:
          $ref: '#/components/schemas/RecurringJobSchedule'
        delivery:
          $ref: '#/components/schemas/RecurringJobDelivery'
        status:
          type: string
          enum:
          - active
          - paused
          - deleted
        next_run_at:
          type: string
          format: date-time
          nullable: true
        last_run_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    RecurringJobCreate:
      type: object
      required:
      - job_type
      - prompt
      - schedule
      - delivery
      properties:
        name:
          type: string
          description: Optional. Defaults to first 80 chars of prompt.
        job_type:
          type: string
        prompt:
          type: string
        schedule:
          $ref: '#/components/schemas/RecurringJobSchedule'
        delivery:
          $ref: '#/components/schemas/RecurringJobDelivery'
        next_run_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message.
        error_code:
          type: string
          description: Machine-readable error code.
    AgentError:
      type: object
      required:
      - code
      properties:
        code:
          type: string
          description: The stable machine-readable failure code.
        message:
          type: string
          description: Human-readable failure detail.
    RecurringJobDelivery:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - chat_only
          - email
        email:
          type: string
          description: Recipient email. REQUIRED when type="email"; must be omitted when type="chat_only".
    RecurringJobSchedule:
      type: object
      required:
      - cadence
      - timezone
      properties:
        cadence:
          type: string
          enum:
          - daily
          - weekly
        timezone:
          type: string
          description: IANA timezone (e.g. "UTC", "America/Los_Angeles")
        time_of_day:
          type: string
          description: Local clock time "HH:MM" (24h). Required for daily/weekly cadences.
        days_of_week:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 6
          description: Days to run (0=Mon … 6=Sun). REQUIRED when cadence="weekly"; must be omitted when cadence="daily". No duplicates.
    RecurringJobUpdate:
      type: object
      properties:
        name:
          type: string
        prompt:
          type: string
        schedule:
          $ref: '#/components/schemas/RecurringJobSchedule'
        delivery:
          $ref: '#/components/schemas/RecurringJobDelivery'
        next_run_at:
          type: string
          format: date-time
  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.