> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roe-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom API Connector
> Connect any REST API to Roe AI with configurable authentication and endpoints
Connect any REST API to Roe AI by configuring authentication and endpoint definitions. The Custom API connector lets you bring your own API — whether it's an internal service, a third-party platform, or a proprietary data source — and expose it to agents as callable tools.
## Use Cases
* **Fraud Investigation**: Query internal risk scoring APIs, payment processors, or identity verification services
* **AML Investigation**: Access customer due diligence APIs, sanctions screening, or transaction monitoring systems
* **Merchant Risk**: Connect to underwriting or merchant monitoring APIs for risk assessment and due diligence
* **Product Compliance**: Integrate with regulatory databases or compliance checking APIs to verify product and policy adherence
* **Data Enrichment**: Pull data from any REST API to enrich agent investigations with additional context
## Prerequisites
Before creating a Custom API connection, ensure you have:
1. The **base URL** of the API you want to connect (e.g., `https://api.acme.com/v1`)
2. **Authentication credentials** for one of the supported auth methods
3. **API documentation** for the endpoints you want to expose to agents
## Supported Authentication Methods
The Custom API connector supports four authentication strategies:
| Auth Type | Description | Use When |
| ----------------------------- | ----------------------------------------------- | ------------------------------------------- |
| **API Key** | Send an API key as a header or query parameter | Most common for third-party APIs |
| **Bearer Token** | Static Bearer token in the Authorization header | Pre-issued tokens or personal access tokens |
| **Basic Auth** | HTTP Basic authentication (username/password) | Legacy or internal APIs |
| **OAuth2 Client Credentials** | OAuth2 client credentials flow | Modern APIs with machine-to-machine auth |
## Configure the Connection
### Configuration (Non-Sensitive)
| Field | Required | Description |
| ------------------- | -------- | ---------------------------------------------------------------------------------------- |
| **Base URL** | Yes | Root URL for the API (e.g., `https://api.acme.com/v1`). No trailing slash. |
| **Endpoints** | Yes | List of API endpoints the agent can call (see [Defining Endpoints](#defining-endpoints)) |
| **Default Headers** | No | Headers sent with every request (e.g., `{"Accept": "application/json"}`) |
| **Timeout** | No | Request timeout in seconds (default: 30, max: 120) |
### Authentication (Sensitive)
Credentials are encrypted and stored in AWS Secrets Manager.
| Field | Required | Description |
| --------------- | -------- | ---------------------------------------------------------- |
| **API Key** | Yes | The API key value |
| **Header Name** | No | Header name to send the key in (default: `X-API-Key`) |
| **Location** | No | Where to send the key: `header` (default) or `query_param` |
| Field | Required | Description |
| --------- | -------- | ---------------------- |
| **Token** | Yes | The Bearer token value |
| Field | Required | Description |
| ------------ | -------- | ----------------------- |
| **Username** | Yes | Authentication username |
| **Password** | Yes | Authentication password |
| Field | Required | Description |
| ----------------- | -------- | ------------------------------------------ |
| **Client ID** | Yes | OAuth2 client ID |
| **Client Secret** | Yes | OAuth2 client secret |
| **Token URL** | Yes | OAuth2 token endpoint URL |
| **Scope** | No | OAuth2 scope (space-separated if multiple) |
Roe AI automatically handles token refresh. Tokens are cached and refreshed 60 seconds before expiry.
## Defining Endpoints
Each endpoint you define becomes a tool that agents can call during investigations. The endpoint **name** is used as the tool identifier, and the **description** is shown to the LLM to help it decide when and how to call it.
Write clear, specific endpoint descriptions. The LLM uses these descriptions to decide which endpoints to call and when. Good descriptions lead to better agent behavior.
### Endpoint Fields
| Field | Required | Description |
| ----------------- | -------- | --------------------------------------------------------------------------------------- |
| **Name** | Yes | Unique identifier (e.g., `get_customer`, `search_transactions`). Used as the tool name. |
| **Description** | Yes | What this endpoint does. Shown to the LLM as the tool description. |
| **Method** | No | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` (default: `GET`) |
| **Path** | Yes | URL path appended to the base URL. Use `{param_name}` for path parameters. |
| **Parameters** | No | List of parameters this endpoint accepts (see below) |
| **Response Hint** | No | Hint about the response format to help the LLM interpret results |
### Parameter Fields
| Field | Required | Description |
| --------------- | -------- | ----------------------------------------------------------------- |
| **Name** | Yes | Parameter name (e.g., `customer_id`) |
| **Location** | Yes | Where the parameter is sent: `path`, `query`, `body`, or `header` |
| **Type** | No | Data type: `string` (default), `integer`, `number`, or `boolean` |
| **Description** | No | Human-readable description shown to the LLM |
| **Required** | No | Whether this parameter is required (default: `true`) |
### Example Configuration
```json theme={null}
{
"base_url": "https://api.acme.com/v1",
"default_headers": {
"Accept": "application/json"
},
"timeout_seconds": 30,
"endpoints": [
{
"name": "get_customer",
"description": "Retrieve customer details by ID, including name, email, risk score, and account status",
"method": "GET",
"path": "/customers/{customer_id}",
"parameters": [
{
"name": "customer_id",
"location": "path",
"param_type": "string",
"description": "The unique customer identifier",
"required": true
}
],
"response_hint": "Returns JSON with customer name, email, risk_score, account_status"
},
{
"name": "search_transactions",
"description": "Search transactions by customer ID with optional date range and amount filters",
"method": "GET",
"path": "/transactions",
"parameters": [
{
"name": "customer_id",
"location": "query",
"param_type": "string",
"description": "Filter by customer ID",
"required": true
},
{
"name": "start_date",
"location": "query",
"param_type": "string",
"description": "Start date (YYYY-MM-DD)",
"required": false
},
{
"name": "end_date",
"location": "query",
"param_type": "string",
"description": "End date (YYYY-MM-DD)",
"required": false
},
{
"name": "min_amount",
"location": "query",
"param_type": "number",
"description": "Minimum transaction amount",
"required": false
}
],
"response_hint": "Returns a list of transaction objects with amount, date, type, and status"
},
{
"name": "submit_risk_assessment",
"description": "Submit a risk assessment for a customer with a score and reasoning",
"method": "POST",
"path": "/risk-assessments",
"parameters": [
{
"name": "customer_id",
"location": "body",
"param_type": "string",
"description": "Customer ID to assess",
"required": true
},
{
"name": "risk_score",
"location": "body",
"param_type": "number",
"description": "Risk score from 0 to 100",
"required": true
},
{
"name": "reasoning",
"location": "body",
"param_type": "string",
"description": "Explanation for the risk score",
"required": true
}
]
}
]
}
```
## Test the Connection
Click **Test Connection** to verify that Roe AI can reach your API. The test will:
1. Apply the configured authentication
2. Send a HEAD request to the base URL
3. Verify the API is reachable (any non-5xx response is considered successful)
The test only checks connectivity to the base URL. Individual endpoint availability is validated when agents call them.
## Using Custom API as a Context Source
Once connected, you can use your Custom API connection as a **context source** in agentic workflows. Each configured endpoint is exposed to the agent as a callable tool.
### Context Source Configuration
```json theme={null}
{
"connection_type": "custom_api",
"name": "Risk Scoring API",
"connection_id": "your-connection-uuid",
"description": "Internal risk scoring API for customer due diligence"
}
```
| Field | Description |
| --------------- | ----------------------------------------------- |
| `name` | Friendly name for this data source |
| `connection_id` | UUID of your Custom API connection |
| `description` | Helps the agent understand when to use this API |
### Agent Capabilities
When a Custom API is configured as a context source, agents can:
* **Discover endpoints**: See all configured endpoint names and descriptions
* **Call endpoints**: Invoke any endpoint with the appropriate parameters
* **Interpret responses**: Use response hints and data to inform investigation findings
* **Chain calls**: Make multiple API calls to gather comprehensive data
## Writing Effective Endpoint Descriptions
The quality of your endpoint descriptions directly impacts how well agents use your API. Here are some guidelines:
Instead of "Get customer", write "Retrieve customer details by ID, including name, email, risk score, and account status"
Explain what each parameter means and what values are accepted, especially for enums or constrained fields
Tell the agent what fields to expect in the response so it can extract the right data
Use descriptive names like `search_transactions` or `get_customer_risk_score` rather than generic names
## Security Best Practices
Use API credentials with the minimum required permissions — read-only where possible
Create dedicated API keys or service accounts for Roe AI rather than sharing personal credentials
Only expose endpoints that agents actually need — avoid including admin or write endpoints unnecessarily
Review your API logs to audit what data agents are accessing
## Troubleshooting
Verify the base URL is correct and reachable from the internet. Roe AI cannot connect to private networks or localhost.
The API returned a server error. This is likely an issue with the API itself — verify it's healthy and accepting requests.
The API did not respond within the configured timeout. Check that the URL is correct and the API is responsive. You can increase the timeout up to 120 seconds.
Verify your authentication credentials are correct. For OAuth2, ensure the client ID, secret, and token URL are valid. For API keys, check the header name and location match what the API expects.
The agent tried to call an endpoint name that doesn't match any configured endpoint. Verify the endpoint names in your configuration.
The agent called an endpoint without providing a required parameter. Check that the parameter descriptions are clear enough for the agent to know what values to provide.
Verify the token URL, client ID, and client secret are correct. Ensure the OAuth2 server supports the client credentials grant type.