> ## 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`). Copy slugs from the list — catalog actions are typically `UPPER_SNAKE`. |
| `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).

Toolkit list endpoints (`GET /toolkits`, `GET /toolkits/with-tools`) are covered above and via `toolkits.*` in the [SDK](/guides/sdk).

## SDK

```ts theme={null}
const tools = await flowra.tools.list({ limit: 10, toolkitSlug: 'slack' });
const slug = tools.data?.[0]?.slug ?? tools.items?.[0]?.slug ?? 'SLACK_SEND_MESSAGE';
await flowra.tools.execute(slug, { arguments: { /* ... */ } });
const kits = await flowra.toolkits.listWithTools({ q: 'slack' });
```

```python theme={null}
tools = flowra.tools.list(limit=10, toolkitSlug="slack")
items = tools.get("data") or tools.get("items") or []
slug = (items[0] or {}).get("slug", "SLACK_SEND_MESSAGE") if items else "SLACK_SEND_MESSAGE"
flowra.tools.execute(slug, {"arguments": {}})
kits = flowra.toolkits.list_with_tools(q="slack")
```

See [SDKs](/guides/sdk).

## 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.


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