> ## 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. # Create an action configuration > Requires `actions:write`. Family is required. HTTP uses the existing Tools configuration shape. Collection and Sheets use definition plus optional availability switches. Omitting both switches on collection creation creates a draft; specifying either publishes a validated snapshot (active defaults true). Sheets requires existing tenant connections and distinct production/test spreadsheets, validated with Google reads; onboarding/provisioning remains in the dashboard. A collection signingSecret can appear once when generated. 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 post /actions 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: post: tags: - Actions summary: Create an action configuration description: >- Requires `actions:write`. Family is required. HTTP uses the existing Tools configuration shape. Collection and Sheets use definition plus optional availability switches. Omitting both switches on collection creation creates a draft; specifying either publishes a validated snapshot (active defaults true). Sheets requires existing tenant connections and distinct production/test spreadsheets, validated with Google reads; onboarding/provisioning remains in the dashboard. A collection signingSecret can appear once when generated. 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: createAction parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateActionRequest' responses: '201': 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: CreateActionRequest: oneOf: - type: object additionalProperties: false properties: family: type: string enum: - http configuration: $ref: '#/components/schemas/ToolCreateRequest' required: - family - configuration - type: object additionalProperties: false properties: family: type: string enum: - collection configuration: $ref: '#/components/schemas/CollectionConfigurationInput' required: - family - configuration - type: object additionalProperties: false properties: family: type: string enum: - sheets configuration: $ref: '#/components/schemas/SheetsConfigurationInput' required: - family - configuration ActionConfigurationResponse: type: object additionalProperties: false properties: action: $ref: '#/components/schemas/ActionConfiguration' required: - action ToolCreateRequest: type: object required: - name - description - parameters - endpoint 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 description: JSON Schema for an object input. additionalProperties: true endpoint: $ref: '#/components/schemas/ToolEndpoint' auth: $ref: '#/components/schemas/ToolAuthInput' active: type: boolean default: true readOnly: type: boolean default: true allowInPlayground: type: boolean default: false 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 CollectionConfigurationInput: type: object additionalProperties: false properties: definition: $ref: '#/components/schemas/CollectionDefinition' webhook: $ref: '#/components/schemas/ActionWebhookInput' active: type: boolean playgroundOnly: type: boolean 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 not: anyOf: - required: - mode - active - required: - mode - playgroundOnly - required: - mode - allowInPlayground SheetsConfigurationInput: type: object additionalProperties: false properties: definition: $ref: '#/components/schemas/SheetsDefinition' active: type: boolean playgroundOnly: type: boolean 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 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 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 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 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.