> **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.

# Audit — Dashboard API (source-reviewed)

**Base URL:** `/api/v1`. **Authentication:** Sanctum bearer token. **Permission:** `audit.view`. Source: [routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Audit/Routes/api.php), [controller](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Audit/Interfaces/Http/Controllers/AuditController.php).

## 1. `GET /api/v1/audits`

**Purpose:** paginated audit log. The controller returns the **raw Laravel paginator JSON** of `OwenIt\Auditing\Models\Audit`, **not** the usual `{"data": { ... }}` envelope.

**Request:** no body or path parameters.

| Query | Type | Required | Validation / behavior |
|---|---|---|---|
| `filter[event]` | string | No | Exact match on audit `event` |
| `filter[auditable_type]` | string | No | Exact match on `auditable_type` |
| `filter[auditable_id]` | string/integer | No | Exact match on audited record ID |
| `filter[user_id]` | string/integer | No | Exact match on actor ID |
| `sort` | string | No | Only `created_at` or `-created_at`; default `-created_at` |
| `per_page` | integer-like | No | Default 25; upper-capped to 100 by controller. No explicit FormRequest min validation here. |
| `page` | integer-like | No | Standard Laravel paginator page number |

**Example request:**

```http
GET /api/v1/audits?filter[event]=updated&filter[user_id]=12&sort=-created_at&per_page=25&page=1 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
```

**200 Response — representative paginator shape:**

```json
{
  "current_page": 1,
  "data": [
    {
      "id": 1001,
      "user_type": "App\\Models\\User",
      "user_id": 12,
      "event": "updated",
      "auditable_type": "Example\\Record",
      "auditable_id": 88,
      "old_values": {"status": "pending"},
      "new_values": {"status": "approved"},
      "url": null,
      "ip_address": null,
      "user_agent": null,
      "tags": null,
      "created_at": "2026-11-22T10:00:00.000000Z",
      "updated_at": "2026-11-22T10:00:00.000000Z"
    }
  ],
  "first_page_url": "https://example.test/api/v1/audits?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://example.test/api/v1/audits?page=1",
  "links": [],
  "next_page_url": null,
  "path": "https://example.test/api/v1/audits",
  "per_page": 25,
  "prev_page_url": null,
  "to": 1,
  "total": 1
}
```

**Response contract notes:** pagination keys follow Laravel `LengthAwarePaginator::toArray()`; `data` is an array of audit model rows. The example row's fields reflect typical OwenIt Auditing schema, but the exact serialized fields, optional fields, and timestamp format are **not confirmed** without inspecting model configuration/runtime serialization. Do not generate strict DTOs from the example row until verified.

| Response path | Type | Meaning |
|---|---|---|
| `current_page`, `last_page`, `per_page`, `total` | integer | Pagination counts |
| `data` | array<object> | Audit records; raw model serialization |
| `data[].id`, `data[].user_id`, `data[].auditable_id` | integer \| null | Identifiers (model-dependent nullability) |
| `data[].event`, `data[].auditable_type` | string | Event and audited model |
| `data[].old_values`, `data[].new_values` | object \| array \| null | Changes as serialized by auditing package |
| `first_page_url`, `last_page_url`, `path` | string | Pagination URLs |
| `next_page_url`, `prev_page_url` | string \| null | Next/previous URLs |
| `from`, `to` | integer \| null | First/last row numbers |
| `links` | array<object> | Laravel page navigation links |

**Errors:** authentication/authorization typically 401/403; unsupported filters/sorts may return 400 from Spatie QueryBuilder; exact error JSON requires global handler verification. **Security:** never expose this administrative log to ordinary app users.
