Skip to main content
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 TypeDescriptionUse When
API KeySend an API key as a header or query parameterMost common for third-party APIs
Bearer TokenStatic Bearer token in the Authorization headerPre-issued tokens or personal access tokens
Basic AuthHTTP Basic authentication (username/password)Legacy or internal APIs
OAuth2 Client CredentialsOAuth2 client credentials flowModern APIs with machine-to-machine auth

​
Configure the Connection

​
Configuration (Non-Sensitive)

FieldRequiredDescription
Base URLYesRoot URL for the API (e.g., https://api.acme.com/v1). No trailing slash.
EndpointsYesList of API endpoints the agent can call (see Defining Endpoints)
Default HeadersNoHeaders sent with every request (e.g., {"Accept": "application/json"})
TimeoutNoRequest timeout in seconds (default: 30, max: 120)

​
Authentication (Sensitive)

Credentials are encrypted and stored in AWS Secrets Manager.
FieldRequiredDescription
API KeyYesThe API key value
Header NameNoHeader name to send the key in (default: X-API-Key)
LocationNoWhere to send the key: header (default) or query_param

​
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

FieldRequiredDescription
NameYesUnique identifier (e.g., get_customer, search_transactions). Used as the tool name.
DescriptionYesWhat this endpoint does. Shown to the LLM as the tool description.
MethodNoHTTP method: GET, POST, PUT, PATCH, or DELETE (default: GET)
PathYesURL path appended to the base URL. Use {param_name} for path parameters.
ParametersNoList of parameters this endpoint accepts (see below)
Response HintNoHint about the response format to help the LLM interpret results

​
Parameter Fields

FieldRequiredDescription
NameYesParameter name (e.g., customer_id)
LocationYesWhere the parameter is sent: path, query, body, or header
TypeNoData type: string (default), integer, number, or boolean
DescriptionNoHuman-readable description shown to the LLM
RequiredNoWhether this parameter is required (default: true)

​
Example Configuration

{
  "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

{
  "connection_type": "custom_api",
  "name": "Risk Scoring API",
  "connection_id": "your-connection-uuid",
  "description": "Internal risk scoring API for customer due diligence"
}
FieldDescription
nameFriendly name for this data source
connection_idUUID of your Custom API connection
descriptionHelps 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:

Be Specific

Instead of “Get customer”, write “Retrieve customer details by ID, including name, email, risk score, and account status”

Describe Parameters

Explain what each parameter means and what values are accepted, especially for enums or constrained fields

Add Response Hints

Tell the agent what fields to expect in the response so it can extract the right data

Use Clear Names

Use descriptive names like search_transactions or get_customer_risk_score rather than generic names

​
Security Best Practices

Least Privilege

Use API credentials with the minimum required permissions — read-only where possible

Dedicated Credentials

Create dedicated API keys or service accounts for Roe AI rather than sharing personal credentials

Limit Endpoints

Only expose endpoints that agents actually need — avoid including admin or write endpoints unnecessarily

Monitor Usage

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.