Skip to main content

​
Overview

Agents are lightweight clients that run in your infrastructure to expose services and enable connectivity. The Agents API provides endpoints for registration, heartbeat monitoring, capability management, and agent-to-agent messaging.

​
Provision Agent Token

Create a short-lived agent token programmatically. Used by AI agent runtimes to get workspace access without the device authorization flow. 
curl -X POST https://api.privateconnect.co/v1/agents/provision \
  -H "x-api-key: pc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "clientType": "cursor",
    "label": "staging",
    "name": "cursor-agent-1",
    "ttlSeconds": 7200
  }'
Request Body:
​
clientType
string
required
The tool requesting access. Valid values: cursor, windsurf, copilot, cline, aider, continue, bolt, v0, replit, custom
​
label
string
Environment label (e.g., production, staging). Max 100 characters.
​
name
string
Agent name (e.g., cursor-agent-1). Max 100 characters.
​
ttlSeconds
number
Token lifetime in seconds. Min: 60, Max: 86400, Default: 7200 (2 hours)
Response: 
{
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "token": "agent_tok_1234567890abcdefghijklmnop",
  "expiresAt": "2026-03-02T12:00:00.000Z",
  "workspaceId": "ws_123",
  "workspaceName": "my-workspace"
}
Save the token value - it cannot be retrieved later. The token expires after ttlSeconds.

​
Register Agent

Register a new agent in the workspace with a pre-generated token. 
curl -X POST https://api.privateconnect.co/v1/agents/register \
  -H "x-api-key: pc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "token": "agent_tok_1234567890abcdefghijklmnop",
    "label": "production",
    "name": "web-server-1"
  }'
Request Body:
​
agentId
string
required
UUID for the agent
​
token
string
required
Agent authentication token (min 32 characters)
​
label
string
Environment label
​
name
string
Agent display name
Response: 
{
  "success": true,
  "agent": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "web-server-1",
    "label": "production",
    "workspaceId": "ws_123",
    "createdAt": "2026-03-02T10:00:00.000Z"
  }
}

​
Agent Heartbeat

Update agent last-seen timestamp. Called periodically by connected agents to maintain online status. 
curl -X POST https://api.privateconnect.co/v1/agents/heartbeat \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "token": "agent_tok_1234567890abcdefghijklmnop"
  }'
Request Body:
​
agentId
string
required
Agent UUID
​
token
string
required
Agent token
Response: 
{
  "success": true
}

​
List Agents

Retrieve all agents in the workspace. 
curl https://api.privateconnect.co/v1/agents \
  -H "x-api-key: pc_your_api_key"
Response: 
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "web-server-1",
    "label": "production",
    "isOnline": true,
    "lastSeenAt": "2026-03-02T10:00:00.000Z",
    "createdAt": "2026-03-01T10:00:00.000Z"
  }
]

​
List Online Agents

Retrieve only currently online agents. 
curl https://api.privateconnect.co/v1/agents/online \
  -H "x-api-key: pc_your_api_key"

​
Get Agent Details

Retrieve details for a specific agent. 
curl https://api.privateconnect.co/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: pc_your_api_key"
Response: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "web-server-1",
  "label": "production",
  "workspaceId": "ws_123",
  "isOnline": true,
  "lastSeenAt": "2026-03-02T10:00:00.000Z",
  "createdAt": "2026-03-01T10:00:00.000Z",
  "capabilities": [
    {
      "name": "gpu",
      "metadata": { "model": "A100" }
    }
  ],
  "services": []
}

​
Rotate Agent Token

Generate a new token for an agent. The current valid token must be provided. 
curl -X POST https://api.privateconnect.co/v1/agents/rotate-token \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "currentToken": "agent_tok_old_token"
  }'
Request Body:
​
agentId
string
required
Agent UUID
​
currentToken
string
required
Current valid token
Response: 
{
  "success": true,
  "newToken": "agent_tok_new_token_here",
  "expiresAt": "2026-03-03T10:00:00.000Z"
}

​
Capability Management

​
Register Capabilities

Register capabilities for an agent (e.g., GPU, high-memory, specific tools). 
curl -X POST https://api.privateconnect.co/v1/agents/550e8400-e29b-41d4-a716-446655440000/capabilities \
  -H "x-api-key: pc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": [
      {
        "name": "gpu",
        "metadata": { "model": "A100", "vram": "80GB" }
      },
      {
        "name": "high-memory",
        "metadata": { "ram": "256GB" }
      }
    ]
  }'
Request Body:
​
capabilities
array
required
Array of capability objects

​
Find Agents by Capability

Find agents that have a specific capability. 
curl https://api.privateconnect.co/v1/agents/by-capability/gpu \
  -H "x-api-key: pc_your_api_key"
Response: 
{
  "agents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "gpu-worker-1",
      "isOnline": true,
      "capability": {
        "name": "gpu",
        "metadata": { "model": "A100" }
      }
    }
  ]
}

​
Agent Orchestration

​
Get Orchestration View

Retrieve all agents with their capabilities and services for orchestration. 
curl https://api.privateconnect.co/v1/agents/orchestration \
  -H "x-api-key: pc_your_api_key"
Response: 
{
  "agents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "web-server-1",
      "label": "production",
      "isOnline": true,
      "lastSeenAt": "2026-03-02T10:00:00.000Z",
      "capabilities": [
        { "name": "gpu", "metadata": { "model": "A100" } }
      ],
      "services": [
        {
          "id": "svc_123",
          "name": "prod-db",
          "targetPort": 5432,
          "status": "active"
        }
      ]
    }
  ]
}

​
Agent Messaging

​
Send Message to Agent

Send a message from one agent to another. 
curl -X POST https://api.privateconnect.co/v1/agents/550e8400-e29b-41d4-a716-446655440000/messages/send \
  -H "x-api-key: pc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "toAgentId": "660e8400-e29b-41d4-a716-446655440001",
    "payload": { "action": "process", "data": "example" },
    "channel": "tasks",
    "type": "request",
    "ttlSeconds": 300
  }'
Request Body:
​
toAgentId
string
required
Target agent UUID
​
payload
object
required
Message payload (any JSON object)
​
channel
string
Message channel (for filtering)
​
type
string
Message type: request, response, event, broadcast
​
correlationId
string
Correlation ID for request/response matching
​
ttlSeconds
number
Message time-to-live in seconds
Response: 
{
  "success": true,
  "messageId": "msg_123",
  "expiresAt": "2026-03-02T10:05:00.000Z"
}

​
Broadcast Message

Broadcast a message to all agents in the workspace. 
curl -X POST https://api.privateconnect.co/v1/agents/550e8400-e29b-41d4-a716-446655440000/messages/broadcast \
  -H "x-api-key: pc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": { "announcement": "maintenance in 1 hour" },
    "channel": "system",
    "ttlSeconds": 3600
  }'

​
Get Agent Messages

Retrieve messages for an agent with optional filtering. 
curl "https://api.privateconnect.co/v1/agents/550e8400-e29b-41d4-a716-446655440000/messages?channel=tasks&unreadOnly=true&limit=50" \
  -H "x-api-key: pc_your_api_key"
Query Parameters:
​
channel
string
Filter by channel
​
unreadOnly
boolean
Only return unread messages (default: true)
​
limit
number
Limit number of messages returned
Response: 
{
  "messages": [
    {
      "id": "msg_123",
      "from": "660e8400-e29b-41d4-a716-446655440001",
      "channel": "tasks",
      "type": "request",
      "payload": { "action": "process", "data": "example" },
      "correlationId": "req_456",
      "createdAt": "2026-03-02T10:00:00.000Z",
      "readAt": null
    }
  ]
}

​
Mark Messages as Read

Mark specific messages as read. 
curl -X POST https://api.privateconnect.co/v1/agents/550e8400-e29b-41d4-a716-446655440000/messages/read \
  -H "x-api-key: pc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messageIds": ["msg_123", "msg_124"]
  }'

​
Remote Commands

​
Send Command to Agent

Send a command to an agent for remote control. 
curl -X POST https://api.privateconnect.co/v1/agents/550e8400-e29b-41d4-a716-446655440000/command \
  -H "x-api-key: pc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "expose",
    "params": {
      "target": "localhost:5432",
      "name": "prod-db",
      "protocol": "tcp"
    }
  }'
Request Body:
​
action
string
required
Command action: restart, stop, expose, reach, status
​
params
object
Action-specific parameters
Response: 
{
  "success": true,
  "commandId": "cmd_123",
  "message": "Command 'expose' sent to agent",
  "agentOnline": true
}
If the agent is offline, the command is queued for delivery when the agent reconnects.

​
Audit Logs

​
Get Agent Audit Logs

Retrieve security audit logs for a specific agent. 
curl https://api.privateconnect.co/v1/agents/550e8400-e29b-41d4-a716-446655440000/audit-logs \
  -H "x-api-key: pc_your_api_key"
Response: 
{
  "logs": [
    {
      "id": "log_123",
      "action": "token_rotated",
      "timestamp": "2026-03-02T10:00:00.000Z",
      "metadata": { "oldTokenPrefix": "agent_tok_old" }
    }
  ]
}

​
Get Agents with Expiring Tokens

Retrieve agents whose tokens will expire soon. 
curl https://api.privateconnect.co/v1/agents/expiring-tokens \
  -H "x-api-key: pc_your_api_key"
Response: 
{
  "agents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "web-server-1",
      "tokenExpiresAt": "2026-03-02T12:00:00.000Z",
      "hoursUntilExpiry": 2
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us