clinicpro/docs/api/specialty.md

Specialty API

Prefix: /api/v1/specialties, /api/v1/admin/specialty

---

GET /api/v1/specialties

List all medical specialties.

Permission: PUBLIC

Query Parameters

Param	Type	Required	Description
parent_id	integer	❌	Filter to sub-specialties of a parent

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "قلب و عروق",
      "slug": "ghalb-va-oroug",
      "parent_id": null,
      "status": "active",
      "weight": 10
    },
    {
      "id": 5,
      "name": "فوق تخصص قلب",
      "slug": "fowgh-takhassos-ghalb",
      "parent_id": 1,
      "status": "active",
      "weight": 5
    }
  ]
}

---

GET /api/v1/admin/specialties

List all specialties with pagination (admin view — includes inactive).

Permission: ROLE_ADMIN

Query Parameters

Param	Type	Required	Description
page	integer	❌	Default: 1
limit	integer	❌	Default: 20
search	string	❌	Search in name

Response 200

{
  "success": true,
  "data": [ ... ],
  "meta": { "totalRecords": 50, "totalPages": 3, "currentPage": 1 }
}

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_AUTH_006	403	Not admin

---

POST /api/v1/admin/specialty

Create a new specialty.

Permission: ROLE_ADMIN

Request Body (application/json)

{
  "name": "قلب و عروق",
  "slug": "ghalb-va-oroug",
  "parent_id": null,
  "status": "active",
  "weight": 10
}

Field	Type	Required	Description
name	string	✅	Specialty name
slug	string	❌	Auto-generated from name if omitted
parent_id	integer	❌	Parent specialty ID (for sub-specialties)
status	string	❌	"active" (default) or "inactive"
weight	integer	❌	Sort weight

Response 201

Specialty object.

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_AUTH_006	403	Not admin
ERR_VALIDATION_002	422	Missing name

---

PATCH /api/v1/admin/specialty/{id}

Update a specialty.

Permission: ROLE_ADMIN

Path Parameters

Param	Type	Description
id	integer	Specialty ID

Request Body (all optional)

{
  "name": "قلب و عروق ویرایش‌شده",
  "status": "inactive",
  "weight": 20,
  "parent_id": null,
  "slug": "new-slug"
}

Response 200

Updated specialty object.

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_AUTH_006	403	Not admin
ERR_NOT_FOUND_001	404	Specialty not found

---

DELETE /api/v1/admin/specialty/{id}

Delete a specialty.

Permission: ROLE_ADMIN

Response 200

{ "success": true, "data": { "message": "تخصص حذف شد" } }

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_AUTH_006	403	Not admin
ERR_NOT_FOUND_001	404	Specialty not found