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

# HTTP Tool

> Create, configure, test, and assign an HTTP request tool so your assistant can fetch live data or take actions during a chat.

An HTTP tool is an HTTP request the assistant can call during a conversation. You define the request — method, URL, headers, and parameters — and the assistant fills in the parameters and calls it when a shopper's question matches. A common example is looking up an order's status from your backend and answering with the result.

<Note>
  HTTP Tool are configured at the organization level and then assigned to the assistants that should use them. To keep API keys and OAuth out of the request, set up [Secrets](/en/user-guide/settings/secrets) and [Auth Connections](/en/user-guide/settings/auth-connections) first.
</Note>

## Create a tool

<Steps>
  <Step title="Open Tools">
    On the platform, go to **Tools** and select **New tool**. Choose **HTTP Request**, or start from a template such as *Shipment tracking* and adjust it.
  </Step>

  <Step title="Name and describe the tool">
    Under **Configuration**, give the tool a clear **Name** (for example, `Order status lookup`) and a **Description** of when it should be used. The description helps the assistant decide when the tool is relevant, so be specific.
  </Step>

  <Step title="Define the parameters">
    Under **Parameters**, add the inputs the request needs (such as `order_number`). Use lowercase `snake_case` names. For each parameter, set a **Data type** and a **Value type**: either a **Constant value** that stays the same on every call, or a value the assistant fills in from the conversation. For assistant-filled values, you can also describe how it should obtain them.
  </Step>

  <Step title="Configure the HTTP request">
    Under **HTTP request**, set:

    * **Method** — `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.
    * **URL** — the endpoint to call. Use `{parameter_name}` placeholders to insert parameters, e.g. `https://api.example.com/orders/{order_number}`.
    * **JSON body** (for `POST`, `PUT`, and `PATCH`) — a JSON template that can also use `{parameter_name}` placeholders.
    * **Authentication** — attach an [Auth connection](/en/user-guide/settings/auth-connections) instead of putting credentials in the request.
    * **Headers** (optional) — additional request headers as name/value pairs.

    You can also adjust the request timeout (the maximum time to wait for the external API to respond).
  </Step>

  <Step title="Select response fields (optional)">
    Under **Response fields**, choose which fields from the JSON response are passed to the assistant. Without a selection, the assistant receives the entire response.
  </Step>

  <Step title="Test the tool">
    Select **Test tool**, enter sample parameter values, and run it.

    <Check>
      The request returns the status and data you expect. Fix the URL, headers, or parameters until the test response is correct.
    </Check>

    <Warning>
      A test makes the real outbound request to your endpoint. Test against a safe endpoint and avoid running tools that perform unintended writes.
    </Warning>
  </Step>

  <Step title="Assign it to an assistant">
    Save the tool, then open the assistant that should use it and assign the tool from its **Tools**. The assistant can now call it during chats whenever the shopper's question matches the tool's description.
  </Step>
</Steps>

## Security

Never paste secrets directly into a tool's headers or URL:

* Store API keys and other sensitive values as **Secrets** so they are kept encrypted and never exposed in plain text. See [Settings › Secrets](/en/user-guide/settings/secrets).
* Use an **Auth connection** when the tool needs authentication — Bearer, Basic, a custom header, or OAuth — to act against a third-party service. See [Settings › Auth Connections](/en/user-guide/settings/auth-connections).

<Warning>
  Always test a tool before assigning it. An assigned tool can be called automatically during live chats, so make sure the endpoint behaves as expected and never performs unintended writes.
</Warning>

## Availability

Whether Tools are available, and how many HTTP tools you can create, depends on your plan. When you reach the limit, delete a tool you no longer need or upgrade your plan.

## Next steps

<CardGroup cols={2}>
  <Card title="Secrets" icon="key" href="/en/user-guide/settings/secrets">
    Store API keys your tools reference securely.
  </Card>

  <Card title="Email tool" icon="envelope" href="/en/user-guide/tools/email-tool">
    Let the assistant send emails from a verified sender.
  </Card>
</CardGroup>