GEN Billing API

openapi: 3.2.0
info:
  title: Auto Content Engine Billing 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: Billing
  description: Credit balance, plans, transactions, and credit purchase flows.
paths:
  /credit_balance:
    get:
      operationId: getCreditBalance
      x-phase: setup
      summary: Discover — capabilities
      tags:
      - Billing
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent_id: {}
                  organization_id: {}
                  available_credits:
                    type: number
                  paid_media_access:
                    type: boolean
                  generation_access:
                    description: '`UserJobs::GenerationGate.summary`.'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
      x-mcp-tool: gen_discover
      x-mcp-branch: agent.capabilities
  /credit_plans:
    get:
      operationId: getCreditPlans
      x-phase: setup
      summary: Discover — plans
      tags:
      - Billing
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: '`app/resources/credit_plan_resource.rb`.'
                  properties:
                    id: {}
                    name: {}
                    price: {}
                    total_credits: {}
                    cycle: {}
                    code: {}
                    credit_type: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
      x-mcp-tool: gen_discover
      x-mcp-branch: billing.plans
  /credit_transactions:
    get:
      operationId: getCreditTransactions
      x-phase: setup
      summary: Discover — usage
      tags:
      - Billing
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: '`app/resources/credit_transaction_resource.rb`.'
                  properties:
                    id: {}
                    amount: {}
                    purpose: {}
                    is_incoming: {}
                    start_total_used_credits: {}
                    end_total_used_credits: {}
                    created_at: {}
                    source:
                      description: '{service, tool, request_id}, {type, id}, or null.'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
      x-mcp-tool: gen_discover
      x-mcp-branch: billing.usage
  /payment:
    post:
      operationId: postPayment
      x-phase: setup
      summary: Buy credits and manage credit purchases — buy credits
      tags:
      - Billing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: JSON request body.
              required:
              - credit_plan_id
              - success_url
              - cancel_url
              properties:
                credit_plan_id:
                  description: Credit plan being purchased.
                organization_id:
                  description: Workspace paying; omit for a blind (new-workspace) payment.
                quantity:
                  description: Seat quantity; defaults to 1.
                  type: integer
                success_url:
                  type: string
                cancel_url:
                  type: string
                social_account_identifier:
                  description: Required for AURA one-time purchases.
                with_trial:
                  type: boolean
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                - payment_link
                properties:
                  payment_link:
                    description: Stripe Checkout URL.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
      x-mcp-tool: gen_billing_action
      x-mcp-branch: buy_credits
  /seat_checkout:
    post:
      operationId: postSeatCheckout
      x-phase: setup
      summary: Manage workspaces, API keys, preferences, and backups — start seat checkout
      tags:
      - Billing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: JSON request body.
              required:
              - return_url
              properties:
                return_url:
                  type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: {}
                  payment_url: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
      x-mcp-tool: gen_platform_action
      x-mcp-branch: start_seat_checkout
  /subscription_upgrade:
    post:
      operationId: postSubscriptionUpgrade
      x-phase: setup
      summary: Manage workspaces, API keys, preferences, and backups — upgrade workspace
      tags:
      - Billing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: JSON request body.
              required:
              - return_url
              properties:
                credit_plan_id: {}
                return_url: {}
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: {}
                  payment_url: {}
                  credit_plan:
                    type: object
                    description: '`app/resources/credit_plan_resource.rb`.'
                    properties:
                      id: {}
                      name: {}
                      price: {}
                      total_credits: {}
                      cycle: {}
                      code: {}
                      credit_type: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
      x-mcp-tool: gen_platform_action
      x-mcp-branch: upgrade_workspace
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message.
        error_code:
          type: string
          description: Machine-readable error code.
    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.
  responses:
    ApiValidationError:
      description: Validation failed or the request could not be processed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Missing or invalid authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            error_code: unauthorized
  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.