--- title: "Lookups" description: "Let your agent read one answer from your own system, and see what it is given." source: https://hiy.ai/docs/lookups --- # Lookups A **lookup** is a **Call your endpoint** [action](/docs/actions) that your agent uses to read one answer from your own system: where an order is, which plan a customer is on, whether a booking is confirmed. You choose the address, the key, and the few fields your agent may see. Nothing else from the reply reaches it. ## Add one Open the agent's **Tools** page, press **Add an action** in **Your actions**, and choose **Call your endpoint**. The editor opens beside the page, or as a sheet on a phone, and takes you through five steps. To change a lookup you have, press **Edit** on its card. 1. **Start.** Paste a cURL command, import an OpenAPI file, start from a template, or start from scratch. 2. **Request.** The address, whether it only reads or changes data, and the key it signs in with. 3. **Try.** Run it once against your real endpoint with a real value, and tick the fields your agent may read. 4. **Use.** Name it, and say in one sentence when your agent should use it. 5. **Turn on.** Switch it on for this agent and press **Save**. A lookup is saved **switched off** unless you turn it on in the last step, and your agent has never heard of it until then. ## Start from a cURL command or an OpenAPI file Both are read **in your browser**. They use no AI, and the file or command never reaches hiy until you save what it produced. - **Paste a cURL command.** The address, the method and the key come across. Each value in the query string becomes an input your agent fills from the conversation, up to four, and the value you pasted is kept to try it with. A key in the command, whether a bearer token, a username and password, or an API-key header, is saved to the credential store when you press **Save key**, and never goes into the lookup itself. - **Import an OpenAPI file.** JSON or YAML, OpenAPI 3, up to 1 MB. You see its operations with a **Read** or **Write** chip, pick one, and get its address, its inputs and the kind of key it takes. The reply fields the file describes are listed as suggestions to tick in **Try**. Whatever the import could not keep is listed by name, for example *Header X-Tenant*, so you can see what was left out. A key written into the address (`?api_key=…`) cannot be kept there: put it in a header. Only **GET** and **POST** can be a lookup. PUT, PATCH and DELETE are not supported. ## Inputs from the conversation Write `{order_id}` in the address and it becomes an input: your agent fills it only from what the visitor actually said, and never invents it. An address can take up to four. A fact your own site vouches for, such as the signed-in customer's id, can fill the same slot, and your agent never asks the visitor for it. A lookup that **changes data** has no slots in its address: it sends the visitor's summary in its body instead. ## Choose what your agent sees Enter a real value and press **Try it**: it really calls your endpoint, and the reply appears as a tree. **Nothing is ticked.** Tick a field to let your agent read it, up to six. Beside the tree, **What your agent sees** shows the exact values it would be given, and how many of the six you chose. - At most **2 KB** of those fields reaches your agent. If more would, the later fields are left out, never cut short, and your agent is told not to guess them. - A field you did not tick is named to your agent as *not read*, so it cannot be mentioned. - The reply is read for the owner only here. It is not stored, and your agent never sees it whole. ## Read or change data A lookup is a **Read** (GET) by default. Choose **Changes data (POST)** and it asks you to confirm: *This lookup can change data in your system.* A write is saved only once you have said so, and the database refuses a POST saved as a read. **Try is careful with a write.** A read is tried for real. A write first shows **exactly what would be sent**, and only a second press, **Send for real**, calls your system: *This will really call your system.* ## Which hosts your agents may call Your workspace keeps a list of **allowed hosts** under **Integrations → Your own API**. A lookup can only be switched on for a host on that list. An owner or admin adds one there, or with **Allow it** in the editor's Request step; anyone else sees "Ask an owner or admin to allow" the host. A host cannot be removed while a switched-on lookup still uses it. If a host is taken off the list, a lookup to it stops at once and your agent says it is not set up. Up to 20 hosts. The list is for the workspace, so every agent in it shares one. ## Your key Choose **No key**, a key you saved earlier, or **Add a key**, which stores it when you press **Save key** and shows only its last four characters. A key that goes in a header asks for the header name, and a username-and-password key asks for the username; both belong to the lookup, not to the key. A webhook signing secret is not offered, because it is never sent as a header. Every time a key is read, hiy records which lookup asked, and **Try** reads as *Try:* followed by the lookup’s name. No screen shows a key back. ## Recent calls Each lookup lists its **Recent calls**: when, whether it was a test, a rehearsal in **Test** or a live answer, how it ended, the status and how long it took, and the fields it kept. Calls are kept **30 days**. Only names are kept, never what a visitor typed, a key, or what your endpoint replied, so there is nothing to replay: use **Try** to see a reply again. ## Limits See [Actions](/docs/actions#limits): two actions in one answer, 30 live calls a minute for each lookup, 10 seconds to answer, 32 KB read and 2 KB handed over. **Try** is limited to 10 a minute for the whole workspace. **Note:** **A lookup that returns more than an order's status needs a signed-in visitor.** Two typed fields, an email and an order number, are on every packing slip, so they are enough for order status and for nothing more sensitive. For account data, vouch for the visitor from your own site with [site facts](/docs/actions#what-your-site-can-tell-your-agent).