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

# Support API — Dashboard (source-reviewed contracts)

**Source:** [Routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Support/Routes/api.php), [controllers and request classes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Support/Interfaces/Http/Controllers/SupportController.php). **Base URL:** `/api/v1`.

**Status:** 20 route operations covered. JSON values below are **illustrative**, not captured runtime responses. Some admin presenter-dependent fields and enum values are explicitly pending verification; do not infer omitted fields are absent. Common success is `{"data":...}`, except list endpoints which may include `links`, `meta`, etc. Errors are localized and their exact error envelopes are not asserted without inspecting middleware.

## `GET /api/v1/admin/support/topics`

**Purpose:** List topics. **Access:** support.topics.manage.

**Path / query:** filter[active]:0|1|true|false; filter[search]:string max60.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": [
    {
      "id": 3,
      "code": "delivery",
      "name": {
        "ar": "التوصيل",
        "en": "Delivery"
      },
      "default_priority": "normal",
      "sort": 0,
      "active": true,
      "created_at": "2026-11-22T10:00:00+00:00",
      "updated_at": "2026-11-22T10:00:00+00:00",
      "tickets_count": 4
    }
  ]
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; unpaginated; sorted by sort,id.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `POST /api/v1/admin/support/topics`

**Purpose:** Create topic. **Access:** support.topics.manage.

**Path / query:** —.

**Request body / validation:** code:string required max40; name:localized object required; default_priority:enum?; sort:int? >=0; active:bool?.

**Example request body:**
```json
{
  "code": "delivery",
  "name": {
    "ar": "التوصيل",
    "en": "Delivery"
  },
  "default_priority": "normal",
  "sort": 0,
  "active": true
}
```

**Illustrative success response:**
```json
{
  "data": {
    "id": 3,
    "code": "delivery",
    "name": {
      "ar": "التوصيل",
      "en": "Delivery"
    },
    "default_priority": "normal",
    "sort": 0,
    "active": true,
    "created_at": "2026-11-22T10:00:00+00:00",
    "updated_at": "2026-11-22T10:00:00+00:00"
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 201; localized name validated by LocalizedTextRule.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `GET /api/v1/admin/support/topics/{id}`

**Purpose:** Topic detail. **Access:** support.topics.manage.

**Path / query:** id:int path.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": {
    "id": 3,
    "code": "delivery",
    "name": {
      "ar": "التوصيل",
      "en": "Delivery"
    },
    "default_priority": "normal",
    "sort": 0,
    "active": true,
    "created_at": "2026-11-22T10:00:00+00:00",
    "updated_at": "2026-11-22T10:00:00+00:00"
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; 404 unknown.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `PATCH /api/v1/admin/support/topics/{id}`

**Purpose:** Update topic. **Access:** support.topics.manage.

**Path / query:** id:int path.

**Request body / validation:** name:localized object?; default_priority:enum?; sort:int? >=0.

**Example request body:**
```json
{
  "sort": 2
}
```

**Illustrative success response:**
```json
{
  "data": {
    "id": 3,
    "code": "delivery",
    "name": {
      "ar": "التوصيل",
      "en": "Delivery"
    },
    "default_priority": "normal",
    "sort": 2,
    "active": true,
    "created_at": "2026-11-22T10:00:00+00:00",
    "updated_at": "2026-11-22T10:00:00+00:00"
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; code and active not changed here.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `POST /api/v1/admin/support/topics/{id}/activate`

**Purpose:** Activate topic. **Access:** support.topics.manage.

**Path / query:** id:int path.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": {
    "changed": true,
    "id": 3,
    "code": "delivery",
    "name": {
      "ar": "التوصيل",
      "en": "Delivery"
    },
    "default_priority": "normal",
    "sort": 0,
    "active": true,
    "created_at": "2026-11-22T10:00:00+00:00",
    "updated_at": "2026-11-22T10:00:00+00:00"
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; changed=false on no-op.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `POST /api/v1/admin/support/topics/{id}/deactivate`

**Purpose:** Deactivate topic. **Access:** support.topics.manage.

**Path / query:** id:int path.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": {
    "changed": true,
    "id": 3,
    "code": "delivery",
    "name": {
      "ar": "التوصيل",
      "en": "Delivery"
    },
    "default_priority": "normal",
    "sort": 0,
    "active": false,
    "created_at": "2026-11-22T10:00:00+00:00",
    "updated_at": "2026-11-22T10:00:00+00:00"
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; changed=false on no-op.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `GET /api/v1/admin/support/topics/{id}/history`

**Purpose:** Topic audit. **Access:** support.topics.manage.

**Path / query:** id:int path; per_page:int? 1..100 default25.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": [
    {
      "id": 1,
      "event": "updated",
      "old_values": {},
      "new_values": {},
      "actor": {
        "id": 5,
        "name": "Agent"
      },
      "at": "2026-11-22T10:00:00+00:00"
    }
  ],
  "links": {
    "first": "/api/v1/admin/support/tickets?page=1",
    "last": "/api/v1/admin/support/tickets?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": null,
    "last_page": 1,
    "per_page": 15,
    "to": null,
    "total": 0
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; paginated audit old_values/new_values.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `GET /api/v1/admin/support/settings`

**Purpose:** Support settings. **Access:** settings.manage.

**Path / query:** —.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": {
    "message_min": 10,
    "message_max": 10000,
    "attachments_max": 5,
    "reopen_days": 7,
    "open_tickets_max": 5,
    "response_sla_hours": 24,
    "alert_recipients": [],
    "contact_email": "support@example.com",
    "reply_hours": {
      "ar": "يوميًا",
      "en": "Daily"
    },
    "faq_slugs": [],
    "policy_slugs": []
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; configuration values vary by deployment.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `PATCH /api/v1/admin/support/settings`

**Purpose:** Update support settings. **Access:** settings.manage.

**Path / query:** —.

**Request body / validation:** message_min:int? 1..200; message_max:int? 50..10000; attachments_max:int?; reopen_days:int? 0..90; open_tickets_max:int? 1..100; response_sla_hours:int? 1..720; alert_recipients:int[]? <=50; contact_email:email? max120; reply_hours:localized object?; faq_slugs:string[]? <=50; policy_slugs:string[]? <=50; reason:string|null max300.

**Example request body:**
```json
{
  "message_min": 10,
  "response_sla_hours": 24,
  "reason": "Support policy update"
}
```

**Illustrative success response:**
```json
{
  "data": {
    "message_min": 10,
    "message_max": 10000,
    "attachments_max": 5,
    "reopen_days": 7,
    "open_tickets_max": 5,
    "response_sla_hours": 24,
    "alert_recipients": [],
    "contact_email": "support@example.com",
    "reply_hours": {
      "ar": "يوميًا",
      "en": "Daily"
    },
    "faq_slugs": [],
    "policy_slugs": []
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; message_min <= message_max; change audit includes reason.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `GET /api/v1/admin/support/settings/history`

**Purpose:** Settings audit. **Access:** settings.manage.

**Path / query:** per_page:int? 1..100 default25.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": [
    {
      "id": 1,
      "event": "updated",
      "old_values": {},
      "new_values": {},
      "actor": {
        "id": 5,
        "name": "Agent"
      },
      "at": "2026-11-22T10:00:00+00:00"
    }
  ],
  "links": {
    "first": "/api/v1/admin/support/tickets?page=1",
    "last": "/api/v1/admin/support/tickets?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": null,
    "last_page": 1,
    "per_page": 15,
    "to": null,
    "total": 0
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; audit paginated.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `GET /api/v1/admin/support/tickets`

**Purpose:** Ticket queue. **Access:** support.tickets.view.

**Path / query:** per_page:int? 1..100 default15; sort: opened_at,last_activity_at,waiting_since,priority,closed_at,ref,status,id (prefix - descending); filter[...] see TicketQuery.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": [],
  "links": {
    "first": "/api/v1/admin/support/tickets?page=1",
    "last": "/api/v1/admin/support/tickets?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": null,
    "last_page": 1,
    "per_page": 15,
    "to": null,
    "total": 0
  },
  "summary": {
    "by_status": {},
    "waiting": 0,
    "overdue": 0,
    "unassigned": 0
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; default sort -priority; filters and sorts metadata in response; exact TicketQuery filters require additional read.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `GET /api/v1/admin/support/tickets/{ref}`

**Purpose:** Admin ticket detail. **Access:** support.tickets.view.

**Path / query:** ref:path.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": {
    "ref": "SUP-123",
    "status": "open",
    "priority": "normal",
    "messages": []
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; exact admin detail fields from AdminTicketViews require additional verification.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `GET /api/v1/admin/support/tickets/{ref}/history`

**Purpose:** Ticket audit. **Access:** support.tickets.view.

**Path / query:** ref:path; per_page:int? 1..100 default25.

**Request body / validation:** —.

**Example request body:**
```json
{}
```

**Illustrative success response:**
```json
{
  "data": [
    {
      "id": 1,
      "event": "updated",
      "old_values": {},
      "new_values": {},
      "actor": {
        "id": 5,
        "name": "Agent"
      },
      "at": "2026-11-22T10:00:00+00:00"
    }
  ],
  "links": {
    "first": "/api/v1/admin/support/tickets?page=1",
    "last": "/api/v1/admin/support/tickets?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": null,
    "last_page": 1,
    "per_page": 15,
    "to": null,
    "total": 0
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; audit paginated.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `POST /api/v1/admin/support/tickets/{ref}/replies`

**Purpose:** Reply to requester. **Access:** support.tickets.manage.

**Path / query:** ref:path.

**Request body / validation:** message:string required max20000; attachments:string[]?.

**Example request body:**
```json
{
  "message": "We are reviewing this",
  "attachments": []
}
```

**Illustrative success response:**
```json
{
  "data": {
    "message_id": 2,
    "ref": "SUP-123"
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 201; Idempotency-Key supported; response includes full admin detail (omitted here until presenter verified).

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `POST /api/v1/admin/support/tickets/{ref}/notes`

**Purpose:** Internal note. **Access:** support.tickets.manage.

**Path / query:** ref:path.

**Request body / validation:** body:string required max TicketMessage::NOTE_MAX.

**Example request body:**
```json
{
  "body": "Follow up with courier"
}
```

**Illustrative success response:**
```json
{
  "data": {
    "message_id": 3,
    "ref": "SUP-123"
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 201; internal notes not shown to customer; Idempotency-Key supported.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `POST /api/v1/admin/support/tickets/{ref}/assign`

**Purpose:** Assign agent. **Access:** support.tickets.manage.

**Path / query:** ref:path.

**Request body / validation:** assignee_id:int|null required present >=1.

**Example request body:**
```json
{
  "assignee_id": 5
}
```

**Illustrative success response:**
```json
{
  "data": {
    "changed": true,
    "ref": "SUP-123"
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; null unassigns; full admin detail returned.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `POST /api/v1/admin/support/tickets/{ref}/priority`

**Purpose:** Set priority. **Access:** support.tickets.manage.

**Path / query:** ref:path.

**Request body / validation:** priority:required TicketPriority enum.

**Example request body:**
```json
{
  "priority": "normal"
}
```

**Illustrative success response:**
```json
{
  "data": {
    "changed": true,
    "ref": "SUP-123"
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; full admin detail returned.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `POST /api/v1/admin/support/tickets/{ref}/status`

**Purpose:** Change status. **Access:** support.tickets.manage.

**Path / query:** ref:path.

**Request body / validation:** status:required TicketStatus enum; note:string|null max500.

**Example request body:**
```json
{
  "status": "open",
  "note": "Investigating"
}
```

**Illustrative success response:**
```json
{
  "data": {
    "changed": true,
    "ref": "SUP-123"
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; full admin detail returned.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `POST /api/v1/admin/support/tickets/{ref}/close`

**Purpose:** Close ticket. **Access:** support.tickets.manage.

**Path / query:** ref:path.

**Request body / validation:** note:string|null max500.

**Example request body:**
```json
{
  "note": "Resolved"
}
```

**Illustrative success response:**
```json
{
  "data": {
    "changed": true,
    "ref": "SUP-123"
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; full admin detail returned.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.

## `POST /api/v1/admin/support/tickets/{ref}/reopen`

**Purpose:** Reopen ticket. **Access:** support.tickets.manage.

**Path / query:** ref:path.

**Request body / validation:** note:string|null max500.

**Example request body:**
```json
{
  "note": "Further review"
}
```

**Illustrative success response:**
```json
{
  "data": {
    "changed": true,
    "ref": "SUP-123"
  }
}
```

**Response contract:** `data` contains the object/list shown (except endpoints returning top-level pagination fields). Types are represented by the example JSON values: `null` means nullable; arrays may be empty; date/time strings are ISO-8601 where shown. **Caveat:** 200; full admin detail returned.

**Errors:** 401 for protected routes without a valid session, 403 for missing admin permission, 422 for Laravel validation failures, 404 for unknown or unauthorized ticket references (as enforced by owner-scoped lookup). Other business errors are localized; exact status and payload require middleware/domain verification.
