GEN Agent Core API

openapi: 3.2.0
info:
  title: Auto Content Engine Agent Core 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: Agent Core
  description: '**Preferred** single-endpoint read/write for the agent setup canvas. One flat PATCH updates every brand field, personality, and default voice in a single call. Field names mirror what the FE Setup canvas saves, so developers and the FE speak the same language.'
paths:
  /agents/{agent_id}/core:
    get:
      operationId: getAgentCore
      x-mcp-tool: gen_discover
      x-mcp-branch: agent.core
      x-phase: setup
      summary: Get the full agent setup
      description: 'Returns the agent''s full setup as a flat object whose field names mirror

        exactly what the GEN Setup canvas FE reads and writes. Merges brand

        setup, voice association, and personality into a single response — you

        get the whole agent in one call.'
      tags:
      - Agent Core
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Full agent setup
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCore'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ApiValidationError'
    patch:
      operationId: patchAgentCore
      x-mcp-tool: gen_agent_action
      x-mcp-branch: update_agent_core
      x-phase: setup
      summary: Update any combination of setup fields
      description: 'Flat merge-patch. Send only the fields you want to change — missing

        fields are not forwarded. Field names map 1:1 to the GEN Setup canvas

        FE — no wrappers, no sections.


        **Field groups:**

        - Brand setup — `brand_name`, `description`, `identity_type`, `goal`,

        `keywords`, `monitored`, `target_platforms`, `shortform`, `longform`,

        `onboarding_status`, `linked_accounts`.

        - Personality — `personality` (full persona/backstory, max 20000 chars).

        - Voice — `default_user_voice`.


        **Guardrails:**

        - Unknown fields return 422 — typos fail fast.

        - `description` is capped at 500 chars. Full persona text belongs in

        `personality` (max 20000 chars).

        - `identity_type` is a strict enum: `"brand"` or `"character"`.

        - `monitored[].item_type` is a strict enum: `"account"`, `"hashtag"`,

        or `"keyword"`.


        **Semantics:** `linked_accounts` and `monitored` use full-list

        replacement. To add one row without touching others, read the current

        list via GET first, append, then PATCH.


        Returns 200 on full success, 207 Multi-Status with per-target results

        on partial failure. See `AgentCorePatchResult` for target keys.'
      tags:
      - Agent Core
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCorePatch'
      responses:
        '200':
          description: All fields updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCorePatchResult'
        '207':
          description: Partial success — inspect per-target status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCorePatchResult'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '422':
          description: Validation error — unknown field, bad enum, or length cap exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AgentCorePatch:
      type: object
      additionalProperties: false
      description: 'Flat merge-patch body. Send any subset of fields — missing fields are not forwarded.

        Unknown fields return 422. `linked_accounts` and `monitored` use full-list replacement

        semantics: rows not in the list are deleted. To add without touching others, GET first,

        append, then PATCH.

        '
      properties:
        brand_name:
          type: string
          maxLength: 200
        description:
          type: string
          maxLength: 500
          description: Short 2-3 sentence brand summary. NOT full persona — that goes in `personality`.
        identity_type:
          type: string
          enum:
          - brand
          - character
        goal:
          type: string
          maxLength: 100
        target_platforms:
          type: array
          items:
            type: string
          maxItems: 10
        shortform:
          type: boolean
        longform:
          type: boolean
        onboarding_status:
          type: string
          maxLength: 50
        keywords:
          type: array
          items:
            type: string
          maxItems: 20
          description: Flat keyword list. If set without `monitored`, auto-mirrored into monitored with item_type='keyword'.
        monitored:
          type: array
          items:
            $ref: '#/components/schemas/MonitoredItem'
          maxItems: 50
          description: Full inspiration source list (replaces the existing list).
        linked_accounts:
          type: array
          items:
            $ref: '#/components/schemas/LinkedAccount'
          maxItems: 20
        personality:
          type: string
          maxLength: 20000
          description: Full persona text for the agent.
        default_user_voice:
          $ref: '#/components/schemas/VoiceRef'
        proof_of_genesis_enabled:
          type: boolean
          description: Master switch for automatic Backup to Blockchain from asset/vidsheet events.
        proof_of_genesis_auto_backup_sources:
          type: array
          description: Replace the list of asset events that should trigger automatic Proof of Genesis backups. Empty means no automatic backup.
          items:
            type: string
            enum:
            - generated
            - uploaded
            - downloaded
            - published
        proof_of_genesis_auto_backup_asset_types:
          type: array
          description: Replace the list of asset types eligible for automatic Proof of Genesis backup.
          items:
            type: string
            enum:
            - video
            - image
    ApiError:
      type: object
      required:
      - code
      properties:
        code:
          type: string
          description: The stable machine-readable failure code.
        message:
          type: string
          description: Human-readable failure detail.
        errors:
          type: array
          description: Field-level validation failures.
          items:
            type: object
        retryable:
          type: boolean
          description: Whether retrying can succeed without changing the request.
        new_change_set_required:
          type: boolean
          description: Whether the caller must begin a new edit group.
        funding_error_kind:
          type: string
          description: The credit or payment failure category.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message.
        error_code:
          type: string
          description: Machine-readable error code.
    LinkedAccount:
      type: object
      additionalProperties: false
      required:
      - url
      properties:
        id:
          type: integer
          description: Row id if updating an existing row. Omit when adding a new account.
        url:
          type: string
          minLength: 1
          maxLength: 500
        platform:
          type: string
          maxLength: 50
          description: tiktok | instagram | youtube | x | linkedin | pinterest | facebook | threads | website | other
        display_name:
          type: string
          maxLength: 200
    AgentCore:
      type: object
      description: Full agent setup as returned by GET /agents/{id}/core.
      properties:
        agent_id:
          type: string
        brand_name:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        identity_type:
          type: string
          enum:
          - brand
          - character
          nullable: true
        goal:
          type: string
          nullable: true
          description: Comma-separated, e.g. 'growth,authority,sales'
        target_platforms:
          type: array
          items:
            type: string
        shortform:
          type: boolean
          nullable: true
        longform:
          type: boolean
          nullable: true
        onboarding_status:
          type: string
          nullable: true
        keywords:
          type: array
          items:
            type: string
          description: Flat keyword list used by the monitoring cron. Auto-mirrored into `monitored` on write.
        monitored:
          type: array
          items:
            $ref: '#/components/schemas/MonitoredItem'
          description: Inspiration sources — accounts, hashtags, or keywords the agent monitors for trending content.
        linked_accounts:
          type: array
          items:
            $ref: '#/components/schemas/LinkedAccount'
          description: The agent's OWN brand social links. NOT the same as `monitored` (which holds sources to watch).
        personality:
          type: string
          nullable: true
          description: Full persona text for the agent.
        default_user_voice:
          $ref: '#/components/schemas/VoiceRef'
        proof_of_genesis_enabled:
          type: boolean
          description: Master switch for automatic Backup to Blockchain from asset/vidsheet events.
        proof_of_genesis_auto_backup_sources:
          type: array
          description: Asset events that should trigger automatic Proof of Genesis backups.
          items:
            type: string
            enum:
            - generated
            - uploaded
            - downloaded
            - published
        proof_of_genesis_auto_backup_asset_types:
          type: array
          description: Asset types eligible for automatic Proof of Genesis backup.
          items:
            type: string
            enum:
            - video
            - image
    VoiceRef:
      type: object
      additionalProperties: false
      required:
      - voice_id
      properties:
        voice_id:
          type: string
          minLength: 1
          maxLength: 200
        source:
          type: string
          enum:
          - public
          - user_designed
          - user_trained
          - user_elevenlabs
        name:
          type: string
          maxLength: 200
    MonitoredItem:
      type: object
      additionalProperties: false
      required:
      - handle
      - item_type
      properties:
        handle:
          type: string
          minLength: 1
          maxLength: 300
          description: For accounts — a @handle or URL. For hashtags — the tag (with or without
        item_type:
          type: string
          enum:
          - account
          - hashtag
          - keyword
    AgentCorePatchResult:
      type: object
      description: "Per-section result. A PATCH to Agent Core may update multiple sections atomically.\nSection keys currently returned:\n  - `brand` — brand fields (brand_name, description, identity_type, goal,\n    target_platforms, shortform, longform, onboarding_status, keywords, monitored,\n    linked_accounts). Clients should treat section keys as opaque strings.\n  - `personality` — personality text.\n  - `voice` — voice association.\nEach section appears only if the PATCH touched at least one field it owns.\n`status=ok` means that section succeeded. `status=error` means it failed\n(see `error` field). A 207 Multi-Status means at least one section errored.\n"
      additionalProperties:
        type: object
        properties:
          status:
            type: string
            enum:
            - ok
            - error
          data:
            description: Target-specific payload on success.
          error:
            type: string
            description: Error message on failure.
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not found
            error_code: not_found
    ApiUnauthorized:
      description: Missing or invalid authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiValidationError:
      description: Validation failed or the request could not be processed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  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.