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

# Tools

> Browse, create, execute tools and list toolkits for agents and workflows

## What are tools?

**Tools** are actions that your workflows and agents can run: send a Slack message, create a Google Calendar event, search the web, or run your own code. Instead of wiring each integration yourself, you pick from Flowra’s **20,000+ tools** (grouped into **toolkits** like Slack, Gmail, GitHub) or build **custom tools** from JavaScript or Python scripts. When a workflow runs, the AI can decide to call a tool (e.g. “send this to Slack”) and Flowra runs it with the right credentials and returns the result.

So: tools are the “hands” of your agent — they let it do real things in the world (APIs, databases, your code) instead of only generating text.

### Example use cases

* **Pre-built tools** — Search for “send message” or filter by toolkit (e.g. `slack`). Attach the tools you need to a workflow; when the agent runs, it can send messages, create events, or query data.
* **Custom tools** — You have internal APIs or business logic. Write a small script (e.g. “call our CRM API with these params”), test it in the sandbox, then create a tool. The agent can now call that logic like any other tool.
* **Execute from your app** — Call `POST /tools/execute/{toolSlug}` with inputs and (if needed) a connected account ID. Useful for running a tool on behalf of a user from your backend.

### How it works

1. **Discover** — List and search tools by keyword, toolkit, or tags. Get a tool’s slug and input schema.
2. **Create (optional)** — For custom tools: test a script with `/sandbox/ephemeral`, then create the tool with `/tools`. It gets a slug and appears in your project.
3. **Use in workflows** — Attach tools to a workflow; the agent chooses when to call them. Or **execute** a tool directly via the API with the right auth (API key + optional connected account).

Tools that need OAuth (e.g. Slack, Google) require an [auth config](/guides/auth-configs) and often a [connected account](/guides/connected-accounts) per user. The API reference has the full request/response schemas.

***

## API endpoints

### Browse and search tools

**GET** `/api/v1/tools` returns a paginated list of tools. Use query parameters to search and filter.

### Search and filter parameters

| Parameter           | Type    | Description                                                                                                               |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `q`                 | string  | **Search keyword** — Filters by name, description, or other searchable fields (e.g. `send message`, `calendar`, `email`). |
| `toolkitSlug`       | string  | Filter by toolkit slug (e.g. `slack`, `gmail`, `github`).                                                                 |
| `toolSlugs`         | string  | Comma-separated tool slugs. When set, returns only these tools (e.g. `slack_send_message,slack_get_channels`).            |
| `provider`          | string  | Filter by provider: `COMPOSIO` or `LOCAL`.                                                                                |
| `tags`              | string  | Filter by tags (e.g. `productivity`, `communication`).                                                                    |
| `scopes`            | string  | Filter by required scopes.                                                                                                |
| `authConfigIds`     | string  | Comma-separated auth config IDs — return only tools that work with these configs.                                         |
| `important`         | string  | Set to `true` to return only important/featured tools.                                                                    |
| `includeDeprecated` | boolean | Include deprecated tools (default `false`).                                                                               |
| `toolkitVersions`   | string  | Toolkit version; use `latest` or bracket notation for specific versions.                                                  |

### Pagination and sorting

| Parameter           | Type   | Description                                                              |
| ------------------- | ------ | ------------------------------------------------------------------------ |
| `page`              | number | Page number (1-based). Default: `1`.                                     |
| `limit`             | number | Items per page (1–100). Default: `20`.                                   |
| `offset`            | number | Number of items to skip.                                                 |
| `cursor`            | string | Cursor for cursor-based pagination.                                      |
| `sortBy`            | string | Field to sort by (e.g. `createdAt`, `name`).                             |
| `sortOrder`         | string | `ASC` or `DESC`. Default: `DESC`.                                        |
| `fields`            | string | Comma-separated fields to include in the response.                       |
| `selectedToolSlugs` | string | Comma-separated tool slugs; can put certain tools first in the response. |

### Example: search by keyword

```bash theme={null}
curl -X GET "https://flowra.dev/api/v1/tools?q=send%20message&limit=20" \
  -H "x-api-key: YOUR_API_KEY"
```

### Example: filter by toolkit

```bash theme={null}
curl -X GET "https://flowra.dev/api/v1/tools?toolkitSlug=slack&limit=50" \
  -H "x-api-key: YOUR_API_KEY"
```

### Example: get specific tools by slug

```bash theme={null}
curl -X GET "https://flowra.dev/api/v1/tools?toolSlugs=slack_send_message,slack_get_channels,gmail_send_email" \
  -H "x-api-key: YOUR_API_KEY"
```

### Example: filter by tags

```bash theme={null}
curl -X GET "https://flowra.dev/api/v1/tools?tags=productivity&limit=20" \
  -H "x-api-key: YOUR_API_KEY"
```

For a visual catalog with search and filters, use the [Flowra Dashboard](https://flowra.dev).

### Create custom tools (from code)

You can build **custom tools** from code so workflows and agents can run your logic (API calls, calculations, custom integrations).

1. **Test your script** — Use **POST** `/api/v1/sandbox/ephemeral` to run a script in a secure one-shot sandbox with optional sample state. You get a structured result (`status`, `result`, `error`) without saving anything. Request body: **SandboxEphemeralDto** (see [API reference](/api-reference)). For longer-lived VMs, use **POST** `/api/v1/sandbox/sessions` and **POST** `/api/v1/sandbox/sessions/{id}/execute`.
2. **Create the tool** — When the script behaves as you want, use **POST** `/api/v1/tools` to create a new tool. Request body: **CreateToolDto** (name, description, input schema, and the script or configuration). The new tool gets a slug and appears in the tools list.
3. **Update or delete** — **PATCH** `/api/v1/tools/byId/{id}` updates a tool; **DELETE** `/api/v1/tools/byId/{id}` removes it. **PATCH** `/api/v1/tools/byId/{id}/status` enables or disables a tool without deleting it.

Custom tools are provider **LOCAL** and appear when you filter by `provider=LOCAL` or in your project's toolkits.

### Get tool by ID

**GET** `/api/v1/tools/byId/{id}` returns one tool. Use the tool's ID (or slug). Optional query params: `version`, `toolkitVersions`.

### Execute a tool

**POST** `/api/v1/tools/execute/{toolSlug}` runs a tool with the given arguments and auth.

Request body: **ExecuteToolDto** (see [API reference](/api-reference) for schema). Include the tool slug in the path and the required inputs in the body.

### Tool execution logs

**GET** `/api/v1/tools/execution-logs` returns paginated execution logs for your project. Filter with `toolSlug`, `page`, `limit`, `sortBy`, `sortOrder`, and similar query params (see [API reference](/api-reference)).

Use logs to debug failed tool calls (inputs, outputs, timing, errors). In the product, the same data appears under [Tool execution logs](https://flowra.dev/dashboard/tool-execution-logs). Avoid sharing raw logs that may contain PII.

***

## Toolkits

**Toolkits** group related tools (for example Slack or Gmail). Each has a **slug**, name, description, and tool count. Use them to browse by product, configure auth once per toolkit, and filter tools with `toolkitSlug`.

### List toolkits

**GET** `/api/v1/toolkits` — paginated list. Search with `q`. Support `page`, `limit`, `offset`, `sortBy`, `sortOrder`.

```bash theme={null}
curl -X GET "https://flowra.dev/api/v1/toolkits?q=slack&limit=20" \
  -H "x-api-key: YOUR_API_KEY"
```

### List toolkits with nested tools

**GET** `/api/v1/toolkits/with-tools` — same list, each item includes a `tools` array. Search applies to toolkit and tool name/description. Optional `selectedToolSlugs` prioritizes matching toolkits.

```bash theme={null}
curl -X GET "https://flowra.dev/api/v1/toolkits/with-tools?q=send%20message&limit=20" \
  -H "x-api-key: YOUR_API_KEY"
```

Dashboard hub: [Toolkits & Tools](https://flowra.dev/dashboard/toolkit-tools). Product guide: [Toolkits and tools](/product/toolkits-and-tools). Longer-lived code runs: [Sandbox](/guides/sandbox).

## Related

* [Toolkits and tools](/product/toolkits-and-tools) — Dashboard catalog and Select Tools
* [Workflows](/guides/workflows) — Attach tools to workflows and run them.
* [Sandbox](/guides/sandbox) — Ephemeral and durable code execution.
* [Auth configs](/guides/auth-configs) — Configure OAuth/API keys for tools.
* [Native tools](/guides/native-tools) — Built-in Flowra tool slugs for agents.
* [API reference: Tools](/api-reference) — Full request/response schemas.