# Create and debug HTTP tools

> Turn an HTTP service into a callable tool and verify authentication, input, and response.

Source: https://doc.fastgpt.io/en/guide/build/tools/http_tools

HTTP tools convert internal REST services or third-party HTTP APIs into callable tools for Chat Agents, Agent V2 apps, and Workflows using either **batch OpenAPI Schema import** or **manual single-endpoint configuration**.

## Prerequisites and Creation Modes

You need tool creation permission in the active team and network reachability from the FastGPT server to the target API. Both modes are options under **Create Type** when you create an HTTP tool set, and the choice cannot be changed afterward.

| Creation Mode                                     | Best For                                                                                         | Key Characteristics                                                                                                                              |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Bulk creation** (OpenAPI Schema)                | A service exposing multiple related endpoints (such as order lookup, creation, and cancellation) | Shares a common Base URL and auth headers; paste OpenAPI 3.0 / Swagger JSON or YAML, or import it from a URL, to parse child tools automatically |
| **Create manually** (curl import or manual entry) | Connecting one standalone endpoint                                                               | Imports a curl command, or directly configures HTTP method (`GET`/`POST`/`PUT`/`DELETE`/`PATCH`), URL, query parameters, and body template       |

## Configure

1. Go to **Studio → My Tools**, click **New → HTTP Tools** in the upper-right corner, and choose **Bulk creation** or **Create manually** under **Create Type**.
2. Enter the service address, tool name, and description. In manual mode, import a curl command or set method and path; in bulk mode, inspect the parsed tool list.
3. Configure authentication headers (None, `Bearer Token`, `Basic Auth`, or custom Header key-value pairs), keeping fixed credentials in authentication settings. Define caller-supplied arguments, types, descriptions, and required fields.
4. Inspect request parameters, body, and output structure, then save.
5. Select a tool, supply known arguments in its debug panel, run it, and inspect the response or error.

![Bulk create an HTTP tool set from an OpenAPI Schema](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/current/http-tool-schema.png.webp)

![Manually configure a single-endpoint HTTP tool](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/current/http-tool-manual.png.webp)

For example, configure the read-only `GET /status` endpoint of your own test service. Expect the status fields defined by that service's contract. First verify server access with the same credential, then compare the FastGPT debug result.

## Authentication and Parameter Mapping

| Section                            | Description                                                                              | Recommendation                                                                                              |
| ---------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Authentication (Header Secret)** | Supports `Authorization: Bearer <token>`, `Basic`, or custom headers                     | Store static tokens in authentication settings rather than exposing them as model-populated input arguments |
| **Path & Query Parameters**        | Path placeholders in the URL or entries in the Params table                              | Declare accurate types (`string`/`number`/`boolean`) and clear descriptions so models supply valid values   |
| **Request Body**                   | Supports `application/json`, `form-data`, `x-www-form-urlencoded`, `xml`, and `raw-text` | Bind declared input parameters into the JSON body template                                                  |

## Connect an application

Add the tool through the application's tool selector and describe when to use it. Test a question requiring the tool and inspect model-supplied arguments and returned content. See [HTTP Request node](/en/guide/build/workflow/nodes/http) for an explicitly configured request inside a workflow.

## Troubleshoot

| Error                                       | Check                                                                                                                                                              |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 401 / 403                                   | Authentication value, service authorization scope, and expiration                                                                                                  |
| 404                                         | Service address, path, and request method                                                                                                                          |
| Non-2xx status code (e.g., 400 / 422 / 500) | The system includes the downstream HTTP response body in the tool error text; expand the execution details to inspect the upstream error code and message directly |
| Timeout or network failure                  | DNS, egress, TLS, and target service status from the FastGPT server                                                                                                |
| Argument or schema failure                  | Types, required values, body format, and actual response structure                                                                                                 |

Debugging can call the external service and produce its real effects. Verify target permissions and business confirmation requirements before using write operations. Remove authentication headers and personal data from troubleshooting material.