> ## Documentation Index > Fetch the complete documentation index at: https://docs.slng.ai/llms.txt > Use this file to discover all available pages before exploring further. # Call an external API > Create an API Request tool that sends one HTTPS request to an existing service. Create an API Request tool when an agent needs one request to a service you already run. You configure the endpoint, authentication, input schema, response, timeout, and failure behavior without writing code. ## Prerequisites * An HTTPS endpoint that accepts the request method and JSON arguments you plan to use. * Any bearer or HMAC secret stored in your organization Vault. * Permission to manage organization tools. Go to **Global Tools**, choose **New tool**, then select **API Request**. Enter a tool name and **Instructions**. **Instructions** maps to the API `description` field. Use a name made of letters, numbers, underscores, or dashes. The New tool page with API Request highlighted Create the draft with `POST /v1/agents/tools`. Replace the `.example` URL and Vault secret name with values for your service before testing it. ```json tool.json theme={null} { "name": "lookup_order", "description": "Look up the current status of a Wayne Enterprises order.", "tool_type": "api_request", "config": { "type": "api_request", "url": "https://api.wayne.example/orders/status", "http_method": "POST", "auth": { "type": "bearer", "secret_name": "WAYNE_API_TOKEN" }, "headers": [ { "name": "X-Client", "value": "voice-agent" } ], "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The order identifier provided by the caller" } }, "required": ["order_id"] }, "strict": true, "webhook_format": "raw", "timeout_seconds": 10, "wait_for_response": true, "response": { "show_to_llm": true, "instructions": "Tell the caller the order status and expected delivery date." } } } ``` ```bash Request theme={null} curl -X POST https://api.agents.slng.ai/v1/agents/tools \ -H "Authorization: Bearer $SLNG_API_KEY" \ -H "Content-Type: application/json" \ -d @tool.json ``` Set the literal HTTPS **Request URL** and choose the **Method**. The URL cannot contain credentials or a fragment. The API Request tool editor with the Request URL field highlighted Set the literal HTTPS URL in `config.url` and choose `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` in `config.http_method`. The URL cannot contain credentials or a fragment. Choose **None**, **Bearer**, or **HMAC** authentication. Bearer and HMAC settings reference a Vault secret by its `SCREAMING_SNAKE_CASE` name. Do not add `Authorization`, `X-Signature-256`, `Host`, or other transport headers yourself. Parameters are values the model extracts from the conversation and passes to the tool. For example, a forecast tool can define a `city` parameter so the model passes the city mentioned by the caller. Use **Builder** to add each parameter. Give it a clear name and description so the model knows which value to extract. Mark a parameter as required when the request cannot run without it. The Parameters section of the API Request tool editor with Add parameter highlighted Define the JSON Schema object in `config.parameters`. Add every required property to `required`, and describe each value precisely. Set `config.strict` to `true` to reject arguments that the schema does not define. A `GET` request sends arguments as query parameters. Other methods send the arguments as the raw JSON request body. Tool-level header values are literals or Vault references. The executor builds the query string from the tool's parameters. Pass a fixed value like an API key as a parameter, and pin it with the attachment's `argument_overrides` (or a parameter `enum`). A query string written into `config.url` is dropped, so keep the key in a parameter. When you test with `/run`, pass the value in `sample_input`. **Show the result to the model** controls whether the result enters the conversation. Use **Result instructions** to tell the model how to interpret it. The Response section of the API Request tool editor with Show the result to the model highlighted Set `response.show_to_llm` and `response.instructions`. The API also accepts `timeout_seconds` from 1 to 60 and `wait_for_response`. Keep the default wait enabled when the agent needs the result before continuing. Run the draft with representative inputs. Confirm the endpoint received the expected body and returned the expected JSON. You must complete a successful test for the current draft before publishing it. Attach the version to an agent. Set whether the model or a call event invokes it on the attachment, not on the tool draft. See [Attach a tool to an agent](/guides/agents/tools-and-mcp/attach-to-an-agent). ## Handle failures A run can fail because the endpoint times out, returns an invalid response, or rejects authentication. Keep the timeout shorter than the maximum delay a caller should hear. Add a pre-action message on the attachment when a normal response can take several seconds. If the agent does not need the response, set `wait_for_response` to `false`. This also prevents the response from being shown to the LLM. See [Tools API reference](/api-reference/agents-resources/tools) for the complete request and lifecycle endpoint contracts.