# API Contract

## Purpose

Map high-level governance actions to Aibot Agent API HTTP routes.

## Base Rules

1. Base path: `/v1/agent-api`
2. Auth: `Authorization: Bearer <agent_api_key>`
3. Only `provider_type=3` and `status=active` agent can access.
4. Scope middleware executes before service business checks.

## Action Mapping (v1)

| Action | Method | Route | Required Scope |
|---|---|---|---|
| `group_detail_read` | `GET` | `/sessions/group/detail` | `group.detail.read` |
| `group_create` | `POST` | `/sessions/create_group` | `group.create` |
| `group_leave_self` | `POST` | `/sessions/leave` | - |
| `group_member_add` | `POST` | `/sessions/members/add` | `group.member.add` |
| `group_member_remove` | `POST` | `/sessions/members/remove` | `group.member.remove` |
| `group_member_role_update` | `POST` | `/sessions/members/role` | `group.member.role.update` |
| `group_all_members_muted_update` | `POST` | `/sessions/speaking/all_muted` | `group.speaking.update` |
| `group_member_speaking_update` | `POST` | `/sessions/members/speaking` | `group.speaking.update` |
| `group_dissolve` | `POST` | `/sessions/dissolve` | `group.dissolve` |

## OpenClaw Tool Mapping

Use the native `grix_group` tool with typed fields:

| Tool action | HTTP action | Required fields |
|---|---|---|
| `create` | `group_create` | `accountId`, `name` |
| `detail` | `group_detail_read` | `accountId`, `sessionId` |
| `leave` | `group_leave_self` | `accountId`, `sessionId` |
| `add_members` | `group_member_add` | `accountId`, `sessionId`, `memberIds` |
| `remove_members` | `group_member_remove` | `accountId`, `sessionId`, `memberIds` |
| `update_member_role` | `group_member_role_update` | `accountId`, `sessionId`, `memberId`, `role` |
| `update_all_members_muted` | `group_all_members_muted_update` | `accountId`, `sessionId`, `allMembersMuted` |
| `update_member_speaking` | `group_member_speaking_update` | `accountId`, `sessionId`, `memberId`, `isSpeakMuted` or `canSpeakWhenAllMuted` |
| `dissolve` | `group_dissolve` | `accountId`, `sessionId` |

## Payload Templates

### create

```json
{
  "action": "create",
  "accountId": "primary",
  "name": "Project Collaboration Group",
  "memberIds": ["1002", "9991"],
  "memberTypes": [1, 2]
}
```

### add_members

```json
{
  "action": "add_members",
  "accountId": "primary",
  "sessionId": "task_room_9083",
  "memberIds": ["1003"],
  "memberTypes": [1]
}
```

### leave

```json
{
  "action": "leave",
  "accountId": "primary",
  "sessionId": "task_room_9083"
}
```

## Error Matrix

| HTTP/BizCode | Meaning | Skill Response |
|---|---|---|
| `403/20011` | agent scope forbidden | Tell owner to grant corresponding scope |
| `400/10003` | invalid request payload | Ask for missing or corrected parameters |
| `401/10001` | invalid or missing auth | Check api_key and account config |
| `403/10002` | agent not active / invalid provider | Ask owner to activate the agent |

Notes:

1. `leave` does not require scope and should not route `403/20011` into scope remediation.

## Retry Policy

1. Never auto-retry `group_create` unless user confirms.
2. Allow one retry for transient network failure only.
3. Do not retry auth/scope/parameter failures automatically.