Skip to main content

HTTP API Tools

Connect external REST APIs as tools that agents can use during email processing.

Overview​

HTTP API Tools allow your agents to interact with external services by making HTTP requests. Instead of manually configuring each API endpoint, Control Bridge uses AI to analyze your API documentation and automatically generate tool configurations.

Use Cases​

  • CRM Integration - Look up customer information from Salesforce, HubSpot, or custom CRMs
  • Ticketing Systems - Create or update tickets in Zendesk, ServiceNow, or Jira
  • Internal APIs - Connect to your company's internal services
  • Third-party Services - Access weather, shipping, payment, or other external APIs
  • Data Enrichment - Augment email context with external data sources

How It Works​

API Documentation          AI Analysis           Agent Tool
      │                        │                     │
      ▼                        ▼                     ▼
┌─────────────┐         ┌─────────────┐      ┌─────────────┐
│ OpenAPI/    │   →    │ Multi-pass  │  →  │ Configured  │
│ Swagger/    │         │ LLM         │      │ HTTP Tool   │
│ Markdown    │         │ Processing  │      │ ready to    │
│ Spec        │         │             │      │ use         │
└─────────────┘         └─────────────┘      └─────────────┘

Creating an HTTP API Tool​

Prerequisites​

Before starting the wizard:

  1. API Documentation - Have your API specification ready (OpenAPI, Swagger, Postman collection, or markdown documentation)
  2. API Credentials - Have authentication details available (API keys, tokens, etc.)
  3. Anthropic Model - Ensure you have at least one Anthropic (Claude) model configured in your AI providers

Step 1: Navigate to the Wizard​

  1. Navigate to Build > Connections > API Tools
  2. Click Add HTTP API Tool
  3. You'll see the introduction page explaining the wizard process

Step 2: Upload Your API Specification​

Choose how to provide your API documentation:

Option A: Upload a File​

  • Supported formats: JSON, YAML, TXT, MD, PDF
  • Drag and drop or click to browse
  • Maximum size: 500KB

Option B: Paste Specification​

  • Paste your API documentation directly
  • Works with OpenAPI/Swagger JSON/YAML or markdown documentation

Option C: Fetch from URL​

  • Enter the URL to your API documentation
  • The system will fetch and analyze it automatically

Best Practices for Specifications:

  • Include endpoint descriptions and parameter details
  • Document authentication requirements clearly
  • Provide example requests and responses when possible
  • The more detail you provide, the better the AI analysis

Step 3: Select AI Model​

Choose an Anthropic (Claude) model to process your specification:

ModelBest For
Claude SonnetMost specifications - balanced speed and accuracy
Claude OpusComplex specifications with many endpoints
Claude HaikuSimple specifications with few endpoints

Note: The wizard requires an Anthropic model because it uses streaming responses for real-time progress updates. If you don't see any models, configure an Anthropic provider first in AI Providers.

Step 4: Processing​

The AI analyzes your specification through multiple passes:

  1. Triage Pass (5-15%) - Identifies document structure and format
  2. Authentication Pass (15-25%) - Detects authentication requirements
  3. Discovery Pass (25-50%) - Extracts available endpoints
  4. Analysis Pass (50-75%) - Analyzes parameters and responses
  5. Generation Pass (75-90%) - Creates tool configurations
  6. Validation Pass (90-100%) - Verifies the configuration

During processing:

  • Watch real-time progress updates
  • View the log of analysis steps
  • Cancel anytime if needed

If more than 5 endpoints are found:

  • You'll be asked to select which endpoints to include
  • Recommended endpoints are pre-selected
  • Maximum 5 endpoints per integration

Step 5: Review Configuration​

Review the generated configuration:

Integration Details​

  • Name - Friendly name for this integration
  • Description - What this integration does
  • Base URL - The API's base URL

Endpoints​

For each discovered endpoint, review:

  • HTTP method (GET, POST, PUT, etc.)
  • Endpoint path
  • Parameters and their types
  • Description

You can:

  • Edit any field that needs adjustment
  • Toggle endpoints on/off
  • Modify parameter descriptions

Step 6: Configure Authentication​

Set up authentication for the API:

No Authentication​

Use for public APIs that don't require credentials.

API Key​

Header Name: X-API-Key (or your API's header name)
API Key: your-api-key-here

Bearer Token​

Token: your-bearer-token-here

Automatically sent as Authorization: Bearer <token>

Basic Authentication​

Username: your-username
Password: your-password

Automatically encoded and sent as Authorization: Basic <encoded>

OAuth 2.0 (Client Credentials)​

Token URL: https://api.example.com/oauth/token
Client ID: your-client-id
Client Secret: your-client-secret
Scope: api.read api.write (optional)

Tip: If the AI didn't correctly detect your authentication requirements, click Re-analyze to have it scan the specification again with fresh context.

Step 7: Test the Connection​

Before finalizing, test your configuration:

  1. Select an Endpoint - Choose which endpoint to test
  2. Fill Path Parameters - Enter values for any {param} placeholders
  3. Add Request Body - For POST/PUT requests, enter test data
  4. Execute Test - Send a test request

Interpreting Results:

ResultMeaning
200-299Success - tool is configured correctly
401Authentication failed - check credentials
403Forbidden - check API permissions
404Endpoint not found - verify the path
500Server error - API issue (not your config)

Expect Error Response: Check this option if you're testing with data that should return an error (like a non-existent ID). This prevents valid 4xx responses from being flagged as failures.

Skip Testing Option: You can skip testing to complete setup later, but we recommend testing at least one endpoint.

Step 8: Complete​

Your HTTP API Tool is now ready to use! The summary shows:

  • Integration name and endpoints created
  • Which agents can use the tool
  • Next steps for assigning the tool

Assigning API Tools to Agents​

After creating an HTTP API Tool:

  1. Navigate to Build > AI Agents > Agents
  2. Edit the agent that should use this tool
  3. In the Tools section, find your new API tool
  4. Check the box to enable it
  5. Save the agent

The tool will now be available when that agent processes emails.

Managing API Tools​

View All Integrations​

Navigate to Build > Connections > API Tools to see all configured integrations.

Edit an Integration​

  1. Click on an integration card
  2. Modify settings as needed
  3. Click Save Changes

Toggle Active/Inactive​

Use the toggle switch to enable or disable an integration without deleting it.

Delete an Integration​

  1. Click the delete button on the integration card
  2. Confirm deletion

Warning: Deleting an integration also removes it from all agents that use it. Consider deactivating instead if you might need it later.

Execution Logging and Audit Trail​

All API tool executions are comprehensively logged for troubleshooting, compliance, and security auditing.

Agent Execution Logs​

View API tool calls within agent execution context:

  1. Navigate to Monitor > Activity > Agent Activity
  2. Click on an execution
  3. Expand the tool calls section
  4. View request/response details

Integration Logs​

For detailed API-specific logging, view the dedicated Integration Logs:

  1. Navigate to Manage > Data & Logs > Integration Logs
  2. Filter by integration, date range, or status
  3. Click any log entry to view full request/response details

What Gets Logged​

Every API request and response is captured as a JSON audit log with:

CategoryDetails
RequestURL, HTTP method, headers (credentials redacted), body
ResponseStatus code, headers, body (truncated if large)
TimingTotal duration, DNS lookup, connection time, TLS handshake, first byte, download
ContextIntegration name, endpoint name, agent execution ID, timestamp
ResultSuccess/failure status, error messages, retry count

Automatic Redaction​

Sensitive data is automatically redacted before storage to protect credentials and PII:

Always Redacted:

  • Authorization headers and API keys
  • Bearer tokens and OAuth credentials
  • Passwords and secrets in request/response bodies
  • Cookies and session tokens

PII Protection:

  • Social security numbers (pattern-matched)
  • Credit card numbers
  • JWT tokens and AWS access keys

Redacted values appear as [REDACTED] in logs while preserving document structure for debugging.

Troubleshooting​

AI Processing Fails​

Problem: Processing stops with an error

Solutions:

  1. Check that your specification is complete and well-formatted
  2. Try a different AI model (Opus for complex specs)
  3. Simplify the specification if it's very large
  4. Ensure the specification includes endpoint details

Authentication Errors (401)​

Problem: Test returns 401 Unauthorized

Solutions:

  1. Verify credentials are correct
  2. Check if the API key has expired
  3. Ensure the header name matches what the API expects
  4. For OAuth, verify the token URL and client credentials

Connection Timeouts​

Problem: Requests time out

Solutions:

  1. Verify the base URL is correct
  2. Check if the API is accessible from your network
  3. Test the API manually with curl or Postman

Incorrect Response Data​

Problem: Tool returns unexpected data

Solutions:

  1. Review the response data path configuration
  2. Test with the API directly to see actual response format
  3. Adjust JSONPath expressions as needed

Tool Not Appearing in Agent​

Problem: Can't find the tool when configuring an agent

Solutions:

  1. Verify the integration is Active (not disabled)
  2. Check that at least one endpoint is enabled
  3. Refresh the page
  4. Verify you have the settings:write permission

Best Practices​

API Specification Quality​

  • Include clear endpoint descriptions
  • Document all parameters with types and examples
  • Specify authentication requirements
  • Note any rate limits or usage restrictions

Security​

  • Credential Protection - All API credentials are encrypted at rest using AES-256-CBC encryption
  • Automatic Redaction - Sensitive data in logs is automatically redacted before storage
  • Environment Separation - Use environment-specific credentials (dev vs. production)
  • Key Rotation - Regularly rotate API keys and update them in the integration settings
  • Monitoring - Review Integration Logs regularly for unusual activity patterns
  • Least Privilege - Configure API credentials with minimum required permissions
  • Audit Trail - All API calls are logged with full request/response details for compliance

Performance​

  • Be mindful of rate limits
  • Set appropriate timeouts
  • Test with realistic parameter values

Agent Instructions​

Help your agents use API tools effectively:

When looking up customer information:
1. Use the lookup_customer tool with the customer's email
2. If not found, check for typos in the email address
3. Include relevant customer details in your response