API integration

This guide is designed for developers looking to create a custom AI agent—not tied to a specific platform—that can query and execute tools using Caddey's API via OAuth authentication. Whether you're building a web-based chatbot, a customer support assistant, or an internal automation tool, these steps will help you seamlessly integrate Caddey capabilities into your custom solution.

Prerequisites

• Caddey Account: Ensure you have an active Caddey account.
• Development Environment: Basic familiarity with API integration and OAuth 2.0 flows.

Step 1: Create an OAuth Client

1. Log in to Caddey:
   Visit app.caddey.ai and log into your account.

2. Navigate to the Clients Section:
   From the dashboard, click on the Clients tab.

3. Add a New Client:
   Click Add client, enter the required details (client name and description), choose Public as the client type, and save.

4. Note the Client ID:
   Once the client is created, note the Client ID as it will be needed for OAuth authentication.

Step 2: Configure OAuth Authentication

1. Set up OAuth Configuration:
   In your custom AI agent's configuration, set up OAuth with these parameters:

   • Authorization URL: https://auth.caddey.ai/realms/caddey/protocol/openid-connect/auth
   • Token URL: https://auth.caddey.ai/realms/caddey/protocol/openid-connect/token
   • Client ID: The Client ID from Step 1
   • Client Type: Public (no client secret required)

2. Implement OAuth Flow: Implement the OAuth 2.0 authorization code flow to obtain access tokens for API requests. Your implementation should:

   • Direct users to the authorization URL with your Client ID
   • Handle the callback to receive the authorization code
   • Exchange the authorization code for an access token
   • Store and use the access token for API requests

3. Configure Redirect URI: Add your application's callback URL to the OAuth client's Redirect URIs in Caddey.

4. Import the API Schema: Retrieve the API schema by accessing:
   https://api.caddey.ai/v3/api-docs/tools
   This schema defines key endpoints such as:

   • GET /tools/query – To list available tools.
   • POST /tools/{toolId}/execute – To execute a specific tool with JSON input.

5. Configure Endpoints:
   Set up your custom AI agent to interact with these endpoints, ensuring that all API calls include the OAuth Bearer token in the Authorization header.

Step 3: Test the Integration

1. Query Available Tools:
   • Send a GET request to /tools/query and verify the returned list of tools.
2. Execute a Tool:
   • Select a tool and send a POST request to /tools/{toolId}/execute with the required parameters.
   • Ensure the tool executes successfully and returns the expected output.

Step 4: Finalize and Deploy

1. Review Configurations:
   Double-check all settings and verify that API requests are properly authenticated with OAuth tokens.

2. Deploy Your Assistant:
   Once testing is successful, deploy your custom AI agent with the Caddey integration enabled.

3. Monitor and Update:
   Continuously monitor the integration and update your configurations as necessary.

Additional Resources

• Caddey Support
• Caddey Tools API Reference