> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kylon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools API

> Search, authorize, inspect, execute, proxy, and upload through Kylon tools.

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 | The App auth token, App visibility, 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](/proxy/app-connections).

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

## List connections

```bash theme={null}
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

```bash theme={null}
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` | Optional result limit |
| `cursor` | Optional pagination cursor |

## Start toolkit authorization

```bash theme={null}
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",
    "redirect_url": "https://example.com/connected"
  }' | jq
```

The response includes a redirect URL. Open it in a browser so the user can authorize the toolkit.

## Get toolkit details

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

Returns toolkit metadata and available tools, including input schemas where available.

## Search tools within a toolkit

```bash theme={null}
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` | Optional result limit |
| `cursor` | Optional pagination cursor |
| `connection_id` | Optional connection filter |

## Execute a tool

```bash theme={null}
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": {
      "to": "person@example.com",
      "subject": "Hello from Kylon",
      "body": "This was sent through a connected tool."
    }
  }' | jq
```

Request body:

| Field | Required | Description |
| - | - | - |
| `tool` | Yes | Tool slug/name |
| `arguments` | No | Tool input object |
| `connection_id` | No | Specific connection to use |

## Proxy a native toolkit request

```bash theme={null}
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 connection to use |

## Upload media for tool use

```bash theme={null}
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 media to Kylon staging and returns a reference usable by supported tool calls.

## OpenAPI reference

The current generated API reference covers each Tools API endpoint:

* [List Connections](/api-reference/list-connections)
* [Search Toolkits](/api-reference/search-toolkits)
* [Get Auth URL](/api-reference/get-auth-url)
* [Get Toolkit Details](/api-reference/get-toolkit-details)
* [Search Toolkit Tools](/api-reference/search-toolkit-tools)
* [Execute Tool](/api-reference/execute-tool)
* [Proxy Request](/api-reference/proxy-request)
* [Upload File](/api-reference/upload-file)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.