DocuSign Rooms API - v2 — Roles

naftiko: 1.0.0-alpha2
info:
  label: DocuSign Rooms API - v2 — Roles
  description: 'DocuSign Rooms API - v2 — Roles. 5 operations. Lead operation: Docusign Gets roles.. Self-contained Naftiko
    capability covering one Docusign business surface.'
  tags:
  - Docusign
  - Roles
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    DOCUSIGN_API_KEY: DOCUSIGN_API_KEY
capability:
  consumes:
  - type: http
    namespace: rooms-roles
    baseUri: https://rooms.docusign.com/restapi
    description: DocuSign Rooms API - v2 — Roles business capability. Self-contained, no shared references.
    resources:
    - name: v2-accounts-accountId-roles
      path: /v2/accounts/{accountId}/roles
      operations:
      - name: rolesgetroles
        method: GET
        description: Docusign Gets roles.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: onlyAssignable
          in: query
          type: boolean
          description: This parameter is deprecated. Use `filterContext` instead. Note that `filterContext=AssignableRolesBasedOnCompanyPermissions`
            is equivalent to `onlyAssignable=t
        - name: filterContext
          in: query
          type: string
          description: 'Filters the roles by the calling user''s permissions. Valid values are:'
        - name: filter
          in: query
          type: string
          description: A search filter that returns roles by the beginning of the role name. You can enter the beginning of
            the role name only to return all of the roles that begin wi
        - name: startPosition
          in: query
          type: integer
          description: The starting zero-based index position of the result set. The default value is 0.
        - name: count
          in: query
          type: integer
          description: The number of results to return. This value must be a number between `1` and `100` (default).
        - name: accountId
          in: path
          type: string
          description: The globally unique identifier (GUID) for the account.
          required: true
      - name: rolescreaterole
        method: POST
        description: Docusign Creates a role.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: accountId
          in: path
          type: string
          description: The globally unique identifier (GUID) for the account.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v2-accounts-accountId-roles-roleId
      path: /v2/accounts/{accountId}/roles/{roleId}
      operations:
      - name: rolesgetrole
        method: GET
        description: Docusign Gets a role.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: roleId
          in: path
          type: integer
          description: The ID of the role.
          required: true
        - name: includeIsAssigned
          in: query
          type: boolean
          description: When **true,** the response includes the `isAssigned` property, which specifies whether the role is
            currently assigned to any users. The default is **false.**
        - name: accountId
          in: path
          type: string
          description: (Required) The globally unique identifier (GUID) for the account.
          required: true
      - name: rolesupdaterole
        method: PUT
        description: Docusign Updates a role.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: roleId
          in: path
          type: integer
          description: The ID of the role.
          required: true
        - name: accountId
          in: path
          type: string
          description: The globally unique identifier (GUID) for the account.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: rolesdeleterole
        method: DELETE
        description: Docusign Deletes a role.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: roleId
          in: path
          type: integer
          description: The ID of the role to delete.
          required: true
        - name: accountId
          in: path
          type: string
          description: The globally unique identifier (GUID) for the account.
          required: true
    authentication:
      type: apikey
      key: Authorization
      value: '{{env.DOCUSIGN_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: rooms-roles-rest
    port: 8080
    description: REST adapter for DocuSign Rooms API - v2 — Roles. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/v2/accounts/{accountid}/roles
      name: v2-accounts-accountid-roles
      description: REST surface for v2-accounts-accountId-roles.
      operations:
      - method: GET
        name: rolesgetroles
        description: Docusign Gets roles.
        call: rooms-roles.rolesgetroles
        with:
          onlyAssignable: rest.onlyAssignable
          filterContext: rest.filterContext
          filter: rest.filter
          startPosition: rest.startPosition
          count: rest.count
          accountId: rest.accountId
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: rolescreaterole
        description: Docusign Creates a role.
        call: rooms-roles.rolescreaterole
        with:
          accountId: rest.accountId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/accounts/{accountid}/roles/{roleid}
      name: v2-accounts-accountid-roles-roleid
      description: REST surface for v2-accounts-accountId-roles-roleId.
      operations:
      - method: GET
        name: rolesgetrole
        description: Docusign Gets a role.
        call: rooms-roles.rolesgetrole
        with:
          roleId: rest.roleId
          includeIsAssigned: rest.includeIsAssigned
          accountId: rest.accountId
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: rolesupdaterole
        description: Docusign Updates a role.
        call: rooms-roles.rolesupdaterole
        with:
          roleId: rest.roleId
          accountId: rest.accountId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: rolesdeleterole
        description: Docusign Deletes a role.
        call: rooms-roles.rolesdeleterole
        with:
          roleId: rest.roleId
          accountId: rest.accountId
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: rooms-roles-mcp
    port: 9090
    transport: http
    description: MCP adapter for DocuSign Rooms API - v2 — Roles. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: docusign-gets-roles
      description: Docusign Gets roles.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: rooms-roles.rolesgetroles
      with:
        onlyAssignable: tools.onlyAssignable
        filterContext: tools.filterContext
        filter: tools.filter
        startPosition: tools.startPosition
        count: tools.count
        accountId: tools.accountId
      outputParameters:
      - type: object
        mapping: $.
    - name: docusign-creates-role
      description: Docusign Creates a role.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: rooms-roles.rolescreaterole
      with:
        accountId: tools.accountId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: docusign-gets-role
      description: Docusign Gets a role.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: rooms-roles.rolesgetrole
      with:
        roleId: tools.roleId
        includeIsAssigned: tools.includeIsAssigned
        accountId: tools.accountId
      outputParameters:
      - type: object
        mapping: $.
    - name: docusign-updates-role
      description: Docusign Updates a role.
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: rooms-roles.rolesupdaterole
      with:
        roleId: tools.roleId
        accountId: tools.accountId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: docusign-deletes-role
      description: Docusign Deletes a role.
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: rooms-roles.rolesdeleterole
      with:
        roleId: tools.roleId
        accountId: tools.accountId
      outputParameters:
      - type: object
        mapping: $.