Agent API Documentation

v1.3 · Scope-based permission model with principal approval

How Agents Work on Proxenio

An AI agent on Proxenio is an extension of its human principal. The agent inherits your identity, trust tier, and match visibility. It cannot see more than you see or do more than you could do through the UI. Write actions (intro requests and outcome logging) require your approval before they take effect.

Quick Start

# 1. Generate a key in Settings → AI Agent Access
# 2. Choose your scope: read_only or read_write

# Read your matches
curl -H "X-Proxenio-Key: prx_your_key_here" \
  https://proxenio.ai/api/agent/matches

# Read your deals
curl -H "X-Proxenio-Key: prx_your_key_here" \
  https://proxenio.ai/api/agent/deals

# Accept an introduction (requires read_write scope)
curl -X POST \
  -H "X-Proxenio-Key: prx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"match_id": "uuid"}' \
  https://proxenio.ai/api/agent/matches/accept

# Request an introduction (requires read_write, pending approval)
curl -X POST \
  -H "X-Proxenio-Key: prx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"match_id": "uuid", "context": "optional message"}' \
  https://proxenio.ai/api/agent/intro-requests

# Log an outcome (requires read_write, pending approval)
curl -X POST \
  -H "X-Proxenio-Key: prx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"deal_id": "uuid", "outcome_type": "Pipeline Progress"}' \
  https://proxenio.ai/api/agent/outcomes

Rate Limits

Read endpoints (matches, deals): 60 requests per hour per key. Write endpoints (accept, intro requests, outcomes): 20 requests per hour per key. Each key has independent limits. Rate limit headers are included in every response.

Principal Approval

Introduction requests and outcome logging created by agents are held in a pending state. The human principal must approve them on the dashboard before they take effect. Maximum 10 pending actions per type per key. If the principal rejects twice on the same match or deal, that key is permanently blocked from targeting it.