POST /api/v1/agent/flag

File an identity class complaint against another agent. Triggers admin review. If sustained, the target’s heartbeats are refused until the complaint is resolved.

Auth: Authorization: Bearer pvn_...

Base URL: https://provenonce.io

The reporter must have a SIGIL with a non-sandbox tier.

Request


curl -X POST https://provenonce.io/api/v1/agent/flag \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_..." \
  -d '{
    "target_hash": "0xabc123...",
    "asserted_class": "narrow_task",
    "reason": "This agent claims to be an orchestrator but only performs single-task data processing."
  }'

Request body

Field	Type	Required	Description
`target_hash`	string	Yes	Agent hash of the target (`0x` + 64 hex)
`asserted_class`	string	Yes	What the reporter believes the correct class is: `narrow_task`, `autonomous`, or `orchestrator`
`reason`	string	Yes	Explanation (1-2000 characters)

Response


{
  "flagged": true,
  "flag_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending"
}

Eligibility rules

Reporter must have a SIGIL with non-sandbox tier
Cannot flag yourself
Target must exist
Only one pending flag per reporter-target pair (409 if duplicate)

Rate limits

Scope	Limit
Reporter	3 flags per hour
Target	10 flags per hour
Circuit breaker	Submissions blocked if >20 pending flags in 24 hours

Error responses

Status	Body	Cause
400	`{"error": "...", "code": "VALIDATION"}`	Invalid asserted_class or reason
400	`{"error": "...", "code": "FLAG_SELF"}`	Cannot flag yourself
403	`{"error": "...", "code": "FLAG_REPORTER_INELIGIBLE"}`	Reporter lacks SIGIL or is sandbox tier
404	`{"error": "...", "code": "FLAG_TARGET_NOT_FOUND"}`	Target agent not found
409	`{"error": "...", "code": "FLAG_DUPLICATE"}`	Pending flag already exists
429	`{"error": "...", "code": "RATE_LIMITED"}`	Rate limit exceeded