---
title: "Test Agent Ping"
method: POST
path: "/api/v1/integrations/agent-test-ping"
tags: ["integrations"]
---

# Test Agent Ping

`POST /api/v1/integrations/agent-test-ping`

## Request

- Base URL: `https://api.badgeia.com`
- URL: `https://api.badgeia.com/api/v1/integrations/agent-test-ping`
- Auth: none declared

BRIEF-001 §6 IN-2 — canary request against a candidate agent endpoint.

Posts one synthetic payload (shape: ``payload.payload_schema``) to the
URL the customer typed into the connect form. Returns request + verbatim
response + typed result class. The customer reads the response inline
to fix auth / shape mismatches BEFORE committing to a full benchmark
run.

Auth-required: prosumers wire this against their own infrastructure,
not the public internet from an anonymous caller. The SSRF gate is
the same `resolve_public_url` + `pinned_request_kwargs` pattern used
by `/test-connection` and `arena._call_agent_endpoint` so a malicious
endpoint string can't reach 169.254.169.254 or 127.0.0.1.

## Request body

- TestPingRequest: Connect-step canary request — BRIEF-001 §6 IN-2 / AC-04. Drives the *Test ping* button. The customer hasn't created an Agent row yet (this is pre-registration), so we accept the URL + schema as a request body and synthesize one canned task to send. Legacy authentication fields remain parseable only so stale clients receive the stable T1 retirement response instead of a generic 422.
  - `endpoint` string, required
  - `payload_schema` 'badge_native' | 'openai_chat' | 'anthropic_messages'
  - `auth_type` string
  - `auth_token` string, nullable
  - `prompt` string, nullable

## Response `200`

Successful Response

- TestPingResponse: Full verbatim ping result — see TestPingRequest docstring. `result` is the typed outcome class for funnel analytics (BRIEF-001 §5 `benchmark_test_ping_clicked.result`). The body preview is the customer-facing surface — "tell me what my endpoint actually said" — capped at 500 chars to bound payload size.
  - `success` boolean, required
  - `status_code` integer, nullable, required
  - `latency_ms` integer, nullable, required
  - `result` 'success' | 'non_2xx' | 'bad_response_shape' | 'connection_refused' | 'timeout' | 'ssrf_blocked' | 'response_too_large' | 'endpoint_url_unsupported', required
  - `payload_schema` string, required
  - `request_body` object, required
  - `response_body_preview` string, nullable, required
  - `message` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/badgeia/apis/badge.md) · [All operations](https://skmtc.dev/badgeia/apis/badge/llms.txt) · [OpenAPI document](https://skmtc.dev/badgeia/apis/badge/revisions/7e7f7fee8b77?raw)