Agent API Documentation

API for AI agents to access their principal's verified professional matches and accept introductions on Proxenio.

Authentication

Every request requires an API key in the header. Keys are generated by verified human users on the Agents page.

X-Proxenio-Key: prx_<your_key>

Keys are scoped to read_only. Agents can read matches and accept introduction requests on behalf of their principal.

Read Matches

GEThttps://proxenio.ai/api/agent/matches

Returns all matches for the principal, sorted by match score descending. Minimum score: 40.

GET Request

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

GET Response

{
  "principal": {
    "id": "uuid",
    "name": "Antony C.",
    "trust_tier": 3,
    "pro_score": 22
  },
  "matches": [
    {
      "match_id": "uuid",
      "status": "pending",
      "match_score": 78,
      "match_type": "strong",
      "created_at": "2026-02-18T06:00:00Z",
      "counterparty": {
        "id": "uuid",
        "name": "Maria K.",
        "role": "CFO",
        "industry": "Fintech",
        "location": "Limassol",
        "company": "PayCo",
        "intent_type": "Raise Funds",
        "intent_description": "Series A for payments platform",
        "trust_tier": 2,
        "pro_score": 15,
        "is_verified": true,
        "confirmed_outcomes": 3
      }
    }
  ],
  "meta": {
    "agent": "My Agent",
    "scope": "read_only",
    "total_matches": 1,
    "requests_remaining": 58,
    "timestamp": "2026-02-18T09:00:00Z"
  }
}

Accept Introduction

POSThttps://proxenio.ai/api/agent/matches/accept

Accept an introduction request on behalf of the principal. The principal must be the receiving party (user_b). Creates a deal upon success.

POST Request

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

POST Response

{
  "success": true,
  "action": "accepted",
  "match": {
    "match_id": "uuid",
    "status": "accepted",
    "counterparty": {
      "id": "uuid",
      "name": "Maria K.",
      "role": "CFO",
      "industry": "Fintech"
    }
  },
  "deal_id": "uuid",
  "meta": {
    "agent": "My Agent",
    "principal_id": "uuid",
    "timestamp": "2026-02-18T09:05:00Z"
  }
}

Accept Guard Rails

400	match_id is required	Missing match_id in request body.
400	Match status is [X]	Match must be in active status to accept.
400	No introduction request found	No intro request exists for this match.
400	Intro request is [X]	Intro must be pending or awaiting_consent.
403	Not a participant	Principal is not a participant in this match.
403	Cannot accept own request	Agent cannot accept on behalf of the requester.
403	Not authorized	Principal must be user_b (the receiving party).
404	Match not found	No match exists with this ID.

Response Fields

principal.trust_tier	0–4	Human's verified trust level. Agent inherits this.
principal.pro_score	0–100	Behavioral score based on confirmed outcomes.
matches[].match_score	40–100	Engine-computed match quality. Below 40 is hidden.
matches[].match_type	premium \| strong \| regular	Score bracket classification.
matches[].status	pending \| accepted	Match lifecycle state.
counterparty.trust_tier	0–4	Counterparty's verified trust level.
counterparty.confirmed_outcomes	integer	Number of counterparty-confirmed deal outcomes.
counterparty.is_verified	boolean	Email verification status.
meta.scope	read_only	Current permission level of the API key.
meta.requests_remaining	integer	Requests left in current hourly window.

Error Codes

401	Unauthorized	Missing, invalid, or revoked API key.
404	Not Found	Principal profile or match not found.
429	Rate Limited	60 requests/hour exceeded. Check X-RateLimit-Reset header.
500	Server Error	Internal error. Retry.

Trust Rules for Agents

→Every agent must be linked to a verified human principal.

→Agent inherits the principal's trust tier — cannot exceed it.

→Same engine rules apply — no bypassing skip layers or tier gates.

→The human principal is accountable for all agent actions.

→Counterparties always see "Represented by AI Agent on behalf of [Human]".

→Humans confirm outcomes, not agents.

Rate Limits

During alpha: 60 requests/hour per API key. GET and POST share the same counter. Each key has an independent counter — 3 keys = 180 requests/hour total.

Rate limit headers are included in every response:

X-RateLimit-Limit	60	Maximum requests per hour.
X-RateLimit-Remaining	integer	Requests left in current window.
X-RateLimit-Reset	ISO timestamp	When the current window resets.

Key Management

Generate, view, and revoke keys on the Agents page.

→Maximum 3 active keys per user.

→Keys are shown once at generation — save immediately.

→Revoked keys lose access instantly.

→Key prefix (prx_xxxx...) is visible for identification.