Connecting APIs

Connect external APIs to bring live data into your automations. This guide covers setting up connections, authentication, and best practices.

Overview

API connections allow you to:

• Fetch data from external services during automation execution
• Enrich your datasets with third-party data
• Send results to external systems
• Build custom integrations with your existing tools

Connection Types

Built-in Integrations

Pre-configured integrations with optimized settings:

Custom HTTP Connections

Connect to any REST API using the HTTP Request node:

• Full control over request configuration
• Support for any HTTP method
• Custom headers and authentication
• Response parsing and mapping

Setting Up Connections

MCP Connections

The Model Context Protocol (MCP) allows you to connect to compatible services:

1. Open Integrations in the sidebar and choose the Platforms tab
2. Under Your Platforms, click Add Connection
3. Name the connection and enter its Server URL
4. Choose an Authentication method and add credentials if required
5. Leave Test connection before saving checked to verify the server
6. Click Add Connection

Once connected, available tools appear in your automation sidebar.

API Keys

For services requiring API keys:

1. Go to Settings > API keys
2. Click Create API Key
3. Name your key (e.g., "Production Automation Key")
4. Set expiration (optional)
5. Copy and securely store the key - it's only shown once

Key management:

• Revoke keys immediately if compromised
• Use different keys for different environments
• Monitor usage in the API Keys dashboard

Authentication Methods

No Authentication

Some public APIs don't require authentication:

GET https://api.example.com/public/data

API Key in Header

Most common method for SaaS APIs:

GET https://api.example.com/data
Authorization: Bearer YOUR_API_KEY

Or custom header:

GET https://api.example.com/data
X-API-Key: YOUR_API_KEY

API Key in Query String

Some services accept keys as URL parameters:

GET https://api.example.com/data?api_key=YOUR_API_KEY

Basic Authentication

Username and password combination:

GET https://api.example.com/data
Authorization: Basic base64(username:password)

Using API Data in Automations

HTTP Request Node

1. Add an HTTP Request node to your automation

2. Configure the request:

   • URL: API endpoint (can include dynamic values from input)
   • Method: GET, POST, PUT, DELETE
   • Headers: Authentication and content type
   • Body: Request payload (for POST/PUT)

3. Map the response:

   • Select which response fields to extract
   • Map them to output columns

Example: Enriching Records

[Your Data] → [HTTP Request] → [Output]
                    ↓
           For each record:
           GET /api/company/{id}
                    ↓
           Add company name, revenue

Rate Limiting and Retries

The HTTP Request node retries transient failures (5xx responses and timeouts) with exponential backoff. If the upstream API returns 429, that is treated as a transient error and retried with backoff as well.

External APIs have their own rate limits — when you process many records, space out or batch your requests to stay within the provider's limits.

Usage and Credits

Cesteral Intelligence meters work in credits: 1 credit is 1 action (an external API call, LLM query, census query, geocode, and so on). Your plan determines your monthly credit allowance and other limits (such as seats, projects, storage, and knowledge bases). Enterprise plans can have unlimited credits. Check your current usage and limits in the workspace billing settings.

Error Handling

Common HTTP Errors

Automation Behavior

When an API request fails:

• Single record: That record is marked with error status
• Batch fails: Partial results are preserved
• Retry logic: Transient errors trigger automatic retries

Best Practices

Security

• Never hardcode API keys in URLs or visible fields
• Use the secure credential storage
• Rotate keys periodically
• Use keys with minimal required permissions

Performance

• Cache responses when data doesn't change frequently
• Batch requests where possible
• Filter data before making API calls

Reliability

• Test connections before running production automations
• Monitor for API deprecation notices
• Have fallback handling for API outages
• Log API responses for debugging

Troubleshooting

Connection Test Fails

• Verify the URL is correct and accessible
• Check firewall rules for outbound connections
• Ensure credentials are valid and not expired

Slow API Responses

• Check if the external service is experiencing issues
• Consider if you're hitting rate limits
• Try smaller batch sizes

Data Not Mapping Correctly

• Verify response format matches expectations
• Check for nested JSON structures
• Ensure field names are exact matches