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

✅ 200 OK

{
  "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
  }
}

❌ 500 Internal Server Error

{ "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

✅ 200 OK

{ "message": "Company created successfully" }

⚠️ 422 Validation Error

{ 
    "message": "The label field is required.", 
    "errors": 
    { 
        "label": ["The label field is required."] 
    } 
} 

❌ 500 Internal Server Error

{ "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

✅ 200 OK

{ 
    "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" 
    } 
} 

❌ 404 Not Found

{ "message": "No query results for model" }

Update Company

POST /api/companies/ 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:

Deletes the old physical file from public/files/ (if exists)
Deletes the old File record
Creates a new File record
Stores the new file
Updates company_image_id

Response

✅ 200 OK

{ "message": "Company updated successfully !!!!" }

⚠️ 422 Validation Error

{ 
    "message": "The currency must be a string.", 
    "errors": { "currency": ["The currency must be a string."] } 
} 

❌ 500 Internal Server Error

{ "message": "Failed to update company: <error details>" }

Archive Company

POST /api/companies/{id}/archive Archives a company. Authorization

Policy: archive on Company

✅ 200 OK

{ "message": "Company archived successfully." }

❌ 500 Internal Server Error

{ "message": "An unexpected error occurred." }

Unarchive (Restore) Company

POST /api/companies/{id}/unarchive Restores an archived company. Authorization

Policy: restore on Company

Response

✅ 200 OK

{ "message": "Company restored successfully." }

❌ 500 Internal Server Error

{ "message": "An unexpected error occurred." }

Delete Company

DELETE /api/companies/{id} Soft-deletes a company (uses Eloquent delete()). Authorization

Policy: delete on Company

Response

✅ 200 OK

{ "message": "Company force deleted successfully." }

❌ 500 Internal Server Error

{ "message": "An unexpected error occurred." }

Introduction

Getting Started

System Design

Modules

API Reference

Development Guide

Deployment

Companies

Get All Companies

Create Company

Get Company By ID

Update Company

Archive Company

Unarchive (Restore) Company

Delete Company

​Get All Companies

​Create Company

​Get Company By ID

​Update Company

​Archive Company

​Unarchive (Restore) Company

​Delete Company

Get All Companies

Create Company

Get Company By ID

Update Company

Archive Company

Unarchive (Restore) Company

Delete Company