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

# API Connections

> Connect REST or web endpoints, classify them as SOURCE or ACTION, map inputs and outputs, and test them before Assistant uses them.

Use **Connections → API Connections** to connect AI Assistant to HTTP APIs and live web endpoints.

## Start with the business effect

Choose the connection category first:

* **SOURCE** for read-only retrieval.
* **ACTION** for anything that can change external state.

Examples of SOURCE calls include checking an order, reading an account balance, or retrieving a warranty status.

Examples of ACTION calls include cancelling an order, issuing a refund, changing a subscription, or creating a return.

## Request configuration

An API Connection can define:

* base URL;
* HTTP method;
* headers;
* query parameters;
* request-body template;
* input schema/variables;
* response mode;
* output mapping; and
* cache TTL.

The editor can extract variables from templated request fields so those values can be supplied by the Assistant workflow.

## Authentication

A connection can use:

* no authentication;
* API key;
* Bearer token;
* Basic authentication;
* OAuth 2.0; or
* a reusable encrypted credential from **Connections → Authentication**.

Prefer shared credentials when several integrations use the same secret.

## Output mapping

Map the response to fields that are meaningful to the procedure using the connection.

A technically successful response that leaves the Assistant interpreting a 200-line vendor payload is not a particularly successful integration.

Expose the fields the workflow actually needs.

## JSON versus web-page response mode

Most APIs return structured JSON.

A web-page response mode is available for live webpage retrieval where supported. It behaves as a read-only source rather than a state-changing action.

## Cache TTL

Use caching for SOURCE data that is safe to reuse briefly.

Do not use a long cache for information whose freshness determines the business decision, such as a just-cancelled order or a rapidly changing account state.

## Test the connection

Before saving a production workflow:

1. enter representative test variables;
2. run the connection test;
3. inspect the final destination and request preview;
4. verify authentication succeeded;
5. inspect returned data; and
6. confirm the output mapping exposes the expected fields.

## Automatic approval

ACTION connections can expose automatic-approval behavior, but it is not enabled by default.

Enable it only after reviewing the action's business risk, input validation, authorization, idempotency, and recovery behavior.

## Simulation

Assistant Simulation executes SOURCE calls normally but intercepts ACTION side effects and reports what would have run.

Use Simulation before connecting a new ACTION to Agent Mode.

> **[Authentication](https://docs.raum.am/assistant/authentication.md)**
>
> Store reusable encrypted credentials.

> **[MCP Servers](https://docs.raum.am/assistant/mcp-servers.md)**
>
> Connect hosted tool servers with discovered tool schemas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.