GEN Proof of Genesis API

openapi: 3.2.0
info:
  title: Auto Content Engine Proof of Genesis 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: Proof of Genesis
  description: 'Back up GEN assets to Walrus with verifiable hashes. Base URL `https://agent-core.gen.pro/v1`. Public assets may be uploaded raw; private assets must be encrypted before upload because Walrus blobs are public by default. Default automatic sources are downloaded and published assets; generated/uploaded sources are supported for opt-in or manual flows.

    Storage is monthly: Agent Core writes Walrus blobs for two epochs (~28 days), charges Rails operation `backup_to_blockchain` in GB-month units after upload/readback verification, and marks renewal due three days before expiry.'
paths:
  /agents/{agent_id}/proof-of-genesis/backups:
    get:
      operationId: listProofOfGenesisBackups
      servers:
      - url: https://agent-core.gen.pro/v1
      x-mcp-tool: gen_discover
      x-mcp-branch: platform.backups
      x-phase: edit
      summary: List Proof of Genesis backups for an agent
      description: 'Returns Proof of Genesis backup rows newest first. Removed rows are

        hidden by default; pass `include_removed=true` for audit views.'
      tags:
      - Proof of Genesis
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: include_removed
        in: query
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Backup list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofOfGenesisBackupList'
        '401':
          $ref: '#/components/responses/AgentCoreUnauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/AgentCoreValidationError'
    post:
      operationId: createProofOfGenesisBackup
      servers:
      - url: https://agent-core.gen.pro/v1
      x-mcp-tool: gen_platform_action
      x-mcp-branch: create_proof_of_genesis_backup
      x-phase: edit
      summary: Back up an asset to Walrus
      description: 'Creates a manual or event-triggered Proof of Genesis backup for an

        image or video asset. Agent Core checks credits before Walrus work and

        charges operation `backup_to_blockchain` after successful upload and

        readback verification.


        Walrus blobs are public by default. Public assets may be uploaded raw.

        Private assets must be encrypted before upload. Raw private requests

        are rejected before billing or Walrus work.'
      tags:
      - Proof of Genesis
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProofOfGenesisBackupCreate'
      responses:
        '201':
          description: Backup created or existing idempotent backup returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofOfGenesisBackup'
        '402':
          description: Insufficient credits or charge rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Proof of Genesis disabled or pricing not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/AgentCoreUnauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/AgentCoreValidationError'
  /agents/{agent_id}/proof-of-genesis/backups/{backup_id}:
    delete:
      operationId: removeProofOfGenesisBackup
      servers:
      - url: https://agent-core.gen.pro/v1
      x-mcp-tool: gen_platform_action
      x-mcp-branch: remove_proof_of_genesis_backup
      x-phase: edit
      summary: Remove a Proof of Genesis backup from the default asset view
      description: 'Soft-removes a backup row by setting `removed_at`. This hides it from

        the default assets-page list but does not guarantee deletion from Walrus

        or Sui.'
      tags:
      - Proof of Genesis
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: backup_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Removed backup row
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofOfGenesisBackup'
        '401':
          $ref: '#/components/responses/AgentCoreUnauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '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:
    ProofOfGenesisBackup:
      type: object
      properties:
        id:
          type: integer
        agent_id:
          type: string
        status:
          type: string
          enum:
          - uploading
          - synced
          - failed
          - billing_failed
        source_event:
          type: string
          enum:
          - manual
          - generated
          - uploaded
          - downloaded
          - published
        source_url:
          type: string
        asset_type:
          type: string
          enum:
          - video
          - image
        visibility:
          type: string
          enum:
          - private
          - public
        encrypted:
          type: boolean
        encryption_scheme:
          type: string
          nullable: true
        encryption_key_id:
          type: string
          nullable: true
        owner_sui_address:
          type: string
          nullable: true
        custody_mode:
          type: string
          nullable: true
          enum:
          - gen_custody
          - customer_wallet
          - null
          description: Whether GEN or the customer's Sui wallet owns the Walrus object.
        walrus_object_recipient_address:
          type: string
          nullable: true
          description: Sui address passed to Walrus send_object_to for customer-owned object transfer.
        content_sha256:
          type: string
          nullable: true
        size_bytes:
          type: integer
          nullable: true
        content_type:
          type: string
          nullable: true
        walrus_blob_id:
          type: string
          nullable: true
        walrus_blob_object_id:
          type: string
          nullable: true
        walrus_storage_id:
          type: string
          nullable: true
        walrus_start_epoch:
          type: integer
          nullable: true
        walrus_end_epoch:
          type: integer
          nullable: true
        walrus_encoded_length_bytes:
          type: integer
          nullable: true
        walrus_cost_wal:
          type: integer
          nullable: true
        verification_status:
          type: string
          nullable: true
          enum:
          - verified
          - skipped
          - null
        billing_operation:
          type: string
          example: backup_to_blockchain
        billing_charge_id:
          type: integer
          nullable: true
        billing_amount_charged:
          type: string
          nullable: true
        billing_new_balance:
          type: string
          nullable: true
        billing_outboxed:
          type: boolean
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: Approximate Walrus expiry for the current monthly storage period.
        renewal_due_at:
          type: string
          format: date-time
          nullable: true
          description: When Agent Core should attempt monthly renewal, currently three days before expires_at.
        renewal_status:
          type: string
          description: Monthly renewal state for this backup.
          enum:
          - not_due
          - due
          - renewing
          - renewed
          - renewal_blocked
          - renewal_failed
        renewal_attempts:
          type: integer
          description: Number of renewal attempts recorded by Agent Core.
        last_renewed_at:
          type: string
          format: date-time
          nullable: true
        failure_code:
          type: string
          nullable: true
        failure_message:
          type: string
          nullable: true
        removed_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        completed_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.
    AgentCoreError:
      type: object
      required:
      - code
      properties:
        code:
          type: string
          description: The stable machine-readable failure code.
        message:
          type: string
          description: Human-readable failure detail.
    ProofOfGenesisBackupCreate:
      type: object
      description: Manual or event-triggered request to back up a GEN asset to Walrus.
      properties:
        asset_url:
          type: string
          description: GEN asset URL to back up. Preferred field.
        video_url:
          type: string
          description: Legacy alias for asset_url.
        asset_type:
          type: string
          enum:
          - video
          - image
          default: video
        visibility:
          type: string
          enum:
          - private
          - public
          default: private
          description: Private assets must be encrypted before upload. Raw private requests are rejected before billing or Walrus work.
        encrypted:
          type: boolean
          default: false
          description: Whether the asset bytes are already encrypted before Walrus upload. Required with encryption_scheme for private assets.
        encryption_scheme:
          type: string
          nullable: true
          maxLength: 128
          description: Required when visibility is private, e.g. seal/v1.
        encryption_key_id:
          type: string
          nullable: true
          maxLength: 256
          description: Optional key policy/version identifier for private proof metadata.
        owner_sui_address:
          type: string
          nullable: true
          description: Optional customer Sui wallet address that should own the Walrus object. Server-triggered auto-backup can resolve this from the user's Dynamic Sui wallet.
        source_event:
          type: string
          enum:
          - manual
          - generated
          - uploaded
          - downloaded
          - published
          default: manual
        content_type:
          type: string
          nullable: true
        idempotency_key:
          type: string
          description: Stable retry key, e.g. content-resource id plus version.
        metadata:
          type: object
          additionalProperties: true
      anyOf:
      - required:
        - asset_url
      - required:
        - video_url
    ProofOfGenesisBackupList:
      type: object
      required:
      - backups
      properties:
        backups:
          type: array
          items:
            $ref: '#/components/schemas/ProofOfGenesisBackup'
  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.