Agent API tools

8 operations. Call each with POST https://app.chirply.io/api/v1/actions/<name> and a bearer token; the response is { "data": { "action", "summary", "result" } }. A read badge means the operation changes nothing; write requires the credential’s write scope.

Save assignments

agent_api_tools.assignwriteadmin only

Replace the complete set of agents allowed to use a reusable API tool. Assigned agents receive only its active published version.

Parameters

Field	Type	Required	Description
tool_id	string (uuid)	required	Tool to assign.
agent_ids	array of (string (uuid))	required	Complete replacement list of AI agent ids; pass [] to remove it from every agent.

Example

curl -X POST https://app.chirply.io/api/v1/actions/agent_api_tools.assign \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "agent_ids": [
      "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
    ]
  }'

Test with your API key

Over MCP the same operation is the tool agent_api_tools_assign at https://app.chirply.io/api/mcp, same bearer token, same input.

Add tool draft

agent_api_tools.createwriteadmin only

Create a reusable Agent API Tool draft. It cannot run on calls until it is tested, published, and assigned to agents.

Parameters

Field	Type	Required	Description
connection_id	string (uuid)	required	Reusable API connection this operation uses.
name	string	required	Button and catalog title.
key	string	required	Permanent snake_case machine key.
description	string	required	When and why a live agent should call it.
method	"GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE"	optional	HTTP method. Default: "POST"
path	string	optional	Path resolved against the connection base URL. Default: "/"
input_schema	map of string → object	required	Self-contained object JSON Schema; every field should have a description.
request_template	any (or null)	optional	Optional JSON request template using {{args.field}}, {{contact_id}}, and {{session_id}}.
response_instructions	string	required	How the agent should interpret and explain the returned data.
timeout_ms	integer	optional	Live-call timeout in milliseconds. Default: 5000
risk	"read" \| "write"	optional	Whether the operation only reads or changes the external system. Default: "read"

Example

curl -X POST https://app.chirply.io/api/v1/actions/agent_api_tools.create \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "name": "Example",
    "key": "example",
    "description": "example",
    "input_schema": {},
    "response_instructions": "example"
  }'

Test with your API key

Over MCP the same operation is the tool agent_api_tools_create at https://app.chirply.io/api/mcp, same bearer token, same input.

Add connection

agent_api_tools.create_connectionwriteadmin only

Create a reusable account API connection. Authentication secrets are AES-256-GCM encrypted and can never be read back. This does not call the external API.

Parameters

Field	Type	Required	Description
name	string	required	Human-readable connection name.
base_url	string (uri)	required	Public HTTPS base URL used by tools on this connection.
auth_type	"none" \| "bearer" \| "basic" \| "api_key"	required	Authentication scheme.
secret	string	optional	Bearer token, Basic password, or API-key value; encrypted immediately and never returned.
username	string	optional	Username when auth_type is basic.
api_key_header	string	optional	Header name when auth_type is api_key. Default: "X-API-Key"
default_headers	map of string → string	optional	Non-secret headers added to every request. Default: {}

Example

curl -X POST https://app.chirply.io/api/v1/actions/agent_api_tools.create_connection \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example",
    "base_url": "https://example.com",
    "auth_type": "none"
  }'

Test with your API key

Over MCP the same operation is the tool agent_api_tools_create_connection at https://app.chirply.io/api/mcp, same bearer token, same input.

List connected API operations

agent_api_tools.listreadadmin only

List reusable API connections, draft/published agent tools, agent assignments, published versions, and recent redacted execution status for this account. Never returns stored credentials or full external responses.

Parameters

Field	Type	Required	Description
include_runs	boolean	optional	Include the 30 most recent redacted execution events. Default: true
include_versions	boolean	optional	Include every published immutable version of each tool — its version number, the exact configuration snapshot it pinned, and when it was published. This is what the page's “Published configuration is pinned to version N” line reads. Off by default because a long-lived tool accumulates many versions. Default: false

Example

curl -X POST https://app.chirply.io/api/v1/actions/agent_api_tools.list \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "include_runs": true,
    "include_versions": false
  }'

Test with your API key

Over MCP the same operation is the tool agent_api_tools_list at https://app.chirply.io/api/mcp, same bearer token, same input.

Publish

agent_api_tools.publishwriteconfirmadmin only

Publish the current draft as a new immutable version. Every assigned live voice agent immediately receives this version; write tools may change a real external system without another human approval during a call.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

Field	Type	Required	Description
id	string (uuid)	required	Tool id to publish.

Example

curl -X POST https://app.chirply.io/api/v1/actions/agent_api_tools.publish \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'

Test with your API key

Over MCP the same operation is the tool agent_api_tools_publish at https://app.chirply.io/api/mcp, same bearer token, same input.

Run test

agent_api_tools.testwriteconfirmadmin only

Immediately call an external authenticated API using this tool's current draft configuration and supplied test input. A write-classified tool can change the external system for real; the response is bounded and credentials are never returned.

Parameters

Field	Type	Required	Description
tool_id	string (uuid)	required	Tool draft to test.
input	map of string → object	optional	JSON arguments matching the tool input schema. Default: {}

Example

curl -X POST https://app.chirply.io/api/v1/actions/agent_api_tools.test \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'

Test with your API key

Over MCP the same operation is the tool agent_api_tools_test at https://app.chirply.io/api/mcp, same bearer token, same input.

Edit tool draft

agent_api_tools.updatewriteadmin only

Update the editable draft of a reusable Agent API Tool. Calls keep using the immutable active version until Publish is run, so incomplete edits cannot break assigned agents.

Parameters

Field	Type	Required	Description
id	string (uuid)	required	Tool id to edit.
connection_id	string (uuid)	optional	Replacement API connection.
name	string	optional	New catalog title.
key	string	optional	New snake_case machine key; avoid changing a key integrations already reference.
description	string	optional	New instructions describing when and why the agent calls it.
method	"GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE"	optional	Replacement HTTP method.
path	string	optional	Replacement endpoint path.
input_schema	map of string → object	optional	Replacement self-contained object JSON Schema.
request_template	any (or null)	optional	Replacement request JSON template; null sends arguments directly.
response_instructions	string	optional	Replacement instructions for interpreting the response.
timeout_ms	integer	optional	Replacement live-call timeout.
risk	"read" \| "write"	optional	Whether the tool reads or changes the external system.

Example

curl -X POST https://app.chirply.io/api/v1/actions/agent_api_tools.update \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'

Test with your API key

Over MCP the same operation is the tool agent_api_tools_update at https://app.chirply.io/api/mcp, same bearer token, same input.

Edit connection

agent_api_tools.update_connectionwriteadmin only

Update a reusable API connection. Omit secret to keep the encrypted credential already stored; supplying one replaces it for every tool using this connection.

Parameters

Field	Type	Required	Description
id	string (uuid)	required	Connection id.
name	string	optional	New connection name.
base_url	string (uri)	optional	New public HTTPS base URL.
auth_type	"none" \| "bearer" \| "basic" \| "api_key"	optional	New authentication scheme.
secret	string	optional	Replacement credential, encrypted immediately.
username	string	optional	Basic-auth username.
api_key_header	string	optional	API-key header name.
default_headers	map of string → string	optional	Replacement non-secret default headers.

Example

curl -X POST https://app.chirply.io/api/v1/actions/agent_api_tools.update_connection \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'

Test with your API key

Over MCP the same operation is the tool agent_api_tools_update_connection at https://app.chirply.io/api/mcp, same bearer token, same input.