> ## Documentation Index > Fetch the complete documentation index at: https://docs.visitoai.com/llms.txt > Use this file to discover all available pages before exploring further. # Update an action configuration > Requires `actions:write`. Body uses the family editing shape, not execution inputs. HTTP uses a partial patch; omit auth.value to preserve a secret. Collection and Sheets require revision and the full definition. Collection edits without switches preserve the current published version until lifecycle publish; edits with switches publish a new immutable snapshot. Concurrent revisions return 409. The three-state mode is also accepted and counts as explicit state input; do not mix it with legacy switches. Explicit scopeMode is supported (HTTP at configuration root, collection/Sheets in definition); omission preserves legacy semantics. ## OpenAPI ````yaml /openapi.json patch /actions/{actionId}/configuration openapi: 3.0.3 info: title: Visito M2M API version: 1.0.0 description: >- Tenant-scoped server-to-server API for channels, conversations, commerce, custom AI tools, and WhatsApp templates. Send operations are asynchronous and return queued acknowledgements. Expansion adds conversation controls, knowledge, sales opportunities, delivery status, reporting, and signed webhooks. servers: - url: https://platform-api.visitoai.com/m2m/v1 description: Production security: - bearerAuth: [] tags: - name: Channels - name: Conversations - name: Commerce - name: Custom tools - name: WhatsApp templates - name: Properties - name: Knowledge - name: Sales CRM - name: Delivery - name: Reporting - name: Webhooks paths: /actions/{actionId}/configuration: patch: tags: - Actions summary: Update an action configuration description: >- Requires `actions:write`. Body uses the family editing shape, not execution inputs. HTTP uses a partial patch; omit auth.value to preserve a secret. Collection and Sheets require revision and the full definition. Collection edits without switches preserve the current published version until lifecycle publish; edits with switches publish a new immutable snapshot. Concurrent revisions return 409. The three-state mode is also accepted and counts as explicit state input; do not mix it with legacy switches. Explicit scopeMode is supported (HTTP at configuration root, collection/Sheets in definition); omission preserves legacy semantics. operationId: updateAction parameters: - name: actionId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateActionRequest' responses: '200': description: Successful action operation content: application/json: schema: $ref: '#/components/schemas/ActionConfigurationResponse' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' components: schemas: UpdateActionRequest: oneOf: - $ref: '#/components/schemas/ToolPatchRequest' - $ref: '#/components/schemas/CollectionConfigurationPatch' - $ref: '#/components/schemas/SheetsConfigurationPatch' ActionConfigurationResponse: type: object additionalProperties: false properties: action: $ref: '#/components/schemas/ActionConfiguration' required: - action ToolPatchRequest: type: object minProperties: 1 properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$ description: type: string minLength: 1 maxLength: 2000 parameters: type: object additionalProperties: true endpoint: type: object properties: url: type: string format: uri method: type: string enum: - GET - POST timeoutMs: type: integer minimum: 500 maximum: 30000 additionalProperties: false auth: $ref: '#/components/schemas/ToolAuthInput' active: type: boolean readOnly: type: boolean allowInPlayground: type: boolean propertyIds: type: array items: type: string mode: type: string enum: - 'off' - playground - active description: >- off: unavailable; playground: Playground only; active: live channels and Playground. Do not combine mode with legacy state fields. playgroundOnly: type: boolean description: >- Optional explicit availability setting; prefer mode. Omission preserves legacy HTTP eligibility. scopeMode: type: string enum: - tenant - businesses description: >- tenant applies throughout this workspace and requires empty propertyIds; businesses uses explicitly selected active business IDs. Omission preserves legacy scope semantics. Scope is not an execution permission. additionalProperties: false not: anyOf: - required: - mode - active - required: - mode - playgroundOnly - required: - mode - allowInPlayground CollectionConfigurationPatch: type: object additionalProperties: false properties: definition: $ref: '#/components/schemas/CollectionDefinition' webhook: $ref: '#/components/schemas/ActionWebhookInput' active: type: boolean playgroundOnly: type: boolean revision: type: integer minimum: 1 mode: type: string enum: - 'off' - playground - active description: >- off: unavailable; playground: Playground only; active: live channels and Playground. Do not combine mode with legacy state fields. required: - definition - revision not: anyOf: - required: - mode - active - required: - mode - playgroundOnly - required: - mode - allowInPlayground SheetsConfigurationPatch: type: object additionalProperties: false properties: definition: $ref: '#/components/schemas/SheetsDefinition' active: type: boolean playgroundOnly: type: boolean revision: type: integer minimum: 1 mode: type: string enum: - 'off' - playground - active description: >- off: unavailable; playground: Playground only; active: live channels and Playground. Do not combine mode with legacy state fields. required: - definition - revision not: anyOf: - required: - mode - active - required: - mode - playgroundOnly - required: - mode - allowInPlayground ActionConfiguration: oneOf: - type: object additionalProperties: false properties: actionId: type: string family: type: string enum: - http revision: type: integer minimum: 1 nullable: true supportedOperations: type: array items: type: string enum: - configuration - update - state - lifecycle - delete - test state: $ref: '#/components/schemas/ActionState' configuration: $ref: '#/components/schemas/Tool' required: - actionId - family - revision - supportedOperations - state - configuration - type: object additionalProperties: false properties: actionId: type: string family: type: string enum: - collection revision: type: integer minimum: 1 nullable: true supportedOperations: type: array items: type: string enum: - configuration - update - state - lifecycle - delete - test state: $ref: '#/components/schemas/ActionState' configuration: $ref: '#/components/schemas/CollectionConfiguration' signingSecret: type: string description: >- One-time secret returned only by a mutation that creates a signing key; never on reads. required: - actionId - family - revision - supportedOperations - state - configuration - type: object additionalProperties: false properties: actionId: type: string family: type: string enum: - sheets revision: type: integer minimum: 1 nullable: true supportedOperations: type: array items: type: string enum: - configuration - update - state - lifecycle - delete - test state: $ref: '#/components/schemas/ActionState' configuration: $ref: '#/components/schemas/SheetsConfiguration' required: - actionId - family - revision - supportedOperations - state - configuration ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string example: M2M_AUTH_INSUFFICIENT_SCOPE message: type: string details: type: object additionalProperties: true example: error: code: M2M_AUTH_INSUFFICIENT_SCOPE message: M2M credential does not have required scope. details: requiredScopes: - conversations:write missingScopes: - conversations:write ToolAuthInput: type: object required: - type properties: type: type: string enum: - none - bearer - api_key headerName: type: string value: type: string writeOnly: true additionalProperties: false CollectionDefinition: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 80 whenToUse: type: string maxLength: 1000 fields: type: array items: $ref: '#/components/schemas/ActionField' maxItems: 20 propertyIds: type: array items: type: string maxLength: 120 minLength: 1 maxItems: 50 uniqueItems: true scopeMode: type: string enum: - tenant - businesses description: >- tenant applies throughout this workspace and requires empty propertyIds; businesses uses explicitly selected active business IDs. Omission preserves legacy scope semantics. Scope is not an execution permission. required: - name - whenToUse - fields - propertyIds ActionWebhookInput: type: object additionalProperties: false properties: url: type: string description: HTTPS delivery destination. Empty disables delivery. bearer: type: string maxLength: 4000 writeOnly: true description: >- Omit to preserve; empty clears the bearer. Stored credentials are never returned. SheetsDefinition: oneOf: - $ref: '#/components/schemas/LegacySheetsDefinition' - $ref: '#/components/schemas/SheetsPermissionDefinition' ActionState: type: object additionalProperties: false properties: active: type: boolean playgroundOnly: type: boolean status: type: string enum: - draft - published - paused - archived allowInPlayground: type: boolean mode: type: string enum: - 'off' - playground - active - legacy_live_only description: >- Computed availability. legacy_live_only preserves existing HTTP live access without Playground access until explicitly changed. required: - active Tool: type: object required: - toolId - tenantId - name - description - parameters - endpoint - auth - active - readOnly - allowInPlayground - propertyIds - createdAt - updatedAt properties: toolId: type: string tenantId: type: string name: type: string description: type: string parameters: type: object additionalProperties: true endpoint: $ref: '#/components/schemas/ToolEndpoint' auth: type: object required: - type - configured properties: type: type: string enum: - none - bearer - api_key headerName: type: string secretLastFour: type: string configured: type: boolean active: type: boolean readOnly: type: boolean allowInPlayground: type: boolean propertyIds: type: array items: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time mode: type: string enum: - 'off' - playground - active - legacy_live_only description: >- Computed availability. legacy_live_only preserves existing HTTP live access without Playground access until explicitly changed. playgroundOnly: type: boolean configurationVersion: type: string nullable: true description: >- Current configuration timestamp. Confirm this exact version for each write-capable direct HTTP test. scopeMode: type: string enum: - tenant - businesses description: >- tenant applies throughout this workspace and requires empty propertyIds; businesses uses explicitly selected active business IDs. Omission preserves legacy scope semantics. Scope is not an execution permission. CollectionConfiguration: type: object additionalProperties: false properties: actionId: type: string revision: type: integer minimum: 1 version: type: integer minimum: 0 status: type: string enum: - draft - published - paused - archived active: type: boolean playgroundOnly: type: boolean draft: $ref: '#/components/schemas/CollectionDefinition' published: $ref: '#/components/schemas/CollectionDefinition' webhookUrl: type: string hasBearer: type: boolean mode: type: string enum: - 'off' - playground - active description: >- Computed availability. legacy_live_only preserves existing HTTP live access without Playground access until explicitly changed. required: - actionId - revision - version - status - active - playgroundOnly - draft - webhookUrl - hasBearer SheetsConfiguration: type: object additionalProperties: false properties: actionId: type: string revision: type: integer minimum: 1 version: type: integer minimum: 1 active: type: boolean playgroundOnly: type: boolean definition: $ref: '#/components/schemas/SheetsDefinition' mode: type: string enum: - 'off' - playground - active description: >- Computed availability. legacy_live_only preserves existing HTTP live access without Playground access until explicitly changed. operations: type: array maxItems: 3 items: type: object additionalProperties: false properties: name: type: string readOnly: type: boolean inputSchema: type: object additionalProperties: true required: - name - readOnly - inputSchema required: - actionId - revision - version - active - playgroundOnly - definition ActionField: type: object additionalProperties: false properties: key: type: string pattern: ^[a-z][a-z0-9_]*$ maxLength: 48 description: type: string maxLength: 300 type: type: string enum: - text - email - phone - date - number - integer - boolean - single-select - multi-select required: type: boolean choices: type: array items: type: string maxLength: 80 maxItems: 30 required: - key - description - type - required LegacySheetsDefinition: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 80 whenToUse: type: string maxLength: 1000 fields: type: array items: $ref: '#/components/schemas/ActionField' maxItems: 20 propertyIds: type: array items: type: string maxLength: 120 minLength: 1 maxItems: 50 uniqueItems: true production: $ref: '#/components/schemas/SheetsTarget' test: $ref: '#/components/schemas/SheetsTarget' steps: type: array items: $ref: '#/components/schemas/SheetsStep' minItems: 1 maxItems: 5 scopeMode: type: string enum: - tenant - businesses description: >- tenant applies throughout this workspace and requires empty propertyIds; businesses uses explicitly selected active business IDs. Omission preserves legacy scope semantics. Scope is not an execution permission. schemaVersion: type: integer enum: - 1 executionPolicy: type: string enum: - legacy required: - name - whenToUse - fields - propertyIds - production - test - steps SheetsPermissionDefinition: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 80 whenToUse: type: string maxLength: 1000 scopeMode: type: string enum: - tenant - businesses description: >- tenant applies throughout this workspace and requires empty propertyIds; businesses uses explicitly selected active business IDs. Omission preserves legacy scope semantics. Scope is not an execution permission. propertyIds: type: array items: type: string maxLength: 120 minLength: 1 maxItems: 50 uniqueItems: true schemaVersion: type: integer enum: - 2 executionPolicy: type: string enum: - columns production: $ref: '#/components/schemas/SheetsPermissionTarget' test: $ref: '#/components/schemas/SheetsPermissionTarget' columns: type: array items: $ref: '#/components/schemas/SheetsPermissionColumn' minItems: 1 maxItems: 30 identifyingColumns: type: array items: type: string maxItems: 5 uniqueItems: true recordId: oneOf: - type: object additionalProperties: false properties: columnId: type: string generation: type: string enum: - input - visito required: - columnId - generation - type: object additionalProperties: false properties: generation: type: string enum: - columns columnIds: type: array items: type: string minItems: 1 maxItems: 5 uniqueItems: true required: - generation - columnIds required: - schemaVersion - name - whenToUse - propertyIds - production - columns - identifyingColumns ToolEndpoint: type: object required: - url - method properties: url: type: string format: uri method: type: string enum: - GET - POST timeoutMs: type: integer minimum: 500 maximum: 30000 additionalProperties: false SheetsTarget: type: object additionalProperties: false properties: connectionId: type: string minLength: 1 maxLength: 160 spreadsheetId: type: string minLength: 1 maxLength: 160 tabs: type: object minProperties: 1 maxProperties: 5 additionalProperties: type: object additionalProperties: false properties: sheetId: type: integer minimum: 0 keyColumn: type: string minLength: 1 maxLength: 160 columns: type: array items: type: string minLength: 1 maxLength: 160 minItems: 1 maxItems: 30 uniqueItems: true required: - sheetId - keyColumn - columns required: - connectionId - spreadsheetId - tabs SheetsStep: type: object additionalProperties: false properties: operation: type: string enum: - add - update tab: type: string ownership: type: string enum: - conversation - constrained selector: type: object additionalProperties: false properties: column: type: string equals: $ref: '#/components/schemas/SheetsBinding' from: type: string until: type: string required: - column expected: type: array items: type: object additionalProperties: false properties: column: $ref: '#/components/schemas/SheetsColumn' value: $ref: '#/components/schemas/SheetsValue' required: - column - value maxItems: 30 changes: type: array items: type: object additionalProperties: false properties: column: $ref: '#/components/schemas/SheetsColumn' value: $ref: '#/components/schemas/SheetsBinding' required: - column - value minItems: 1 maxItems: 30 required: - operation - tab - changes SheetsPermissionTarget: type: object additionalProperties: false properties: connectionId: type: string minLength: 1 maxLength: 160 spreadsheetId: type: string minLength: 1 maxLength: 160 sheetId: type: integer minimum: 0 headerRow: type: integer enum: - 1 required: - connectionId - spreadsheetId - sheetId SheetsPermissionColumn: type: object additionalProperties: false properties: id: type: string pattern: ^[a-z][a-z0-9_]*$ maxLength: 48 header: type: string minLength: 1 maxLength: 160 type: type: string enum: - text - email - phone - date - number - integer - boolean - single-select permissions: type: object additionalProperties: false properties: read: type: boolean update: type: boolean create: type: boolean required: - read - update - create requiredOnCreate: type: boolean valueSource: type: string enum: - input - sheet choices: type: array items: type: string maxLength: 80 maxItems: 30 uniqueItems: true required: - id - header - type - permissions - requiredOnCreate - valueSource SheetsBinding: oneOf: - type: object additionalProperties: false properties: input: type: string required: - input - type: object additionalProperties: false properties: value: $ref: '#/components/schemas/SheetsValue' required: - value - type: object additionalProperties: false properties: generated: type: boolean enum: - true required: - generated SheetsColumn: oneOf: - type: string - type: object additionalProperties: false properties: input: type: string choices: type: object additionalProperties: type: string required: - input - choices SheetsValue: oneOf: - type: string maxLength: 1000 - type: number - type: boolean responses: Error: description: Structured error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Visito M2M API key description: Server-side tenant-scoped credential created from Build > API Keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.