ping`

Most callers should use canopy.ping() instead. This page is for SDK builders and developers calling the wire protocol directly.

POST /api/ping validates your API key and agent ID, returns a snapshot of the agent and org, and logs a zero-amount transaction so the dashboard can show the agent as connected.

Base URL: https://trycanopy.ai

Request

POST /api/ping
Authorization: Bearer <apiKey>
Content-Type: application/json

Body

Field	Type	Description
`agent_id`	`string`	The agent ID (`agt_…`) to check

200 — ok

{
  "ok": true,
  "agent_id": "agt_xxxxxxxx",
  "agent_name": "Trader",
  "org_id": "org_xxxxxxxx",
  "status": "active"
}

Field	Type	Description
`ok`	`boolean`	`true` when key + agent are valid
`agent_name`	`string`	Display name configured in the dashboard
`status`	`string`	Agent status (`"active"`, `"paused"`, etc.)

Example

curl --request POST \
  --url https://trycanopy.ai/api/ping \
  --header "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{ "agent_id": "agt_xxxxxxxx" }'

Run ping on startup as a configuration health check. If it returns 401, your API key is wrong. If it returns 400 with a missing-agent-id error, your agent ID is missing or revoked. The SDK throws CanopyApiError / CanopyConfigError with dashboardUrl pointing at the page that fixes the problem.