cURL Examples¶

Command-line examples using cURL for testing and scripting.

Setup¶

Environment Variables¶

export AG2TRUST_API_KEY="cust_your_api_key_here"
export AG2TRUST_BASE_URL="https://agents.ag2trust.com"

Basic Operations¶

Send Message to Pool¶

curl -X POST "${AG2TRUST_BASE_URL}/api/v1/ask/support" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, I need help with my order"}'

Response:

{
  "thread_id": "thread_abc123",
  "agent_id": "uuid",
  "content": "Hello! I'd be happy to help you with your order. Could you provide your order number?",
  "timestamp": "2025-01-15T10:30:00Z"
}

Continue Conversation¶

curl -X POST "${AG2TRUST_BASE_URL}/api/v1/ask/support" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "thread_abc123",
    "content": "My order number is 12345"
  }'

Send to Specific Agent¶

AGENT_ID="550e8400-e29b-41d4-a716-446655440000"

curl -X POST "${AG2TRUST_BASE_URL}/api/v1/agents/${AGENT_ID}/messages" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, what can you help me with?"}'

Response:

{
  "message_id": "msg_xyz789",
  "content": [
    {
      "type": "text",
      "text": "I can help you with product questions, billing inquiries, and technical support."
    }
  ],
  "metadata": {
    "tokens_used": 45,
    "model": "gpt-4o",
    "duration_ms": 1250
  }
}

Agent Management¶

List Agents¶

curl -X GET "${AG2TRUST_BASE_URL}/api/v1/agents" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}"

Response:

{
  "agents": [
    {
      "agent_id": "uuid-1",
      "name": "support-agent-1",
      "status": "running",
      "capabilities": ["web_http"]
    },
    {
      "agent_id": "uuid-2",
      "name": "support-agent-2",
      "status": "running",
      "capabilities": ["web_http"]
    }
  ]
}

Get Usage Statistics¶

curl -X GET "${AG2TRUST_BASE_URL}/api/v1/usage?period=day" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}"

Response:

{
  "period": "day",
  "requests": 150,
  "tokens_used": 45000,
  "rate_limit": 60,
  "rate_limit_remaining": 45,
  "rate_limit_reset": "2025-01-15T10:31:00Z"
}

Webhook Operations¶

Set Default Webhook¶

curl -X PUT "${AG2TRUST_BASE_URL}/api/v1/webhook" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://your-server.com/webhooks/ag2trust"}'

Test Webhook¶

curl -X POST "${AG2TRUST_BASE_URL}/api/v1/webhook/test" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://your-server.com/webhooks/ag2trust"}'

Response:

{
  "success": true,
  "status_code": 200,
  "latency_ms": 150
}

Send Async Message¶

AGENT_ID="550e8400-e29b-41d4-a716-446655440000"

curl -X POST "${AG2TRUST_BASE_URL}/api/v1/agents/${AGENT_ID}/messages" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analyze this large dataset and provide insights...",
    "webhook_url": "https://your-server.com/webhooks/ag2trust"
  }'

Response (immediate):

{
  "callback_id": "cb_xyz789",
  "status": "processing",
  "agent_id": "uuid",
  "timestamp": "2025-01-15T10:30:00Z"
}

Shell Scripts¶

Conversation Script¶

#!/bin/bash
# chat.sh - Interactive chat script

API_KEY="${AG2TRUST_API_KEY}"
BASE_URL="${AG2TRUST_BASE_URL:-https://agents.ag2trust.com}"
ENDPOINT="${1:-support}"
THREAD_ID=""

send_message() {
    local content="$1"
    local payload

    if [ -n "$THREAD_ID" ]; then
        payload=$(jq -n --arg c "$content" --arg t "$THREAD_ID" \
            '{content: $c, thread_id: $t}')
    else
        payload=$(jq -n --arg c "$content" '{content: $c}')
    fi

    response=$(curl -s -X POST "${BASE_URL}/api/v1/ask/${ENDPOINT}" \
        -H "X-API-Key: ${API_KEY}" \
        -H "Content-Type: application/json" \
        -d "$payload")

    THREAD_ID=$(echo "$response" | jq -r '.thread_id')
    echo "$response" | jq -r '.content'
}

echo "Chat started. Type 'quit' to exit."
while true; do
    read -p "You: " input
    [ "$input" = "quit" ] && break
    echo -n "Agent: "
    send_message "$input"
    echo
done

Usage:

chmod +x chat.sh
./chat.sh support

Retry Script¶

#!/bin/bash
# send_with_retry.sh - Send message with retry logic

API_KEY="${AG2TRUST_API_KEY}"
BASE_URL="${AG2TRUST_BASE_URL:-https://agents.ag2trust.com}"
MAX_RETRIES=3

send_with_retry() {
    local content="$1"
    local endpoint="${2:-support}"
    local attempt=0

    while [ $attempt -lt $MAX_RETRIES ]; do
        response=$(curl -s -w "\n%{http_code}" -X POST \
            "${BASE_URL}/api/v1/ask/${endpoint}" \
            -H "X-API-Key: ${API_KEY}" \
            -H "Content-Type: application/json" \
            -d "{\"content\": \"$content\"}")

        http_code=$(echo "$response" | tail -n1)
        body=$(echo "$response" | sed '$d')

        if [ "$http_code" = "200" ]; then
            echo "$body"
            return 0
        elif [ "$http_code" = "429" ]; then
            retry_after=$(echo "$body" | jq -r '.details.retry_after // 5')
            echo "Rate limited, waiting ${retry_after}s..." >&2
            sleep "$retry_after"
            ((attempt++))
        else
            echo "Error: HTTP $http_code" >&2
            echo "$body" >&2
            return 1
        fi
    done

    echo "Max retries exceeded" >&2
    return 1
}

# Usage
send_with_retry "Hello, I need help" "support"

Batch Processing Script¶

#!/bin/bash
# batch_process.sh - Process multiple messages from file

API_KEY="${AG2TRUST_API_KEY}"
BASE_URL="${AG2TRUST_BASE_URL:-https://agents.ag2trust.com}"
INPUT_FILE="${1:-messages.txt}"
OUTPUT_FILE="${2:-responses.json}"

echo "[" > "$OUTPUT_FILE"
first=true

while IFS= read -r message; do
    [ -z "$message" ] && continue

    response=$(curl -s -X POST "${BASE_URL}/api/v1/ask/support" \
        -H "X-API-Key: ${API_KEY}" \
        -H "Content-Type: application/json" \
        -d "{\"content\": \"$message\"}")

    if [ "$first" = true ]; then
        first=false
    else
        echo "," >> "$OUTPUT_FILE"
    fi

    echo "$response" >> "$OUTPUT_FILE"

    # Rate limit protection
    sleep 1
done < "$INPUT_FILE"

echo "]" >> "$OUTPUT_FILE"
echo "Processed $(wc -l < "$INPUT_FILE") messages"

Debugging¶

Verbose Output¶

curl -v -X POST "${AG2TRUST_BASE_URL}/api/v1/ask/support" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello"}'

Check Rate Limit Headers¶

curl -s -D - -X POST "${AG2TRUST_BASE_URL}/api/v1/ask/support" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello"}' \
  | grep -i "x-ratelimit"

Output:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1700308800

Timing Request¶

time curl -s -X POST "${AG2TRUST_BASE_URL}/api/v1/ask/support" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello"}' \
  > /dev/null

Pretty Print JSON¶

curl -s -X POST "${AG2TRUST_BASE_URL}/api/v1/ask/support" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello"}' \
  | jq .

Common Patterns¶

Extract Response Content¶

# Pool endpoint
curl -s ... | jq -r '.content'

# Agent endpoint
curl -s ... | jq -r '.content[] | select(.type=="text") | .text'

Check Agent Status¶

curl -s "${AG2TRUST_BASE_URL}/api/v1/agents" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}" \
  | jq '.agents[] | {name, status}'

Filter Running Agents¶

curl -s "${AG2TRUST_BASE_URL}/api/v1/agents" \
  -H "X-API-Key: ${AG2TRUST_API_KEY}" \
  | jq '[.agents[] | select(.status=="running")]'

Error Handling¶

Check for Errors¶

response=$(curl -s -w "\n%{http_code}" ...)
http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')

case $http_code in
    200) echo "Success: $body" ;;
    401) echo "Error: Invalid API key" ;;
    429) echo "Error: Rate limited" ;;
    503) echo "Error: No agents available" ;;
    *)   echo "Error: HTTP $http_code - $body" ;;
esac