Custom API

Custom API actions let your agent interact with external services. Fetch real-time data, submit forms, or trigger workflows in other tools.

Creating a Custom API Action

1. Go to your agent's Actions tab
2. Click Add Action → Custom API
3. Configure the API call:
   • Endpoint URL - The API endpoint to call
   • HTTP Method - GET, POST, PUT, PATCH, or DELETE
   • Headers - Authentication and content-type
   • Request Body - Data to send (for POST/PUT/PATCH)
4. Save and test

Configuration Options

Endpoint URL

The full URL of the API endpoint:

https://api.yourservice.com/v1/data

Use HTTPS endpoints only. HTTP endpoints are blocked for security.

HTTP Method

Headers

Add authentication and content headers:

Authorization: Bearer {{SECRET:service_api_key}}
Content-Type: application/json

Create the named secret separately. Agentkit resolves {{SECRET:name}} only on the server. Action reads and logs never include the stored value.

Data input source

Most inputs come from the conversation. For a scalar text input that represents an email address, you can choose Verified email, ask if unavailable. Agentkit then uses the verified web contact or inbound email sender. Anonymous web visitors are asked for the value. A value written by the model cannot replace a verified address.

Request Body

For POST/PUT requests, define the JSON body with the data you want to send.

When the API is Called

The AI decides when to call the API based on conversation context and the action's description. You can guide this behavior by providing a clear description of when the action should be triggered.

Handling Responses

Success Response

When the API returns successfully (2xx status):

• Display a success message to the visitor
• Include response data in the chat
• Trigger follow-up actions

Error Handling

When the API fails:

• Display a friendly error message
• Log the error for debugging
• Optionally retry the request

Example Use Cases

Check Order Status

Configure a GET endpoint to fetch order data when visitors ask about their order status.

Submit to CRM

Configure a POST endpoint to send lead data to your CRM system.

Get Real-Time Data

Configure a GET endpoint to fetch real-time data (like availability or inventory) from your systems.

Security Considerations

API Keys

• Store API keys as named secrets and reference them with {{SECRET:name}}
• Use environment-specific keys for testing
• Rotate keys periodically

Rate Limiting

• External APIs may have rate limits
• Configure your agent's rate limiting accordingly
• Monitor API usage in logs

Data Privacy

• Only send necessary data
• Ensure external services are GDPR-compliant if needed
• Don't log sensitive response data

Timeout and Retries

Testing Your API Action

1. Set up the action with a test endpoint
2. Go to Playground
3. Trigger the action with appropriate input
4. Check the response in chat
5. Review logs for debugging

Next Steps

• Set up webhooks for reliable delivery
• Connect to Zapier for no-code integrations
• View API documentation for incoming API calls