> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# BulkActions — Dashboard API (source-reviewed)

Source: [`routes`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/BulkActions/Routes/api.php), [`BulkController`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/BulkActions/Interfaces/Http/Controllers/BulkController.php), `Application/BulkRunner.php`, `Application/BulkResult.php`, and the three registered action implementations, GitLab `main`. API prefix: `/api/v1`. All endpoints require `auth:sanctum` and return localized business errors through `LocalizeBulkErrors`. Examples below are **illustrative** (not runtime captures).

## 1. GET `/api/v1/bulk` — actions permitted for current administrator

**Headers:** `Authorization: Bearer <token>`, `Accept: application/json`. No body, path parameters, or validated query parameters. `200` uses `ApiResponse::ok` (`{"data": [...]}`). The list is filtered by server-side `Gate::allows(action.permission())` and may be empty.

| Response path | Type | Meaning |
|---|---|---|
| `data` | `array<object>` | Actions current actor may execute |
| `data[].key` | `string` | Registered action key |
| `data[].max_items` | `integer` | Minimum of action limit and configured global limit |
| `data[].params` | `array<string>` | Names of parameters expected by action-specific validation |

```json
{"data":[{"key":"users.suspend","max_items":100,"params":["reason"]},{"key":"users.unsuspend","max_items":100,"params":[]},{"key":"users.delete","max_items":100,"params":["reason"]}]}
```

**Dashboard:** render actions from the returned list, not from hard-coded role names. Actual availability depends on the registered actions and user permissions.

## 2. GET `/api/v1/bulk/history` — current administrator's execution history

**Headers:** Bearer token and `Accept: application/json`. No validated request fields or body; the controller calls `paginate(20)` and Laravel pagination supports `?page=2` (no `per_page` control here). Records are filtered to `bulk_operations.user_id = current user` and sorted newest first by `id`. Unlike `GET /bulk`, response is a **raw Laravel paginator**, not wrapped in `ApiResponse::ok`.

| Response path | Type | Meaning |
|---|---|---|
| `data` | `array<object>` | Database operation rows, including persisted columns; see migration for exact column set |
| `data[].failures` | `array<object>` | Decoded failure JSON, with messages localized by `FailureTexts` |
| `current_page`, `last_page`, `per_page`, `total` | `integer` | Laravel pagination metadata |
| `first_page_url`, `last_page_url` | `string` | Pagination URLs |
| `next_page_url`, `prev_page_url` | `string|null` | Navigation URLs |
| `from`, `to` | `integer|null` | Row bounds |
| `links` | `array<object>` | Laravel page links |

Illustrative **partial** response (other persisted row columns depend on the migration):

```json
{"current_page":1,"data":[{"id":31,"failures":[{"id":"42","code":"account_not_active","message":"Localized explanation"}]}],"per_page":20,"total":1,"last_page":1,"next_page_url":null,"prev_page_url":null}
```

Do not treat this partial JSON as an exhaustive schema of the persisted operation row; the migration needs a separate schema check.

## 3. POST `/api/v1/bulk/{key}` — execute a bulk action

**Headers:** Bearer token, `Content-Type: application/json`, `Accept: application/json`, and **`Idempotency-Key`** for safe retries (middleware `idempotent`). Throttle: **20 requests/minute**. `{key}` is a string matching `[a-z0-9_.-]+`. Authorization uses `Gate::authorize(registry.get(key).permission())`; an unknown action is rejected by the registry. The operation processes each item separately; a failed item does not roll back successful items.

| Request field | Type | Required | Validation / behavior |
|---|---|---|---|
| `ids` | `array` | Yes | Nonempty (`min:1`); domain validates identifiers, duplicates, and max selection size |
| `params` | `object` | No | `sometimes|array`; action-specific rules applied by `ParamValidator` |
| `params.reason` for `users.suspend` | `string` | Yes | Max length `User::MAX_SUSPENSION_REASON` (constant; not independently resolved here) |
| `params.reason` for `users.delete` | `string` | No | Max 500; default reason used when omitted/blank |
| `params` for `users.unsuspend` | `object` | No | No action-specific fields |

Registered actions verified in repository:

| `{key}` | Required permission | Max IDs per call | Behavior |
|---|---|---:|---|
| `users.suspend` | `users.suspend` | 100 | Suspend users; refuses own account and invalid account states according to Identity rules |
| `users.unsuspend` | `users.suspend` | 100 | Unsuspend; lifting a permanent ban additionally requires `users.ban` |
| `users.delete` | `users.delete` | 100 | Delete users; cannot delete own account |

Example request:

```http
POST /api/v1/bulk/users.suspend
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: suspend-wave-20261122-01
```
```json
{"ids":["41","42","43"],"params":{"reason":"Fraud review case 984"}}
```

**200 Response:** `ApiResponse::ok` wrapper:

```json
{"data":{"action":"users.suspend","requested":3,"succeeded":2,"failed":1,"not_attempted":0,"failures":[{"id":"42","code":"account_not_active","message":"Localized explanation","source":"identity"}],"not_attempted_ids":[]}}
```

| Response path | Type | Meaning |
|---|---|---|
| `data.action` | `string` | Executed action key |
| `data.requested` | `integer` | Count of normalized selected IDs |
| `data.succeeded` | `integer` | Items completed successfully |
| `data.failed` | `integer` | Count of per-item failures |
| `data.not_attempted` | `integer` | Count skipped due to time budget |
| `data.failures` | `array<object>` | Failed items |
| `data.failures[].id` | `string` | Failed ID |
| `data.failures[].code` | `string` | Machine-readable error code |
| `data.failures[].message` | `string` | Localized display message |
| `data.failures[].source` | `string` (optional) | Source module namespace |
| `data.not_attempted_ids` | `array<string>` | IDs safe to resubmit after time budget expires |

**Errors / behavior:** unauthenticated 401; unauthorized 403; malformed request 422 (Laravel validation); throttled 429; unknown action, invalid selection, and invalid action-specific params use localized module exceptions (verify exact HTTP mapping in `LocalizeBulkErrors`). The global max defaults to 500, while these actions each cap at 100. Execution time budget defaults to 25 seconds (`Config/bulk-actions.php`). No all-or-nothing guarantee; the UI must show succeeded, failed, and not-attempted counts separately. A repeated request with the same idempotency key should replay the first result rather than repeat mutations.

**Source review status:** Controller, routes, result serialization, runner, registered action rules and config verified. Runtime error JSON and full history row schema not yet verified; no live API tests claimed.

## Verified history persistence schema (2026-11-22 source follow-up)

The `bulk_operations` migration `2026_11_18_070000_create_bulk_operations_table.php` resolves the previously open history-row schema. `GET /api/v1/bulk/history` returns a **raw Laravel paginator**, and each `data[]` record contains exactly these persisted columns (subject to Laravel serialization):

| Field | Database type | Meaning |
|---|---|---|
| `id` | unsigned bigint | Operation identifier |
| `user_id` | unsigned bigint | Administrator who ran the operation; history is scoped to this user |
| `action` | varchar(80) | Bulk action key |
| `requested` | unsigned integer | Selected items |
| `succeeded` | unsigned integer | Successful items |
| `failed` | unsigned integer | Failed items |
| `not_attempted` | unsigned integer, default 0 | Items not processed |
| `failures` | JSON, decoded into array by controller | Per-item failures, localized at response time |
| `created_at` | timestamp | Execution creation time |

The table has an index on `(user_id, id)` and no `updated_at` column. History page size is fixed at **20**, ordered by descending `id`; only `page` is used for navigation. This is source verification, not a runtime response capture.

```json
{
  "current_page": 1,
  "data": [{
    "id": 31,
    "user_id": 7,
    "action": "users.suspend",
    "requested": 3,
    "succeeded": 2,
    "failed": 1,
    "not_attempted": 0,
    "failures": [{"id":"42","code":"account_not_active","message":"Localized explanation"}],
    "created_at": "2026-11-22T12:00:00.000000Z"
  }],
  "per_page": 20,
  "total": 1,
  "last_page": 1
}
```

Example is illustrative and intentionally omits other paginator metadata.


## History persistence and response-envelope verification

Sources: `BulkController::history` and `2026_11_18_070000_create_bulk_operations_table.php` on GitLab `main`. `GET /api/v1/bulk/history` returns a **raw Laravel paginator** (not `ApiResponse::ok`); page size is hard-coded to 20 and records are restricted by `user_id` to the current authenticated user. Each row contains `id`, `user_id`, `action`, `requested`, `succeeded`, `failed`, `not_attempted`, `failures`, `created_at`. `failures` is decoded from stored JSON and localized before returning. The `bulk_operations` table has an index on `(user_id, id)`. This is code-derived; Staging verification remains pending.
