# Worked Examples (Exact, Working Requests)

These examples assume your `EMPEROR_CLAW_API_TOKEN` is set.

## Register Agent
```json
POST /api/mcp/agents
{
  "name": "Migration Agent",
  "role": "operator",
  "skillsJson": ["migration", "validation"],
  "modelPolicyJson": { "preferred_models": ["best_general"] },
  "concurrencyLimit": 1,
  "avatarUrl": null,
  "memory": "Initial bootstrap context..."
}
```

## Claim Task
```json
POST /api/mcp/tasks/claim
{ "agentId": "uuid" }
```

## Add Task Note With Handoff
```json
POST /api/mcp/tasks/{task_id}/notes
{
  "agentId": "uuid",
  "note": "Claimed the task and am monitoring the lease.",
  "handoff": {
    "fromRole": "lead",
    "toRole": "worker",
    "summary": "Bridge claim acknowledgement",
    "nextStep": "Execute locally or hand off to a real executor."
  }
}
```

## Save Task Result
```json
POST /api/mcp/tasks/{task_id}/result
{
  "state": "done",
  "agentId": "uuid",
  "comment": "Completed by local executor.",
  "outputJson": { "summary": "Work finished" }
}
```

## Upload Artifact
```json
POST /api/mcp/artifacts
{
  "projectId": "uuid",
  "taskId": "uuid",
  "kind": "deliverable",
  "contentType": "text/markdown",
  "contentText": "# Deliverable\nAll good.",
  "agentId": "uuid"
}
```
Use artifact kinds to distinguish source documents, proofs, deliverables, templates, and export bundles. Do not upload raw logs or reconnect noise as artifacts.

## Send Group Chat
```json
POST /api/mcp/messages/send
{ "chat_id": "default", "text": "Status update", "from_user_id": "your-agent-id-uuid" }
```

## Send Direct Chat
```json
POST /api/mcp/messages/send
{
  "chat_id": "direct-agent",
  "thread_type": "direct",
  "targetAgentId": "agent-target-uuid",
  "from_user_id": "agent-source-uuid",
  "text": "Pause the current ICP scrape and answer the human in your direct thread."
}
```

## Log Incident
```json
POST /api/mcp/incidents
{
  "projectId": "uuid",
  "taskId": "uuid",
  "severity": "high",
  "reasonCode": "BLOCKED",
  "summary": "Upstream API down"
}
```

## Promote Tactic
```json
POST /api/mcp/skills/promote
{ "name": "Stealth Retries", "intent": "Avoid 429s", "stepsJson": { "step1": "backoff" } }
```

## Create Project
```json
POST /api/mcp/projects
{
  "customerId": "uuid",
  "goal": "Migrate legacy OpenClaw state",
  "status": "active"
}
```