Connections and tools

Indexed knowledge is what the agent cites. A Connection is a live HTTPS API it may call — but only through the exact Tools you approve, and never with the credential in the model's hands.

Where it lives

Knowledge in the workspace sidebar, then the Connections or Tools tab — /workspaces/:id/knowledge/connections and /workspaces/:id/knowledge/tools. Both are owner-only. Agents can still open Knowledge to work sources; they don't see these tabs, and the server refuses the URLs.

You need an active subscription to test a Connection, save a credential, or enable a Tool. The pages are visible either way.

This is not the Shopify shop connection

The Tools form uses order_id and /orders/{order_id} as placeholders. They are examples of a path parameter, not a Doorwick commerce feature. Point a Connection at your own HTTPS API when you want the agent to call it. Linking a Shopify shop for read-only orders is a separate owner setting — see Connect Shopify.

Add a Connection first

A Connection is one API: a name, an optional description, a public HTTPS base URL, and how Doorwick authenticates.

Authentication is one of:

Bearer token: Sent as Authorization: Bearer …
API key header: Sent on the header you name (the field defaults to X-API-Key)
No authentication: No credential stored

The credential is write-only and encrypted at rest. After you save it, the page shows that one is configured and never returns the value. Leave the field blank on later edits to keep what's stored; use Rotate credential when you need to replace it.

New Connections stay Untested until you hit Test. A successful test marks the row Connected. Failures show as authentication failed, invalid response, unreachable, or timed out. Changing the URL, auth type, or credential puts it back to untested.

Set Connection test path to a lightweight endpoint such as /health or /me that returns a successful 2xx response with the saved authentication. Test sends an authenticated GET below the Base URL. It does not have to be the API root, and it cannot contain a query, fragment, placeholder, or different host.

Disable a Connection when you want Doorwick to stop using it. Delete is blocked while any Tools still point at it — remove or reassign those first.

Then define a Tool

A Tool is one narrow operation on that Connection. The model sees the Tool's name, description, and parameter schema. It never sees the Connection credential, the raw URL, or your API key.

Connection: Which API it calls.
Name and Tool ID: The ID is lowercase letters, numbers, and underscores (look_up_order).
When should Doorwick use it?: The description the model reads. Write the situation, not the HTTP details.
Capability: Read information (GET or HEAD) or Perform an action (POST, PUT, PATCH, or DELETE).
Who may use it?: Any visitor / Verified visitor / Human operator only. Human-only definitions are stored for an operator workflow and are never enabled or exposed to the visitor AI.
Relative API path: Begins with /. Path parameters in braces, then define each under Parameters.
Enable for AI use: Off until you turn it on.

You can't enable a Tool until its Connection is enabled and has passed a test. Leave action Tools off while you review who may use them and what confirmation will ask. Doorwick must not perform a consequential change without the required approval.

Test a Read Tool before enabling it

Save a Read Tool with Enable for AI use off, open its menu, then choose Test Tool. Enter sample values for its declared parameters. Doorwick sends the real GET or HEAD request from the server, so this verifies path substitution, query values, authentication, URL policy, response type, and timeouts together. A successful Tool test also marks its Connection connected.

The test record keeps only the outcome, safe error code, HTTP status, and time. Doorwick does not store the sample values or response body. Action Tools cannot be sent from this dashboard test because POST, PUT, PATCH, or DELETE may change external state; validate those through the visitor confirmation flow.

A passing test proves that one request completed. It does not prove every visitor is authorized, every parameter value exists, or the external provider will remain available.

What the visitor sees

Read Tools run when the agent calls them. Action Tools always stop for confirmation first. The widget shows the Tool's name and description with Confirm and Not now. Typing "yes" in the thread does not count — only those controls do. A confirmation that sits too long expires and the visitor has to start again.

Confirmation is bound to the exact Tool definition and parameters that were proposed. If an owner changes the Connection, method, path, schema, authorization, name, or description before execution, Doorwick refuses the old confirmation and the visitor must review a newly prepared action.

A successful Tool call can attach a Live data: line under the answer, with the Tool name and the Connection name. That is not a knowledge citation. Citations still come from indexed sources; live data comes from the API you connected.

If a Tool is disabled, unauthorized, or the Connection is unhealthy, the agent is told to say so and offer a human — not to invent a result.

Used Tools stay on the record

A Tool that has been invoked can't be deleted. Disable it so the agent stops calling it; the invocation history stays. Unused Tools can be deleted.

The Tools tab shows the last AI use and the last dashboard test separately. A failed test includes a safe remediation message, while upstream response bodies and submitted sample values stay out of the dashboard and event history.

Knowledge citations vs live API calls

Source: Knowledge is indexed pages and pasted text. Connections and Tools are a live HTTPS API you approve.
What the visitor sees: Knowledge attaches citations and next-page links from approved URLs. A Tool can attach a Live data line, and action Tools stop for Confirm / Not now.
When to use: Use Knowledge for policy. Use a Tool when the answer has to be live and you will define that one call.