API Reference

Complete reference for all VerifiedProxy API endpoints. Base URL: https://app.verifiedproxy.com

Authentication

Protected endpoints use Bearer token authentication. Include your credential in the Authorization header:

Authorization: Bearer <your_key_or_secret>

Register Agent

Create a new agent under your organization.

Headers

• Authorization Required Bearer token with your organization API key
• Content-Type Required application/json

Request Body

• name string Required Human-readable agent name
• scopes string[] Required Array of scope strings (e.g., ["browse", "data-collect"])

Example

curl -X POST https://app.verifiedproxy.com/api/agents/register \
  -H "Authorization: Bearer vp_sk_live_a1b2c3d4e5f6a7b8..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Research Bot",
    "scopes": ["browse", "data-collect"]
  }'

Response

{
  "agent_id": "ag_a1b2c3d4",
  "agent_secret": "vp_ag_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
  "name": "Acme Research Bot",
  "scopes": ["browse", "data-collect"]
}

{
  "error": "Invalid API key"
}

Create Session

Announce a visit to a target domain and create a verification session.

Headers

• Authorization Required Bearer token with your agent secret
• Content-Type Required application/json

Request Body

• target_url string Required The URL the agent intends to visit (e.g., https://example.com)
• action string Optional Description of what the agent will do (e.g., "browse", "data-collect")
• metadata object Optional Arbitrary JSON metadata attached to the session

Example

curl -X POST https://app.verifiedproxy.com/api/agents/sessions \
  -H "Authorization: Bearer vp_ag_your_agent_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://example.com",
    "action": "browse",
    "metadata": {"purpose": "product research"}
  }'

Response

{
  "session_id": "ses_e5f6a7b8",
  "agent_id": "ag_a1b2c3d4",
  "target_url": "https://example.com",
  "expires_at": "2026-03-06T12:10:00Z",
  "visit_url": "https://example.com?vp_agent=ag_a1b2c3d4&vp_session=ses_e5f6a7b8"
}

{
  "error": "Invalid agent secret"
}

Verify Agent

Public endpoint for websites to verify an agent's identity and session. No authentication required.

Query Parameters

• agent_id string Required The agent ID from the X-VP-Agent-Id header
• session string Required The session ID from the X-VP-Session header
• url string Optional Your website URL to verify the session was created for your domain

Example

curl "https://app.verifiedproxy.com/api/agents/verify?agent_id=ag_a1b2c3d4&session=ses_e5f6a7b8"

Response (Verified)

{
  "verified": true,
  "agent": {
    "id": "ag_a1b2c3d4",
    "name": "Acme Research Bot",
    "org_name": "Acme Corp",
    "scopes": ["browse", "data-collect"]
  },
  "session": {
    "id": "ses_e5f6a7b8",
    "action": "browse",
    "expires_at": "2026-03-06T12:10:00Z"
  }
}

Response (Not Verified)

{
  "verified": false,
  "reason": "Session expired"
}

Get Agent Profile

Public endpoint to look up an agent's profile. No authentication required.

Path Parameters

• agent_id string Required The agent's unique identifier (e.g., ag_a1b2c3d4)

Example

curl https://app.verifiedproxy.com/api/agents/ag_a1b2c3d4

Response

{
  "agent_id": "ag_a1b2c3d4",
  "name": "Acme Research Bot",
  "org_name": "Acme Corp",
  "scopes": ["browse", "data-collect"],
  "status": "active"
}

{
  "error": "Agent not found"
}

Error Responses

All error responses follow a consistent format:

{
  "error": "Human-readable error message"
}

Rate Limits

Currently there are no enforced rate limits. We recommend keeping session creation to a reasonable frequency (the proxy handles this automatically with 8-minute caching).