> ## Documentation Index > Fetch the complete documentation index at: https://docs.famulor.io/llms.txt > Use this file to discover all available pages before exploring further. # Update an app action tool > Change an app action tool. Only the settings you send change; `fields` are matched by `path` (or by `key` when `path` is missing) and apply onto the tool's current fields. To delete the tool, remove it from its assistants, then call `DELETE /tools/{id}`. Requires an owner or admin credential and a plan with Automations. Requires both `assistants:write` and `automations:write`. ## OpenAPI ````yaml /api-reference/openapi.json patch /tools/app-actions/{toolId} openapi: 3.1.0 info: title: Famulor API version: 1.0.0 description: >- REST API for Famulor. Authenticate with an API key (`fam_...`, created under **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`) as a Bearer token. Every response uses a consistent envelope: `{ "data": ... , "meta": { ... } }` on success and `{ "error": { "code", "message" } }` on failure. List endpoints paginate with `?limit=` (default 50, max 200) and `?offset=`; `meta.pagination.total` carries the total match count. REST operations require API Access through the workspace plan or a recurring add-on. Without it, regular operations return `403 api_access_required`. The invoice-payment and billing-portal operations remain available with a valid `billing:write` credential after a failed plan payment so an authorized owner, admin, or billing member can recover billing. The same customer-facing capabilities are available as MCP tools at `https://app.famulor.io/mcp` (Model Context Protocol, streamable HTTP) using the same credentials, scopes, and workspace access. MCP availability is controlled separately by Connect AI / MCP, not by API Access. servers: - url: https://app.famulor.io/api/v1 description: Hosted platform. - url: https://{domain}/api/v1 description: White-label tenant domain — same paths, tenant branding. variables: domain: default: app.famulor.io description: Your white-label tenant domain. security: - bearerAuth: [] tags: - name: Account description: Self-inspection of the calling credential. - name: Migrations description: Preview and import data from supported legacy platforms. - name: Assistants description: Create and manage voice assistants. - name: Tools description: >- Reusable tools (HTTP APIs, external MCP servers and actions of connected apps) assistants can call mid-conversation. - name: Voices description: Browse the text-to-speech voice library. - name: Calls description: Start outbound calls and read call history, transcripts and recordings. - name: History description: Unified conversation history across calls, messaging and assistant emails. - name: Campaigns description: Outbound calling campaigns with a compliant power dialer. - name: Leads description: Manage Audience contacts across campaigns, channels and Call QA metrics. - name: Segments description: >- Saved, dynamic lead filters — reusable audience definitions used for Audience search and campaign lead assignment. - name: Suppression description: Cross-channel marketing opt-outs and active workspace suppression records. - name: Callbacks description: >- Scheduled callbacks booked by the Schedule callback tool across voice, chat, and email. - name: Phone Numbers description: Marketplace numbers and customer-provided numbers. - name: Famulor Loop description: >- Personal business-phone access, directory, presence, devices, and Loop call recents. - name: SIP Trunks description: Bring your own SIP provider and numbers. - name: Carrier Connections description: Connect a supported carrier account and import its existing phone numbers. - name: Knowledge Bases description: RAG knowledge bases and documents for assistants. - name: Settings description: Workspace-level settings such as caller-memory defaults. - name: Billing description: Balance and transaction ledger of the API key's workspace. - name: Automations description: >- Native workspace automations — list, create, update, trigger. Requires Automations in the workspace plan. - name: Milian Missions description: Recurring jobs that Milian runs unattended on schedule. - name: Integrations description: >- Calendar integrations (Cal.com, Calendly, Acuity Scheduling, Google Calendar, Outlook, native booking engine). Assign them to assistants to provide availability and booking tools, plus provider-supported appointment lookup, cancellation, and rescheduling. - name: Bookings description: >- Native booking engine — event types with weekly availability, public booking pages at /book/{workspace}/{slug}, and the bookings they produce. - name: Dashboards description: >- Custom analytics dashboards, reusable widgets, and tenant-scoped performance analytics. Requires Custom dashboards in the workspace plan. - name: Catalog description: >- Read-only platform catalogs — available models, supported assistant languages, and prompt templates. - name: Simulations description: Assistant simulation tests (plan-gated). - name: Versions description: Assistant configuration version history. - name: Caller IDs description: Outbound caller ID verification. - name: Widgets description: Web widget connectors. - name: Messaging description: >- Telegram, Slack, and Messenger text bots linked to assistants (Chat SDK). Includes conversation delay, inactivity end, and conversation-ended webhooks. - name: QA description: Cohort AI Quality Assurance runs over call transcripts. - name: White Label description: >- Manage white-label customer accounts, defaults, credit transfers and customer plan offers. Each endpoint documents its required scope and workspace eligibility. - name: API Keys description: >- Self-service API keys for the calling workspace or a same-brand workspace where the credential's user is owner/admin. A key can only mint further keys with a scope subset of its own. - name: Workspaces description: >- List visible workspaces, create an additional workspace for the key owner, and mint a dedicated credential for a selected owner/admin workspace. - name: SMS description: Outbound SMS from workspace phone numbers. - name: Milian description: >- Ask Milian, the AI co-worker in your workspace, and start voice sessions with it. - name: Translation description: >- Live translation sessions that interpret a conversation between two languages. - name: Shopify description: Native Shopify app store connections, assistant tools and activity. - name: Avatars description: Private custom avatars and widget avatar selection. - name: Webhook Subscriptions description: >- Signed workspace event subscriptions, independent of existing destinations. paths: /tools/app-actions/{toolId}: patch: tags: - Tools summary: Update an app action tool description: >- Change an app action tool. Only the settings you send change; `fields` are matched by `path` (or by `key` when `path` is missing) and apply onto the tool's current fields. To delete the tool, remove it from its assistants, then call `DELETE /tools/{id}`. Requires an owner or admin credential and a plan with Automations. Requires both `assistants:write` and `automations:write`. operationId: updateAppActionTool parameters: - name: toolId in: path required: true schema: type: string format: uuid description: ID of the app action tool (the `id` in `GET /tools`). requestBody: required: true content: application/json: schema: type: object additionalProperties: false minProperties: 1 properties: connection_id: type: string format: uuid description: Another connection of the same app. name: type: string pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$ description: New tool name the assistant sees. use_when: type: string minLength: 10 maxLength: 1000 description: >- When the assistant should use the tool, for example `When the caller asks for a callback.` description_override: type: - string - 'null' maxLength: 900 description: >- Replaces the generated tool description the assistant sees. Null uses the generated one. fields: type: array maxItems: 300 items: $ref: '#/components/schemas/AppActionFieldSetting' description: >- Field settings, matched by `path` (or by `key` when `path` is missing). Fields you leave out keep their current setting. Send the fields as they were returned or only the ones you change. confirmation: type: string enum: - ask_first - none description: >- `ask_first`: before an action changes data, the assistant reads the values back and calls the tool again to run it. In messaging and email the second call runs only after a new customer message. On calls and in web chat it runs when it comes at least 4 seconds after the read-back, whether or not the customer answered. `ask_first` is not a consent record. `none`: the action runs at once. Omit it to keep the current setting; actions that only read never ask. result_config: type: - object - 'null' additionalProperties: false description: >- How much of the app's result the assistant reads. Null uses the defaults. properties: mode: type: string enum: - auto - selected description: >- `auto` keeps a shortened version of the whole result. `selected` keeps only `paths`. paths: type: array maxItems: 20 items: type: string minLength: 1 maxLength: 200 description: >- JSON pointers to keep in mode `selected`, for example `/id`. max_chars: type: integer minimum: 200 maximum: 3500 description: >- Longest result the assistant reads, from 200 to 3500 characters (default 2000). is_active: type: boolean description: Whether assistants can use the tool. responses: '200': description: The updated app action tool. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/AppActionTool' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/RequestProtectionUnavailable' components: schemas: AppActionFieldSetting: type: object description: >- Setting for one field, matched by `path` (or by `key` when `path` is missing). Only the properties you send change. A `path` inside a list field adds a column, for example `/values/0/1`, or a cell of a list of objects, for example `/attendees/0/email`; listing any column of a list field replaces all of its columns. additionalProperties: false properties: path: type: string maxLength: 1000 description: Field path as returned with the action. key: type: string maxLength: 200 description: >- Field key; identifies a field of the action when `path` is missing. Columns of a list field need their `path`. mode: $ref: '#/components/schemas/AppActionFieldMode' description: Must be one of the field's `allowed_modes`. value: description: >- Value for mode `fixed`. Text may contain `{{param}}` placeholders for AI fields or `{{variable}}` placeholders such as `{{caller_number}}`. variable: type: - string - 'null' maxLength: 100 description: >- Conversation variable for mode `variable`, for example `caller_number`. param: type: - string - 'null' maxLength: 64 description: >- Parameter name the assistant sees for mode `ai` or `variable`; test `values` and `{{param}}` placeholders use it. Null generates one. description: type: - string - 'null' maxLength: 600 description: >- Replaces the generated field description the assistant sees. Null restores it. label: type: string maxLength: 200 description: Column name; only used for columns of a list field. required: type: boolean description: >- Whether a column needs a value; only used for columns of a list field. type: readOnly: true description: Read-only; ignored on input. items: readOnly: true description: Read-only; ignored on input. columns: readOnly: true description: Read-only; ignored on input. cell_type: readOnly: true description: Read-only; ignored on input. enum: readOnly: true description: Read-only; ignored on input. format: readOnly: true description: Read-only; ignored on input. allowed_modes: readOnly: true description: Read-only; ignored on input. provider_description: readOnly: true description: Read-only; ignored on input. example: readOnly: true description: Read-only; ignored on input. default_value: readOnly: true description: Read-only; ignored on input. AppActionTool: type: object description: An app action tool with its settings. required: - tool_id - binding_id - name - is_active - app - app_name - action - action_name - connection_id - risk - confirmation - status - update_available - version - fields - model - result_config - revision properties: tool_id: type: string format: uuid description: Tool ID, the same as `id` in `GET /tools`. binding_id: type: string format: uuid description: ID of the tool's app action settings. name: type: string description: Tool name the assistant sees. is_active: type: boolean app: type: string description: App ID. app_name: type: string action: type: string description: Action ID. action_name: type: string connection_id: type: string format: uuid risk: $ref: '#/components/schemas/AppActionRisk' confirmation: type: string enum: - ask_first - none status: type: string enum: - ok - needs_attention update_available: type: boolean version: type: string description: Version of the action the tool uses. fields: type: array items: $ref: '#/components/schemas/AppActionField' model: type: object required: - use_when description: What the assistant reads about the tool. properties: use_when: type: string description_override: type: - string - 'null' result_config: $ref: '#/components/schemas/AppActionResultConfig' revision: type: integer minimum: 1 description: Increases with every change. AppActionFieldMode: type: string enum: - ai - fixed - variable - 'off' description: >- How a field gets its value: `ai` = the assistant fills it during the conversation, `fixed` = always `value`, `variable` = a conversation variable such as the caller's number, `off` = not sent. AppActionRisk: type: string enum: - read - write - destructive description: >- What the action does in the app: `read` only reads, `write` changes data, `destructive` deletes data. Actions that delete data cannot be used as tools yet. AppActionField: type: object description: >- One input field of an action. Only `mode`, `value`, `variable`, `param` and `description` can be changed; the other properties come from the action. required: - key - path - label - type - required - allowed_modes - mode properties: key: type: string description: >- Stable field key: the name of the field in the action's input, for example `startTime`. Identifies the field (with `path`) in field settings. Test `values` and `{{…}}` placeholders use `param` instead. path: type: string description: >- JSON pointer of the field in the action's input, for example `/values`. label: type: string description: Readable field name. type: type: string enum: - string - number - integer - boolean - array - object items: type: - string - 'null' enum: - string - number - integer - boolean - null description: Type of the list entries for `array` fields. columns: type: - array - 'null' readOnly: true items: type: object required: - key - label - type - required properties: key: type: string description: Property name inside one list entry, for example `email`. label: type: string type: type: string enum: - string - number - integer - boolean required: type: boolean description: Every row needs a value for this column. enum: type: - array - 'null' items: type: string description: Allowed values of a cell in this column. format: type: - string - 'null' enum: - date - date-time - time - email - phone - uri - null description: Expected format of a cell in this column. description: >- Lists of objects only: the properties of one entry as fixed, named columns, in the action's order. A cell has the path `//`, for example `/attendees/0/email`. An empty list (`[]`) means there is no column builder, for example for entries of mixed or unknown type or objects without simple properties: send the whole list as the field's `value` in mode `fixed`. Absent for lists of simple values and for lists of lists; lists of lists use numeric columns such as `/values/0/1` (see `cell_type`). cell_type: type: - string - 'null' readOnly: true enum: - string - number - integer - boolean - null description: >- Lists of lists only: the type of one cell, for example `number` for `/values/0/1`. Cells of mixed or unknown type are `string`. A `string` cell allows the modes `ai`, `fixed` and `variable`; `number`, `integer` and `boolean` cells allow `ai` and `fixed`. enum: type: - array - 'null' items: type: string description: Allowed values. format: type: - string - 'null' enum: - date - date-time - time - email - phone - uri - null description: Expected format of the value. required: type: boolean description: Whether the action needs a value. allowed_modes: type: array items: $ref: '#/components/schemas/AppActionFieldMode' description: Modes this field supports. mode: $ref: '#/components/schemas/AppActionFieldMode' param: type: - string - 'null' description: >- Parameter name the assistant sees for fields in mode `ai` or `variable`, usually `key` in snake_case (`startTime` → `start_time`); a column of a list field uses its column name. Test `values` and `{{param}}` placeholders in fixed text use it. provider_description: type: - string - 'null' description: The app's own description of the field. description: type: - string - 'null' description: >- Your description of the field for the assistant. Null uses the generated one. value: description: >- Value used in mode `fixed`. Text may contain `{{param}}` placeholders for AI fields or `{{variable}}` placeholders such as `{{caller_number}}`. variable: type: - string - 'null' description: >- Conversation variable used in mode `variable`, for example `caller_number`. example: type: - string - 'null' description: Example value. default_value: description: Default value of the action, if any. AppActionResultConfig: type: object description: How much of the app's result the assistant reads. required: - mode - max_chars properties: mode: type: string enum: - auto - selected description: >- `auto` keeps a shortened version of the whole result. `selected` keeps only `paths`. paths: type: array items: type: string description: JSON pointers kept in mode `selected`. max_chars: type: integer minimum: 200 maximum: 3500 description: Longest result the assistant reads, in characters. ErrorEnvelope: type: object description: Error envelope returned by every /api/v1 endpoint on failure. required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - unauthorized - forbidden - api_access_required - not_found - invalid_request - rate_limited - conflict - telephony_configuration_error - telephony_unavailable - destination_forbidden - internal_error - service_unavailable - verification_address_required - bundle_address_missing description: >- Stable, machine-readable error code. `service_unavailable` is returned by POST /bookings and GET /booking-event-types/{id}/slots specifically when the availability engine could not be reached (see AvailabilityOrProtectionUnavailable). `verification_address_required` and `bundle_address_missing` are returned by POST /phone-numbers when the verification behind the number has no address (see the operation description). message: type: string description: Human-readable description of the error. reason: type: string description: >- Optional, more specific and stable reason for this error, for example `plan_required`, `read_only_role` or `missing_scope`. Branch on `code` first: `reason` is only present on some errors, and new values may be added. hint: type: string description: >- Optional recovery advice that is safe to show to the end user, for example which settings page to open. responses: BadRequest: description: Invalid request body or parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: invalid_request message: '"to_number" is required (E.164 format, e.g. +4930123456).' Unauthorized: description: Missing, invalid, expired or revoked API key / access token. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: unauthorized message: Invalid API key. Forbidden: description: >- The credential lacks the required scope or role, or the workspace does not have the required capability. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: scopeDenied: summary: Required scope is missing value: error: code: forbidden message: >- This API key is missing the required scope "assistants:write". apiAccessRequired: summary: API Access is not available value: error: code: api_access_required message: >- API Access is not available for this workspace. Review Settings → Plan. NotFound: description: Resource not found (or it belongs to another workspace). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: not_found message: Assistant not found Conflict: description: The resource is in a conflicting state. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: conflict message: Campaign is not running. RateLimited: description: Too many requests. Retry after the indicated delay. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: rate_limited message: Too many requests. Retry after the indicated delay. RequestProtectionUnavailable: description: Request protection is temporarily unavailable. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: internal_error message: Request protection is temporarily unavailable. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- API key (`fam_...`, created under **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`). REST operations also require API Access for the credential's workspace. Keys can be restricted to scopes such as `assistants:read`, `calls:write`, `campaigns:write`, `automations:read`, `dashboards:read`, `dashboards:write`, `leads:write`, `segments:write`, `loop:read`, `loop:write`, `phone_numbers:write`, `sip_trunks:write`, `knowledge:write`, `voices:read`, `billing:read`, `billing:write`, `settings:write`, `platform:read`, `platform:write`; a `*:write` scope implies the matching `*:read`. Automation and dashboard endpoints also accept the legacy `calls:*` scope. Keys without scope restrictions have full access within the workspace's available capabilities. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.