ProtonIQ Agent API

The ProtonIQ Agent API allows you to programmatically run AI-powered analysis on your CRM data. Submit prompts, receive structured insights, and integrate ProtonIQ's intelligence into your workflows.

Base URL

https://your-domain.com/api/v1/agent

Quick Start

1. Generate an API key from the Admin Panel
2. Submit a run with your prompt
3. Poll for results (typically 5-30 seconds)

Authentication

All API requests require a Bearer token. API keys can be created and managed in the Admin Panel.

API Key Format

Keys are prefixed with piq_ for easy identification. The full key is only shown once at creation—store it securely.

Header Format

Authorization: Bearer piq_xxxxxxxxxxxxxxxxxxxxx

Rate Limits

Rate limits are enforced per API key to ensure fair usage and system stability. Each API key has its own quota, independent of other keys.

Limits by Endpoint

Rate Limit Response

When a rate limit is exceeded, the API returns HTTP 429 with a structured error and a Retry-After header.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Limit: 5 per 1 minute",
    "retry_after_seconds": 60
  }
}

Handling Rate Limits

When you receive a 429 response, wait for the number of seconds specified in retry_after_seconds before retrying. Implement exponential backoff for robust integrations.

# Check Retry-After header
curl -i https://your-domain.com/api/v1/agent/runs \
  -H "Authorization: Bearer piq_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Test"}' 2>&1 | grep -i retry-after

import requests
import time

def call_with_retry(url, headers, json, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=json)
        
        if response.status_code == 429:
            retry_after = response.json()["error"]["retry_after_seconds"]
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue
        
        return response
    
    raise Exception("Max retries exceeded")

async function callWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const { error } = await response.json();
      console.log(`Rate limited. Waiting ${error.retry_after_seconds}s...`);
      await new Promise(r => setTimeout(r, error.retry_after_seconds * 1000));
      continue;
    }
    
    return response;
  }
  
  throw new Error("Max retries exceeded");
}

Submit a new agent run. The run is processed asynchronously—poll the status endpoint to get results.

Request Body

Example Request

curl -X POST https://your-domain.com/api/v1/agent/runs \
  -H "Authorization: Bearer piq_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What deals are closing this month and what are the risks?",
    "model": "gemini-3-pro"
  }'

import requests

response = requests.post(
    "https://your-domain.com/api/v1/agent/runs",
    headers={"Authorization": "Bearer piq_xxxxx"},
    json={
        "prompt": "What deals are closing this month and what are the risks?",
        "model": "gemini-3-pro"
    }
)
run = response.json()
print(f"Run ID: {run['run_id']}")

const response = await fetch("https://your-domain.com/api/v1/agent/runs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer piq_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "What deals are closing this month and what are the risks?",
    model: "gemini-3-pro"
  })
});
const run = await response.json();
console.log(`Run ID: ${run.run_id}`);

Response

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "created_at": "2026-01-14T12:00:00Z"
}

Retrieve the status and results of a run. Poll this endpoint until status is completed or failed.

Path Parameters

Query Parameters

Example Request

curl "https://your-domain.com/api/v1/agent/runs/550e8400-e29b-41d4-a716-446655440000?response_detail=full_trace" \
  -H "Authorization: Bearer piq_xxxxx"

import requests
import time

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

# Poll until complete
while True:
    response = requests.get(
        f"https://your-domain.com/api/v1/agent/runs/{run_id}",
        headers={"Authorization": "Bearer piq_xxxxx"},
        params={"response_detail": "full_trace"}
    )
    run = response.json()
    
    if run["status"] in ("completed", "failed"):
        break
    
    time.sleep(2)  # Poll every 2 seconds

print(run["result"])

const runId = "550e8400-e29b-41d4-a716-446655440000";

// Poll until complete
async function pollRun() {
  while (true) {
    const response = await fetch(
      `https://your-domain.com/api/v1/agent/runs/${runId}?response_detail=full_trace`,
      { headers: { "Authorization": "Bearer piq_xxxxx" } }
    );
    const run = await response.json();
    
    if (run.status === "completed" || run.status === "failed") {
      return run;
    }
    
    await new Promise(r => setTimeout(r, 2000)); // Poll every 2s
  }
}

const result = await pollRun();
console.log(result.result);

Run Status Values

Response (Completed)

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "prompt": "What deals are closing this month?",
  "model": "gemini-3-pro",
  "result": "Based on your pipeline, there are 5 deals expected to close this month...",
  "structured_output": null,
  "tool_calls": [
    {"tool": "search_deals", "summary": "Found 5 deals closing in January"},
    {"tool": "get_deal_details", "summary": "Retrieved details for Acme Corp deal"}
  ],
  "usage": {
    "input_tokens": 1250,
    "output_tokens": 890,
    "duration_ms": 12500
  },
  "created_at": "2026-01-14T12:00:00Z",
  "started_at": "2026-01-14T12:00:01Z",
  "completed_at": "2026-01-14T12:00:14Z"
}

Response Detail Levels

List available models for agent runs.

Example Request

curl https://your-domain.com/api/v1/agent/models \
  -H "Authorization: Bearer piq_xxxxx"

import requests

response = requests.get(
    "https://your-domain.com/api/v1/agent/models",
    headers={"Authorization": "Bearer piq_xxxxx"}
)
models = response.json()["models"]

for model in models:
    print(f"{model['id']}: {model['name']}")

const response = await fetch("https://your-domain.com/api/v1/agent/models", {
  headers: { "Authorization": "Bearer piq_xxxxx" }
});
const { models } = await response.json();

models.forEach(m => console.log(`${m.id}: ${m.name}`));

Available Models

Models are loaded dynamically. This list updates automatically.

Error Codes

The API uses standard HTTP status codes. Errors include a JSON body with details.

Error Response Format

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked."
  }
}

Common Error Codes