API Reference: Endpoints & Request Structure

Overview

The Kambrium API allows you to interact with Large Language Models (LLMs) to retrieve data, generate insights, or take actions within your connected SaaS applications. This section details the available endpoint, including request format, response structure, and best practices.

1. Endpoint: Create an AI-Driven Action

Endpoint URL

POST https://agent-api.kambrium.ai/api/v1/run-agent

Purpose

This endpoint processes a natural language prompt to execute actions within your integrated SaaS platforms or retrieve structured data insights. The AI interprets the request, triggers necessary SaaS integrations, and returns a structured response.

Request Format

Headers

{
    "Content-Type": "application/json"
}

Body Parameters

api_key: string(required) Your authentication key.

prompt: string (required): Natural language instruction for the AI.

Example Request (Python)

import requests

# Set API Key and Prompt
api_key = "YOUR_API_KEY"

# Define the Prompt
prompt = """Create a new lead for Peter Walker, CFO at AMC Inc.
He's interested in purchasing our Quantum Analytics Suite.
Enrich company data, set next step to send proposal by Thursday.
Create a reminder for Tuesday 13th to follow up."""

# Send API Request
response = requests.post(
    "https://agent-api.kambrium.ai/api/v1/run-agent",
    headers={"Content-Type": "application/json"},
    json={
        "api_key": api_key,
        "prompt": prompt
    }
)

# Handle Response
if response.status_code == 201:
    print("Action created successfully.")
    print("Response:", response.json())
else:
    print(f"Error: {response.status_code}")
    print("Response:", response.text)

2. Response Structure

A successful request returns a structured JSON response.

Example Response (201 Created)

{
    "run_id": "kjsfaga82hg91gkajsdghg81",
    "prompt": "Create a new lead for Peter Walker, CFO at AMC Inc.",
    "result": "Lead created successfully in Pipedrive with follow-up reminder set.",
    "time_needed": 2.43,
    "tokens_usage": 120,
    "status": "success"
}

Response Fields

run_id: string A unique identifier for this request.

prompt:string The original prompt sent in the request.

result:string The outcome of the request (e.g., confirmation message).

time_needed:float Time taken (in seconds) to process the request.

tokens_usage:int Number of tokens consumed for this request.

status:string Status of the request (success or failed).

3. Error Handling

If the request fails, the API returns an error message along with an appropriate HTTP status code.

Example Error Response

{
    "status": "error",
    "message": "Invalid API key."
}

Common Errors & Fixes

400 Bad Request: Invalid request format: Check JSON structure

401 Unauthorized: Missing or incorrect API key: Verify API key in payload

500 Internal Server Error: Kambrium API is down or experiencing issues: Retry later or contact support

4. Best Practices for API Usage

• Use Clear, Concise Prompts

  • Example: "Retrieve the latest deal updates from Salesforce for John Doe."

  • Avoid vague prompts like: "Get me some sales data."

• Monitor Token Usage

  • Each request consumes tokens based on prompt complexity.

  • Track usage in your Kambrium Dashboard to optimize efficiency.

• Handle API Rate Limits

  • Ensure your system can handle errors gracefully in case of API throttling.

  • Implement exponential backoff when retrying failed requests.

• Secure Your API Key

  • Never expose your API key in client-side code.

  • Store it securely in environment variables or secret management tools.