> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mls.onchainden.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Propose updating groups

> [Admin Only] Creates a proposal to update existing groups.

Note: Name changes are applied immediately upon request submission and do not 
require proposal execution. Only member updates require the full proposal workflow.
Only admin API members can make requests to this endpoint.




## OpenAPI

````yaml /openapi.yaml post /groups/proposals/update
openapi: 3.1.0
info:
  title: Den API
  version: 2.0.0
  description: >
    API for managing wallets with Den. This API provides programmatic access to
    all platform capabilities

    including wallet accounts, members, groups, policies, and transactions.


    ## Authentication

    All API requests require authentication via Bearer token in the
    Authorization header.


    ## Idempotency

    All mutation requests (POST, PUT, DELETE) require an X-Idempotency-Key
    header for safe retries.


    ## Two Transaction Types

    - **Account Transactions**: Value movement and contract interactions
    (governed by policies)

    - **Organization Operations**: Governance/admin changes (governed by admin
    threshold)
servers:
  - url: https://api.onchainden.com/api/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Members
    description: Manage organization members
  - name: Groups
    description: Manage member groups
  - name: Policies
    description: Manage transaction policies
  - name: Accounts
    description: Manage wallet accounts
  - name: Transactions
    description: Create and execute account transactions
  - name: Admins
    description: Manage admin configuration
  - name: AuditLogs
    description: View audit log entries
paths:
  /groups/proposals/update:
    post:
      tags:
        - Groups
      summary: Propose updating groups
      description: >
        [Admin Only] Creates a proposal to update existing groups.


        Note: Name changes are applied immediately upon request submission and
        do not 

        require proposal execution. Only member updates require the full
        proposal workflow.

        Only admin API members can make requests to this endpoint.
      operationId: createGroupUpdateProposal
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              properties:
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/GroupUpdateItem'
                  description: List of group updates
            example:
              items:
                - id: grp_123
                  name: Finance & Accounting
                  memberUpdates:
                    - action: addMember
                      id: mem_3
                    - action: removeMember
                      id: mem_2
      responses:
        '200':
          description: Group update proposal created
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/OrganizationOperationGroupsUpdate'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '426':
          $ref: '#/components/responses/UpgradeRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
        - lang: javascript
          label: SDK
          source: |
            const client = new DenClient({ apiKey: 'ck_live_...' });
            const proposal = await client.proposeGroupUpdate({
              items: [
                {
                  id: 'grp_123',
                  name: 'Finance & Accounting',
                  memberUpdates: [
                    { action: 'addMember', id: 'mem_3' },
                    { action: 'removeMember', id: 'mem_2' },
                  ],
                },
              ],
            });
components:
  parameters:
    IdempotencyKey:
      name: X-Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        format: uuid
      description: Idempotency key for safely retrying mutation requests.
  schemas:
    GroupUpdateItem:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          example: grp_123
        name:
          type: string
          example: Finance & Accounting
        memberUpdates:
          type: array
          items:
            $ref: '#/components/schemas/GroupMemberUpdate'
    OrganizationOperationGroupsUpdate:
      allOf:
        - $ref: '#/components/schemas/OrganizationOperationBase'
        - type: object
          properties:
            resourceType:
              type: string
              const: groups
            action:
              type: string
              const: update
            data:
              $ref: '#/components/schemas/GroupUpdateProposalData'
      example:
        id: prop_grp_update_123
        resourceType: groups
        action: update
        signatureStatus: approvalReady
        executionStatus: completed
        threshold: 2
        approvals: []
        rejections: []
        createdAt: '2026-01-18T00:00:00.000Z'
        expiresAt: '2026-01-25T00:00:00.000Z'
        data:
          items:
            - id: grp_123
              name: Finance & Accounting
              members:
                - id: mem_1
                  name: Alice
                  type: user
                  walletAddress: 0xabc...
                - id: mem_3
                  name: Cara
                  type: user
                  walletAddress: 0xdef...
              createdAt: '2026-01-01T00:00:00.000Z'
              updatedAt: '2026-01-02T00:00:00.000Z'
        result:
          resolution: approved
          resources:
            - type: group
              id: grp_123
              uri: /api/v1/groups/grp_123
    GroupMemberUpdate:
      type: object
      required:
        - action
        - id
      properties:
        action:
          $ref: '#/components/schemas/GroupMemberUpdateAction'
        id:
          type: string
          description: Member ID to add or remove
          example: mem_3
    OrganizationOperationBase:
      type: object
      required:
        - id
        - resourceType
        - action
        - signatureStatus
        - executionStatus
        - threshold
        - approvals
        - rejections
        - createdAt
        - expiresAt
        - data
      properties:
        id:
          type: string
          example: prop_abc
        resourceType:
          $ref: '#/components/schemas/ResourceType'
        action:
          $ref: '#/components/schemas/ProposalAction'
        signatureStatus:
          $ref: '#/components/schemas/SignatureStatus'
        executionStatus:
          $ref: '#/components/schemas/ExecutionStatus'
        threshold:
          type: integer
          example: 2
        approvals:
          type: array
          items:
            $ref: '#/components/schemas/MemberSummary'
        rejections:
          type: array
          items:
            $ref: '#/components/schemas/MemberSummary'
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        data:
          description: Proposed resource state after execution.
        signingPayloads:
          $ref: '#/components/schemas/ReviewSigningPayloads'
          description: >-
            Present only while signatures can still be collected for non-expired
            organization operations
        result:
          $ref: '#/components/schemas/OrganizationOperationResult'
          description: Present only after execution
    GroupUpdateProposalData:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Group'
          description: Full group state after applying the change
    Error:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    GroupMemberUpdateAction:
      type: string
      enum:
        - addMember
        - removeMember
    ResourceType:
      type: string
      enum:
        - members
        - groups
        - policies
        - accounts
        - admins
    ProposalAction:
      type: string
      enum:
        - create
        - update
        - remove
        - delete
    SignatureStatus:
      type: string
      enum:
        - pendingInitiatorSignature
        - pendingReviewSignatures
        - approvalReady
        - rejectionReady
        - approvalAndRejectionReady
        - expired
      description: >
        Current signature state in the approval workflow:

        - pendingInitiatorSignature: Account Transactions only - awaiting
        initiator signature

        - pendingReviewSignatures: Neither approval nor rejection threshold met

        - approvalReady: Approval threshold met, rejection not met

        - rejectionReady: Rejection threshold met, approval not met

        - approvalAndRejectionReady: Both thresholds met, either can be executed

        - expired: Proposal expired before execution
    ExecutionStatus:
      type: string
      nullable: true
      enum:
        - null
        - processing
        - completed
        - rejected
        - failed
        - blocked
      description: |
        Execution lifecycle state:
        - null: Not yet attempted
        - processing: Execution in progress
        - completed: Successfully executed
        - rejected: Successfully rejected
        - failed: Execution failed
        - blocked: Blocked by policy or constraint
    MemberSummary:
      type: object
      description: Abbreviated member info used in approvals/rejections arrays
      required:
        - id
        - name
        - type
        - walletAddress
      properties:
        id:
          type: string
          example: mem_123
        name:
          type: string
          example: Alice
        type:
          $ref: '#/components/schemas/MemberType'
        walletAddress:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
    ReviewSigningPayloads:
      type: object
      required:
        - approvePayload
        - rejectPayload
      properties:
        approvePayload:
          type: string
          description: Payload for approval signature
        rejectPayload:
          type: string
          description: Payload for rejection signature
    OrganizationOperationResult:
      type: object
      required:
        - resolution
      properties:
        resolution:
          type: string
          enum:
            - approved
            - rejected
          description: Final outcome of the proposal execution
        resources:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationOperationResultResource'
          description: Resources created or modified. Empty when rejected.
    Group:
      type: object
      required:
        - id
        - name
        - members
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: Unique identifier for the group
          example: grp_123
        name:
          type: string
          description: Display name of the group
          example: Finance Team
        members:
          type: array
          items:
            $ref: '#/components/schemas/MemberSummary'
          description: List of members in the group
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorObject:
      type: object
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: Human-readable error message
        details:
          $ref: '#/components/schemas/ErrorDetails'
    MemberType:
      type: string
      enum:
        - user
        - api
      description: Type of member (user for human members, api for bots)
    OrganizationOperationResultResource:
      type: object
      required:
        - type
        - id
      properties:
        type:
          type: string
          description: Resource type that was created, updated, or removed
          example: member
        id:
          type: string
          description: Unique identifier of the affected resource
          example: mem_new1
        uri:
          type: string
          description: >-
            Canonical URI for the affected resource (omitted for
            removals/deletes)
          example: /api/v1/members/mem_new1
    ErrorCode:
      type: string
      enum:
        - validationError
        - invalidSignature
        - unauthorized
        - forbidden
        - notFound
        - conflict
        - thresholdNotMet
        - proposalExpired
        - idempotencyConflict
        - upgradeRequired
        - rateLimited
        - internalError
      description: Machine-readable error codes
    ErrorDetails:
      type: object
      additionalProperties: true
      description: Additional error details (structure varies by error type)
      properties:
        field:
          type: string
          description: Field that caused the error (for validation errors)
        message:
          type: string
          description: Detailed message about the error
  responses:
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: validationError
              message: Validation failed
              details:
                field: name
                message: Name is required
    Unauthorized:
      description: API key is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Invalid API key
    Forbidden:
      description: Not permitted for this action
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: Not permitted for this action
    Conflict:
      description: Resource already exists or proposal already queued
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: conflict
              message: Resource already exists
    UnprocessableEntity:
      description: >-
        Request cannot be processed due to proposal state or idempotency
        conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            thresholdNotMet:
              value:
                error:
                  code: thresholdNotMet
                  message: Threshold not reached
            proposalExpired:
              value:
                error:
                  code: proposalExpired
                  message: Proposal expired
            idempotencyConflict:
              value:
                error:
                  code: idempotencyConflict
                  message: Idempotency key used with different request body
    UpgradeRequired:
      description: HTTPS required; plain HTTP requests are rejected
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: upgradeRequired
              message: HTTPS required
    RateLimited:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rateLimited
              message: Too many requests
    InternalError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: internalError
              message: Server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API key authentication. Include your API key in the Authorization
        header.

````