> ## Documentation Index
> Fetch the complete documentation index at: https://theteam-13fc7f49.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Companies

> Company management endpoints: list, create, view, update (with image upload), archive, restore, and delete.

**Common Notes**

* Most endpoints require authentication.
* Access is controlled by policies (`viewAny`, `view`, `create`, `update`, `archive`, `restore`, `delete`).

***

# Get All Companies

**GET** /api/companies

Returns a paginated list of companies, with optional search by label.

**Authorization**

* Policy: `viewAny` on `Company`

**Query Params**

| Field | Type | Required | Description |
| - | - | - | - |
| per\_page | integer | ❌ No | Items per page. Default: `10` |
| page | integer | ❌ No | Page number. Default: `1` |
| search | string | ❌ No | Search by `label` (LIKE query) |

**Response Shape**
The API returns:

* `data`: array of companies (simplified fields)
* `pagination`: only `per_page` and `page`

Each company may include `company_image` if available:

* `id`
* `file_name`
* `url`

**Response**

> [tab] 200
>
> ✅ 200 OK
>
> ```json theme={null}
> {
>   "data": [
>     {
>       "id": 1,
>       "company_id": null,
>       "label": "Acme Academy",
>       "description": "Training company",
>       "currency": "TND",
>       "company_image_id": 12,
>       "created_at": "2026-01-01T10:00:00.000000Z",
>       "updated_at": "2026-01-05T10:00:00.000000Z",
>       "archived_at": null,
>       "deleted_at": null,
>       "company_image": {
>         "id": 12,
>         "file_name": "1700000000_logo.png",
>         "url": "files/1700000000_logo.png"
>       }
>     }
>   ],
>   "pagination": {
>     "per_page": 10,
>     "page": 1
>   }
> }
> ```

> [tab] 500
>
> ❌ 500 Internal Server Error
>
> ```json theme={null}
> { "message": "An unexpected error occurred." } 
> ```

# Create Company

POST /api/companies

Creates a new company. Optionally accepts an uploaded image (`company_image`) and stores it under `public/files`.

**Authorization**

* Policy: `create` on `Company`

**Content-Type**
This endpoint supports file upload, so use:

| Name | Value |
| - | - |
| Content-Type | multipart/form-data |

**Body (Validation Rules)**

| Field | Type | Required | Description |
| - | - | - | - |
| company\_id | integer | ❌ No | Must exist in `companies` table. |
| label | string | ✅ Yes | min 1, max 255 |
| description | string | ✅ Yes | min 1 |
| currency | string | ✅ Yes | min 1, max 255 |
| company\_image | file | ❌ No | Image file (jpeg/png/jpg/gif/svg), max 5MB |

**Example (multipart)**

* label: `Acme Academy`

* description: `Training company`

* currency: `TND`

* company\_image: (file upload)

**Response**

> [tab] 200
>
> ✅ 200 OK
>
> ```json theme={null}
> { "message": "Company created successfully" } 
> ```

> [tab] 422
>
> ⚠️ 422 Validation Error
>
> ```json theme={null}
> { 
>     "message": "The label field is required.", 
>     "errors": 
>     { 
>         "label": ["The label field is required."] 
>     } 
> } 
> ```

> [tab] 500
>
> ❌ 500 Internal Server Error
>
> ```json theme={null}
> { "message": "An unexpected error occurred." } 
> ```

**Notes**
If `company_image` is uploaded:

* A `File` record is created

* The file is stored under `public/files`

* The company is updated with `company_image_id`

# Get Company By ID

GET /api/companies/`{id}`

Returns a single company (simplified fields) with optional `company_image`.

**Authorization**

* Policy: `view` on `Company`

**Path Params**

| Param | Type | Required | Description |
| - | - | - | - |
| id | integer | ✅ Yes | Company ID |

**Response**

> [tab] 200
>
> ✅ 200 OK
>
> ```json theme={null}
> { 
>     "id": 1, 
>     "company_id": null, 
>     "label": "Acme Academy", 
>     "description": "Training company", 
>     "currency": "TND", 
>     "company_image_id": 12, 
>     "created_at": "2026-01-01T10:00:00.000000Z", 
>     "updated_at": "2026-01-05T10:00:00.000000Z", 
>     "archived_at": null, 
>     "deleted_at": null, 
>     "company_image": 
>     { 
>         "id": 12, 
>         "file_name": "1700000000_logo.png", 
>         "url": "files/1700000000_logo.png" 
>     } 
> } 
> ```

> [tab] 404
>
> ❌ 404 Not Found
>
> ```json theme={null}
> { "message": "No query results for model" } 
> ```

# Update Company

POST /api/companies/{id}

Updates company fields and optionally replaces `company_image`.

**Authorization**

* Policy: `update` on `Company`

**Content-Type**

| Name | Value |
| - | - |
| Content-Type | multipart/form-data |

**Body (Validation Rules)**

| Field | Type | Required | Description |
| - | - | - | - |
| company\_id | integer | ❌ No | Must exist in `companies` table |
| label | string | ❌ No | min 1, max 255 |
| description | string | ❌ No | min 1 |
| currency | string | ❌ No | min 1, max 255 |
| company\_image | file | ❌ No | Image file (jpeg/png/jpg/gif/svg), max 5MB |

**Image Replacement Behavior**
f a new `company_image` is uploaded:

1. Deletes the old physical file from `public/files/` (if exists)

2. Deletes the old `File` record

3. Creates a new `File` record

4. Stores the new file

5. Updates `company_image_id`

**Response**

> [tab] 200
>
> ✅ 200 OK
>
> ```json theme={null}
> { "message": "Company updated successfully !!!!" } 
> ```

> [tab] 422
>
> ⚠️ 422 Validation Error
>
> ```json theme={null}
> { 
>     "message": "The currency must be a string.", 
>     "errors": { "currency": ["The currency must be a string."] } 
> } 
> ```

> [tab] 500
>
> ❌ 500 Internal Server Error
>
> ```json theme={null}
> { "message": "Failed to update company: <error details>" } 
> ```

# Archive Company

POST /api/companies/`{id}`/archive

Archives a company.

**Authorization**

* Policy: `archive` on `Company`

***

> [tab] 200
>
> ✅ 200 OK
>
> ```json theme={null}
> { "message": "Company archived successfully." } 
> ```

> [tab] 500
>
> ❌ 500 Internal Server Error
>
> ```json theme={null}
> { "message": "An unexpected error occurred." } 
> ```

# Unarchive (Restore) Company

POST /api/companies/`{id}`/unarchive

Restores an archived company.

**Authorization**

* Policy: `restore` on `Company`

**Response**

> [tab] 200
>
> ✅ 200 OK
>
> ```json theme={null}
> { "message": "Company restored successfully." } 
> ```

> [tab] 500
>
> ❌ 500 Internal Server Error
>
> ```json theme={null}
> { "message": "An unexpected error occurred." } 
> ```

# Delete Company

DELETE /api/companies/`{id}`

Soft-deletes a company (uses Eloquent `delete()`).

**Authorization**

* Policy: `delete` on `Company`

**Response**

> [tab] 200
>
> ✅ 200 OK
>
> ```json theme={null}
> { "message": "Company force deleted successfully." } 
> ```

> [tab] 500
>
> ❌ 500 Internal Server Error
>
> ```json theme={null}
> { "message": "An unexpected error occurred." } 
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.