GEN Organizations API

openapi: 3.2.0
info:
  title: Auto Content Engine Organizations 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: Organizations
  description: Manage organizations (workspaces).
paths:
  /x402_credit_purchase:
    post:
      operationId: createX402CreditPurchase
      x-mcp-tool: gen_billing_action
      x-mcp-branch: create_x402_credit_purchase
      x-phase: export
      summary: Create an x402 credit-purchase quote
      description: 'Create a 402 quote to fund workspace credits with USDC over x402.

        Pass either `amount_usd` or `credits`; x402 credit purchases are not

        limited to fixed credit packs. If `network` is omitted, GEN returns

        every configured payment option in `payment_methods` and

        `payment_required.accepts` instead of silently choosing one chain.


        Show the Sui, Solana, and Base options to the user or calling agent,

        sign one matching `payment_required.accepts[]` entry, then settle/retry

        with `PAYMENT-SIGNATURE`, `checkout_session_id`, and the chosen network.

        Workspace funding wallets are backend settlement/sweeping

        infrastructure; the user-facing choices are the returned payment

        methods.'
      tags:
      - Organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - workspace_id
              properties:
                workspace_id:
                  type: string
                  description: Workspace/organization receiving credits.
                amount_usd:
                  type: string
                  description: Arbitrary USD amount to convert to credits.
                  example: '1.25'
                credits:
                  type: string
                  description: Arbitrary credit amount to buy.
                  example: '100.0'
                network:
                  type: string
                  enum:
                  - sui
                  - solana
                  - base
                  description: Optional selected payment network. Omit to receive all configured options.
      responses:
        '402':
          description: x402 payment required. Sign one returned payment method and settle/retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402CreditPurchaseQuote'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Missing amount, invalid workspace, or quote failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations:
    get:
      operationId: listOrganizations
      x-mcp-tool: gen_discover
      x-mcp-branch: platform.organizations
      x-phase: setup
      summary: List organizations
      description: Returns all organizations the authenticated user belongs to.
      tags:
      - Organizations
      responses:
        '200':
          description: List of organizations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Organization'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
    post:
      operationId: createOrganization
      x-mcp-tool: gen_platform_action
      x-mcp-branch: create_organization
      x-phase: setup
      summary: Create an organization
      tags:
      - Organizations
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - organization
              properties:
                organization[name]:
                  type: string
                  example: My Company
                organization[avatar]:
                  type: string
                  format: binary
                  description: Organization avatar image.
      responses:
        '201':
          description: Organization created
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization_id:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations/{organization_id}:
    get:
      operationId: getOrganization
      x-mcp-tool: gen_discover
      x-mcp-branch: platform.organization
      x-phase: setup
      summary: Get an organization
      tags:
      - Organizations
      parameters:
      - name: organization_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Organization details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '422':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
    patch:
      operationId: updateOrganization
      x-mcp-tool: gen_platform_action
      x-mcp-branch: update_organization
      x-phase: setup
      summary: Update an organization
      description: Requires owner or manager role.
      tags:
      - Organizations
      parameters:
      - name: organization_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                organization[name]:
                  type: string
                organization[avatar]:
                  type: string
                  format: binary
      responses:
        '200':
          description: Organization updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization_id:
                    type: string
        '403':
          description: Forbidden (not owner or manager)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Organization not found or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
    delete:
      operationId: deleteOrganization
      x-mcp-tool: gen_platform_action
      x-mcp-branch: delete_organization
      x-phase: setup
      summary: Delete an organization
      description: Permanently deletes the organization and all associated data. Requires owner role. Irreversible.
      tags:
      - Organizations
      parameters:
      - name: organization_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Organization deleted
        '403':
          description: Forbidden (not owner)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
  /organizations/{organization_id}/user_organizations:
    get:
      operationId: getOrganizationsByOrganizationIdUserOrganizations
      x-phase: setup
      summary: Discover — members
      tags:
      - Organizations
      parameters:
      - name: organization_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id: {}
                    email: {}
                    name: {}
                    organization_role: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ApiValidationError'
      x-mcp-tool: gen_discover
      x-mcp-branch: platform.members
    post:
      operationId: postOrganizationsByOrganizationIdUserOrganizations
      x-phase: setup
      summary: Manage workspaces, API keys, preferences, and backups — invite member
      tags:
      - Organizations
      parameters:
      - name: organization_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: JSON request body.
              required:
              - username_or_email
              properties:
                username_or_email:
                  description: Email or username of the member to invite.
                role:
                  description: One of the `UserOrganization` roles.
      responses:
        '200':
          description: Success.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ApiValidationError'
      x-mcp-tool: gen_platform_action
      x-mcp-branch: invite_member
  /organizations/{organization_id}/user_organizations/{id}:
    delete:
      operationId: deleteOrganizationsByOrganizationIdUserOrganizationsById
      x-phase: setup
      summary: Manage workspaces, API keys, preferences, and backups — leave workspace
      tags:
      - Organizations
      parameters:
      - name: organization_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ApiValidationError'
      x-mcp-tool: gen_platform_action
      x-mcp-branch: leave_workspace
  /projects/{id}/set_project_share:
    put:
      operationId: putProjectsByIdSetProjectShare
      x-phase: setup
      summary: Create, update, or remove assistants and their profiles — set project share
      tags:
      - Organizations
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: JSON request body.
              required:
              - permission
              properties:
                permission:
                  description: '`public` mints/reuses a share token; `private` removes all shares.'
                  enum:
                  - public
                  - private
                agent_id:
                  type: string
                  description: Agent context; the controller reads params[:agent_id] (`require_agent!`).
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                description: '`ProjectShareResource` for `public`; `{message}` for `private`.'
                properties:
                  share_token: {}
                  permission: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ApiValidationError'
      x-mcp-tool: gen_agent_action
      x-mcp-branch: set_project_share
  /x402_credit_purchase/settle:
    post:
      operationId: postX402CreditPurchaseSettle
      x-phase: setup
      summary: Buy credits and manage credit purchases — settle x402 credit purchase
      tags:
      - Organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: JSON body. The signed payment travels in the `PAYMENT-SIGNATURE` header.
              required:
              - workspace_id
              - checkout_session_id
              properties:
                workspace_id:
                  description: Workspace receiving the credits (alias `organization_id`).
                checkout_session_id:
                  description: The `checkout_session_id` from the create/quote response (alias `x402_checkout_session_id`).
                network:
                  description: Payment network the signature was made on.
                  enum:
                  - sui
                  - solana
                  - base
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  workspace_id: {}
                  checkout_session_id: {}
                  idempotent:
                    type: boolean
                  x402_payment_event_id: {}
                  credit_purchase:
                    type: object
                    properties:
                      id: {}
                      credit_type: {}
                      total_credits: {}
                      total_used_credits: {}
                      status: {}
                      payment_type: {}
                      payment_id: {}
                      created_at:
                        type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ApiValidationError'
      x-mcp-tool: gen_billing_action
      x-mcp-branch: settle_x402_credit_purchase
components:
  schemas:
    X402PaymentRequired:
      type: object
      required:
      - x402Version
      - accepts
      properties:
        x402Version:
          type: integer
          example: 2
        error:
          type: string
        paymentMethods:
          type: array
          items:
            $ref: '#/components/schemas/X402PaymentMethod'
        accepts:
          type: array
          items:
            $ref: '#/components/schemas/X402Accept'
    X402PaymentMethod:
      type: object
      required:
      - network
      - x402Network
      - asset
      - payTo
      - amountUsd
      - credits
      properties:
        network:
          type: string
          enum:
          - sui
          - solana
          - base
          description: Human-readable payment rail to show to users and agents.
        x402Network:
          type: string
          description: x402 network identifier used inside `payment_required.accepts`.
          examples:
          - sui
          - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
          - eip155:8453
        asset:
          type: string
          example: USDC
        payTo:
          type: string
          description: Treasury payment recipient for this rail.
        amountUsd:
          type: string
          description: USD amount represented by this payment method.
        credits:
          type: string
          description: Credits that will be issued after settlement.
    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.
    X402Accept:
      type: object
      required:
      - scheme
      - network
      - asset
      - maxAmountRequired
      - payTo
      - resource
      properties:
        scheme:
          type: string
          example: exact
        network:
          type: string
        asset:
          type: string
          example: USDC
        maxAmountRequired:
          type: string
          description: Atomic USDC amount required by this accept entry.
        payTo:
          type: string
        resource:
          type: string
          example: https://api.gen.pro/v1/x402_credit_purchase
        description:
          type: string
        mimeType:
          type: string
          example: application/json
        extra:
          type: object
          properties:
            checkoutSessionId:
              type: integer
            workspaceId:
              type: integer
            pricingMode:
              type: string
              enum:
              - custom_amount
              - credit_plan
            amountUsd:
              type: string
            credits:
              type: string
            network:
              type: string
              enum:
              - sui
              - solana
              - base
            referenceCreditPlanId:
              type: integer
              nullable: true
    X402CreditPurchaseQuote:
      type: object
      required:
      - checkout_session_id
      - workspace_id
      - amount_usd
      - credits
      - payment_methods
      - payment_required
      properties:
        checkout_session_id:
          type: integer
        workspace_id:
          type: integer
        pricing_mode:
          type: string
          enum:
          - custom_amount
          - credit_plan
        reference_credit_plan_id:
          type: integer
          nullable: true
        credit_plan_id:
          type: integer
          nullable: true
        quantity:
          type: integer
        amount_usd:
          type: string
        credits:
          type: string
        payment_methods:
          type: array
          description: User/agent-facing Sui, Solana, and Base payment options.
          items:
            $ref: '#/components/schemas/X402PaymentMethod'
        payment_required:
          $ref: '#/components/schemas/X402PaymentRequired'
    Organization:
      type: object
      properties:
        id:
          type: string
        uuid:
          type: string
        organization_id:
          type: string
        name:
          type: string
        avatar:
          type: object
          nullable: true
          properties:
            url:
              type: string
              format: uri
            thumbnail_url:
              type: string
              format: uri
        user_role:
          type: string
        credit:
          type: number
        available_credit:
          type: object
          properties:
            generic:
              type: number
            aura:
              type: number
        total_members:
          type: integer
        credit_plan:
          type: object
          nullable: true
          properties:
            id:
              type: string
            name:
              type: string
            cycle:
              type: string
  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'
    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.