Edit author-editable metadata on a single tool (response_field_map, is_enabled, input_defaults — defaults + pinned)

Update author-editable tool metadata.

Three mutable fields:

response_field_map — the customer-owned field map ({"field_mappings": [...]}) selecting which response fields the agent receives. Narrows the agent-facing payload and drives the AOP compiler’s kind=llm → kind=action promotion (ENG-631). Omit the field to no-op; pass an explicit null to clear. The response shape (response_schema) is sync-owned and read-only over this API (D2), so it is rejected by the request schema’s extra="forbid".
is_enabled — turn the individual tool on/off (the PRD’s per-tool toggle). A disabled tool is excluded from resolution, so the agent can no longer call it. Omit to no-op.
input_defaults — operator input-arg config for input fields ({field_name: {"value": ..., "type": "default"|"pinned"}}, ENG-590). A default is a suggestion the agent may overwrite; a pinned value the caller cannot overwrite. Validated against the tool’s current input_schema: an unknown field or wrong-type value is rejected with a 422 listing each offending field. Omit to no-op; pass an explicit null to clear. Surfaced on every tool read (default_count / pinned_count / stale_input_fields / merged_input_preview); neither kind is injected into a tool call in this scope (runtime enforcement is a follow-on).

Only the fields the caller actually set are written. Verifies parent-connection org ownership before the tool update so a correctly-org’d tool id under a foreign-org connection still 404s.

PATCH

integrations

connections

{connection_id}

tools

{tool_id}

Edit author-editable metadata on a single tool (response_field_map, is_enabled, input_defaults — defaults + pinned)

curl --request PATCH \
  --url https://api-sandbox.featherhq.com/v1/integrations/connections/{connection_id}/tools/{tool_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "response_field_map": {},
  "is_enabled": true,
  "input_defaults": {}
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "nickname_slug": "<string>",
  "tool_path": "<string>",
  "slug": "<string>",
  "display_name": "<string>",
  "description": "<string>",
  "input_schema": {},
  "is_enabled": true,
  "last_seen_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "stale_field_paths": [
    "<string>"
  ],
  "default_count": 123,
  "pinned_count": 123,
  "stale_input_fields": [
    "<string>"
  ],
  "merged_input_preview": {},
  "response_schema": {},
  "response_field_map": {},
  "input_defaults": {}
}

Authorizations

x-api-key

string

header

required

Path Parameters

connection_id

string<uuid>

required

tool_id

string<uuid>

required

Body

application/json

Author-editable fields on a single IntegrationConnectionTool.

Three mutable fields: response_field_map (the customer-owned field map {"field_mappings": [...]} that narrows the agent-facing response and drives the AOP compiler's kind=llm → kind=action promotion), is_enabled (turn the individual tool on/off for the agent), and input_defaults (operator input-arg config, {field_name: {"value": ..., "type": "default"|"pinned"}} — ENG-590; a default may be overwritten by the agent, a pinned value cannot). input_defaults is validated at the service layer against the row's current input_schema (it needs the row, which a Pydantic validator can't see), so a wrong-type value or unknown field is rejected there with a 422. The response shape (response_schema) is sync-owned and read-only over the API (ENG-631 D2), so it is deliberately NOT accepted here — extra="forbid" rejects it with a 422.

Pydantic's model_fields_set is used at the service layer to distinguish "omit this field" (no-op) from "explicit None" (clear the field).

response_field_map

Response Field Map · object

is_enabled

boolean | null

input_defaults

Input Defaults · object

Show child attributes

Response

Successful Response

string<uuid>

required

connection_id

string<uuid>

required

organization_id

string<uuid>

required

integration_key

enum<string>

required

Stable identifier for each supported integration.

The string value must match the vendor's per-provider identifier (for Nango: provider_config_key). Persisted on integration_connections.integration_key and integration_connection_tools.integration_key.

Adding a new integration: append a member here, add an IntegrationSpec to INTEGRATIONS, register the provider in the vendor cloud via src/integrations/bootstrap.py (Step 3).

Available options:

slack,

custom_mcp,

notion,

google_drive,

calcom,

twilio,

email

nickname_slug

string

required

tool_path

string

required

slug

string

required

display_name

string

required

description

string | null

required

input_schema

Input Schema · object

required

is_enabled

boolean

required

last_seen_at

string<date-time>

required

created_at

string<date-time>

required

updated_at

string<date-time>

required

stale_field_paths

string[]

required

read-only

Saved field-map paths no longer present in the shape (ENG-631 D4).

default_count

integer

required

read-only

How many input fields carry an operator default (ENG-590 / PRD 7.7).

pinned_count

integer

required

read-only

How many input fields are operator-pinned (ENG-590).

stale_input_fields

string[]

required

read-only

Configured input fields removed/renamed/retyped by a re-sync (PRD 7.6).

merged_input_preview

Merged Input Preview · object

required

read-only

input_schema with each operator value injected (PRD 7.8).

response_schema

Response Schema · object

response_field_map

Response Field Map · object

input_defaults

Input Defaults · object

Show child attributes

Dashboard test surface: invoke a tool by slug (VENDOR_API)Fire a real ``VENDOR_API`` invocation from the Integrations dashboard. Verifies the parent connection is owned by the caller's org (404 otherwise), then dispatches ``invoke_tool_by_slug`` so the operator can confirm the backend action path end-to-end. Emits an ``integration_tool_call`` Tinybird row with ``mode=vendor_api`` and ``reason="ui_slack_test_send"``. An unresolved/disabled slug surfaces as ``ToolUnavailableError`` (400). The backend ``result`` stays **raw** (the backend path is never narrowed). For the field-picker UI we also compute ``narrowed`` here (ENG-631) — what the agent would actually receive — using the shared :func:`narrow_result`. Effective field map: ``request.response_field_map`` → the saved tool's ``response_field_map`` → none (``narrowed=None``).

⌘I

Edit author-editable metadata on a single tool (response_field_map, is_enabled, input_defaults — defaults + pinned)

curl --request PATCH \
  --url https://api-sandbox.featherhq.com/v1/integrations/connections/{connection_id}/tools/{tool_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "response_field_map": {},
  "is_enabled": true,
  "input_defaults": {}
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "nickname_slug": "<string>",
  "tool_path": "<string>",
  "slug": "<string>",
  "display_name": "<string>",
  "description": "<string>",
  "input_schema": {},
  "is_enabled": true,
  "last_seen_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "stale_field_paths": [
    "<string>"
  ],
  "default_count": 123,
  "pinned_count": 123,
  "stale_input_fields": [
    "<string>"
  ],
  "merged_input_preview": {},
  "response_schema": {},
  "response_field_map": {},
  "input_defaults": {}
}