Tools API

The Tools API is the primary proxy surface for connected integrations.

When to use this API

Agents can use connected integrations in three ways:

Surface	Best for	How access is checked
Built-in agent tools	Short interactive work in chat, such as listing connections, finding a tool, or making a small number of calls	The agent’s linked connections
`/proxy/tools/*`	Agent code, scripts, workflows, and automations that need programmatic connection access	The API key’s agent and that agent’s linked connections
App connection endpoints	Server-side code in generated Kylon Apps that needs the App’s source-agent connections	Current App viewer access, explicit per-App grants, and source-agent linked connections

For generated Apps, use the dedicated App connection endpoints instead of calling /proxy/tools/* from browser code. See App Connection API.

Connections are provider-mediated capabilities. Most hosted connections, including hosted integrations, should be called through connection tools such as /proxy/tools/execute. Use the native HTTP proxy endpoint only for supported native toolkits.

List connections

curl -s https://api.kylon.io/proxy/tools/connections \
  -H "x-api-key: pak_your_key_here" | jq

Returns the connections currently linked to the calling agent.

Search toolkits

curl -s "https://api.kylon.io/proxy/tools/search?keywords=gmail&limit=10" \
  -H "x-api-key: pak_your_key_here" | jq

Query parameters:

Parameter	Description
`keywords`	Required search string
`limit`	Positive integer; defaults to 50 and is capped at 100
`cursor`	Optional pagination cursor

Start toolkit authorization

curl -s -X POST https://api.kylon.io/proxy/tools/auth \
  -H "x-api-key: pak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "toolkit": "gmail",
    "connection_intent": {
      "kind": "one_off_access",
      "task_summary": "Read the messages needed for this task"
    }
  }' | jq

The response includes redirectUrl and agentInstruction. Present the link to the user and follow the returned instruction. Agent-started authorization uses Kylon’s connection callback; redirect_url does not override that callback. Optional scopes requests provider-specific scopes. connection_intent records why the connection is needed: one_off_access, realtime_delivery, scheduled_digest, context_discovery, or unknown. Include task_summary for context. A scheduled_digest intent also requires a non-empty cadence; omitting it returns 400 scheduled_digest_requires_cadence before authorization starts. Missing or unrecognized intent is treated as unknown. Inbound messaging endpoints such as LINE Official Account use the in-product connection setup form rather than this auth-link flow. They return messaging_setup_requires_ui here. See LINE setup.

Get toolkit details

curl -s "https://api.kylon.io/proxy/tools/toolkit/gmail?limit=20" \
  -H "x-api-key: pak_your_key_here" | jq

Returns toolkit metadata, tools, and nextCursor, with input schemas where available. Supply limit and cursor to page through tools; the limit defaults to 50 and is capped at 100. Both detail and search endpoints accept connection_id; it is required to inspect an MCP connection’s server-defined tools. An empty tool list can be intentional. Some native toolkits, including GitHub, expose authenticated HTTP or provider CLI access instead of structured tools. Read the returned note before treating an empty list as lost access. Toolkit search returns toolkits, nextCursor, and nextStep; pass the opaque nextCursor unchanged for the next page. Tool search returns toolkit, tools, and nextCursor. A first-page tool search can also include api_key_connections matching the requested service. These are credential connections for code access, not additional structured tools. Unknown toolkit errors can include suggested_connections, recoverable, and agent_instruction. Use the returned alternatives rather than guessing a slug.

Search tools within a toolkit

curl -s "https://api.kylon.io/proxy/tools/toolkit/gmail/search?q=draft&limit=10" \
  -H "x-api-key: pak_your_key_here" | jq

Query parameters:

Parameter	Description
`q`	Search query
`limit`	Positive integer; defaults to 50 and is capped at 100
`cursor`	Optional pagination cursor
`connection_id`	Optional connection filter

Execute a tool

Use the exact slug and inputParameters schema returned by discovery. The example below prepares a Gmail message under Kylon’s Draft approval policy; a tool named SEND does not imply that a message was delivered. Check the returned result and approval state.

curl -s -X POST https://api.kylon.io/proxy/tools/execute \
  -H "x-api-key: pak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "GMAIL_SEND_EMAIL",
    "arguments": {
      "recipient_email": "person@example.com",
      "subject": "Hello from Kylon",
      "body": "Please review this update before sending."
    }
  }' | jq

Request body:

Field	Required	Description
`tool`	Yes	Tool slug/name
`arguments`	No	Tool input object
`connection_id`	No	Specific linked connection; required for MCP tools and when connection selection is ambiguous

Read the execution envelope

Tool execution and native HTTP proxy calls wrap the provider result:

{
  "data": { "example": "provider result" },
  "error": null,
  "successful": true,
  "statusCode": 200,
  "connectionId": "conn_123"
}

Treat successful: false as a failed call. A connected service rate limit returns HTTP 429, error: "rate_limited", rateLimited: true, and retryable: true; it is not an empty result. Follow any returned hint when recovering. Raw /proxy/tools/execute calls do not post Draft or Email cards in chat. Presentable results include presentation.state: "not_presented" and visibleMessageReady: false. For interactive chat, use the built-in execute_connection_tool or kylon workspace connection tool execute so card presentation can be confirmed before telling the user it is visible.

Proxy a native toolkit request

curl -s -X POST https://api.kylon.io/proxy/tools/proxy \
  -H "x-api-key: pak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "toolkit": "github",
    "method": "GET",
    "url": "https://api.github.com/user/repos"
  }' | jq

This endpoint is for toolkit-native API calls where Kylon manages the connection credentials. Request body:

Field	Required	Description
`toolkit`	Yes	Toolkit slug
`method`	Yes	HTTP method
`url`	Yes	Target provider URL
`headers`	No	Additional request headers
`body`	No	Request body
`connection_id`	No	Specific linked connection; required for MCP tools and when connection selection is ambiguous

Upload media for tool use

curl -s -X POST https://api.kylon.io/proxy/tools/upload \
  -H "x-api-key: pak_your_key_here" \
  -F "file=@./image.png" | jq

Uploads a multipart file up to 500 MiB (524,288,000 bytes) and returns:

{
  "stagingKey": "workspace_id/_staging/upload_id/image.png",
  "filename": "image.png",
  "contentType": "image/png",
  "size": 12345
}

Pass stagingKey in the field required by the selected tool’s input schema. This is a workspace-scoped file reference, not a public download URL. The same upload route stages reference assets for OpenRouter video generation.

OpenAPI reference

The OpenAPI reference covers each Tools API endpoint:

Getting Started

Concepts

Agents

Tutorials

CLI

Connections

Proxy

When to use this API

List connections

Search toolkits

Start toolkit authorization

Get toolkit details

Search tools within a toolkit

Execute a tool

Read the execution envelope

Proxy a native toolkit request

Upload media for tool use

OpenAPI reference

​When to use this API

​List connections

​Search toolkits

​Start toolkit authorization

​Get toolkit details

​Search tools within a toolkit

​Execute a tool

​Read the execution envelope

​Proxy a native toolkit request

​Upload media for tool use

​OpenAPI reference

When to use this API

List connections

Search toolkits

Start toolkit authorization

Get toolkit details

Search tools within a toolkit

Execute a tool

Read the execution envelope

Proxy a native toolkit request

Upload media for tool use

OpenAPI reference