aboutsummaryrefslogtreecommitdiffstats

Studirect API Documentation

This documentation describes all available API endpoints for the Studirect platform, grouped by resource and function. Each endpoint includes the HTTP method, route, required authentication/authorization, parameters, and a brief description of its purpose.

Authentication & Authorization

  • Students, companies, and admins authenticate via login endpoints.
  • Sanctum tokens are used for session management.
  • Some routes require specific abilities (student, company, admin).
  • Some routes use signed URLs for verification and password resets.
  • Rate limiting is applied via throttle middleware.

Table of Contents

  1. Student Endpoints
  2. Company Endpoints
  3. Admin Endpoints
  4. Logs
  5. Appointments
  6. Connections
  7. Authentication
  8. Password Reset
  9. Messages
  10. Skills
  11. Diplomas
  12. Skill Match

1. Student Endpoints

Register New Student

  • POST /students
  • Body: Student registration data
  • Auth: None
  • Description: Register a new student.

Verify Student Email

  • GET /students/{id}/verify
  • Auth: Signed URL
  • Description: Verify a student's email address.

List Students

  • GET /students
  • Auth: auth:sanctum, ability:student,admin
  • Description: Get a list of students.

Get Student Detail

  • GET /students/{id}
  • Auth: auth:sanctum, ability:student,admin
  • Description: Get details for a specific student.

Update Student

  • PUT /students/{id}
  • PATCH /students/{id}
  • Auth: auth:sanctum, ability:student,admin
  • Description: Update all or part of a student's details.

Delete Student

  • DELETE /students/{id}
  • Auth: auth:sanctum, ability:student,admin
  • Description: Remove a student account.

2. Company Endpoints

List Companies

  • GET /companies
  • Auth: auth:sanctum
  • Description: List all companies.

Register New Company

  • POST /companies
  • Auth: auth:sanctum, ability:company,admin
  • Description: Register a new company.

Get Company Detail

  • GET /companies/{id}
  • Auth: auth:sanctum, ability:company,admin
  • Description: Get a company's details.

Update Company

  • PUT /companies/{id}
  • PATCH /companies/{id}
  • Auth: auth:sanctum, ability:company,admin
  • Description: Update all or part of a company's details.

Delete Company

  • DELETE /companies/{id}
  • Auth: auth:sanctum, ability:company,admin
  • Description: Remove a company account.

3. Admin Endpoints

List Admins

  • GET /admins
  • Auth: auth:sanctum, ability:admin
  • Description: List all admins.

Register New Admin

  • POST /admins
  • Auth: auth:sanctum, ability:admin
  • Description: Register a new admin.

Get Admin Detail

  • GET /admins/{id}
  • Auth: auth:sanctum, ability:admin
  • Description: Get admin details.

Update Admin

  • PUT /admins/{id}
  • Auth: auth:sanctum, ability:admin
  • Description: Update admin details.

Delete Admin

  • DELETE /admins/{id}
  • Auth: auth:sanctum, ability:admin
  • Description: Remove an admin account.

4. Logs

  • GET /admin/logs
  • List all logs (admin only)
  • GET /admin/logs/students/{id}
  • Get logs for a specific student
  • GET /admin/logs/companies/{id}
  • Get logs for a specific company
  • GET /admin/logs/admins/{id}
  • Get logs for a specific admin
  • Auth: auth:sanctum, ability:admin

5. Appointments

List Appointments

  • GET /appointments
  • Auth: auth:sanctum
  • Description: List all appointments.

Create Appointment

  • POST /appointments
  • Auth: auth:sanctum
  • Description: Create a new appointment.

Get Appointment

  • GET /appointments/{id}
  • Auth: auth:sanctum
  • Description: Get appointment details.

Update Appointment

  • PUT /appointments/{id}
  • Auth: auth:sanctum
  • Description: Update appointment details.

Delete Appointment

  • DELETE /appointments/{id}
  • Auth: auth:sanctum
  • Description: Delete an appointment.

6. Connections

List Connections

  • GET /connections
  • Auth: auth:sanctum
  • Description: List all connections.

Create Connection

  • POST /connections
  • Auth: auth:sanctum
  • Description: Create a new connection.

Get Connection

  • GET /connections/{id}
  • Auth: auth:sanctum
  • Description: Get details for a specific connection.

Update Connection Time

  • PATCH /connections/{id}
  • Auth: auth:sanctum
  • Description: Update only the time for a connection.

Delete Connection

  • DELETE /connections/{id}
  • Auth: auth:sanctum
  • Description: Delete a connection.

7. Authentication

Student Login

  • POST /students/login
  • Body: { email, password }
  • Throttle: login
  • Description: Login as student.

Company Login

  • POST /companies/login
  • Body: { email, password }
  • Throttle: login
  • Description: Login as company.

Admin Login

  • POST /admins/login
  • Body: { email, password }
  • Throttle: login
  • Description: Login as admin.

Generic Login

  • POST /login
  • Body: { email, password }
  • Throttle: login
  • Description: Login for any user type.

Logout (Protected)

  • POST /students/logout
    /companies/logout
    /admins/logout
    /logout
  • Auth: auth:sanctum
  • Description: Logout for each user type or general.

8. Password Reset

Send Password Reset Email

  • POST /students/{id}/reset/mail
  • Auth: Signed URL, throttle:mail
  • Description: Send password reset mail to student.

Reset Student Password

  • PATCH /students/{id}/reset
  • Auth: Signed URL
  • Description: Reset student password.

9. Messages

Send Message

  • POST /messages/send
  • Body: { sender_id, receiver_id, message }
  • Description: Send a message.

Get Conversation

  • POST /messages/conversation
  • Body: { participant_one_id, participant_two_id }
  • Description: Get conversation between two participants.

10. Skills

List Skills

  • GET /skills
  • Description: List all skills.

Get Skill Detail

  • GET /skills/{id}
  • Description: Get a specific skill.

Attach Skill to Student

  • POST /students/{id}/skills
  • Description: Attach a skill to a student.

Remove Skill from Student

  • DELETE /students/{id}/skills/{skill_id}
  • Description: Remove a skill from a student.

Get Student Skills

  • GET /students/{id}/skills
  • Description: List skills for a specific student.

Attach Skill to Company

  • POST /companies/{id}/skills
  • Description: Attach a skill to a company.

Remove Skill from Company

  • DELETE /companies/{id}/skills/{skill_id}
  • Description: Remove a skill from a company.

Get Company Skills

  • GET /companies/{id}/skills
  • Description: List skills for a specific company.

11. Diplomas

List Diplomas

  • GET /diplomas
  • Description: List all diplomas.

Get Diploma Detail

  • GET /diplomas/{id}
  • Description: Get a specific diploma.

12. Skill Match

Calculate Skill Match Percentage

  • GET /match/{student_id}/{company_id}
  • Description: Calculate and return the skill match percentage between a student and a company.

Error Handling

  • 401 Unauthorized: Missing or invalid authentication token.
  • 403 Forbidden: Insufficient ability/role.
  • 404 Not Found: Resource does not exist.
  • 422 Unprocessable Entity: Validation error.

Notes

  • All endpoints return JSON.
  • Use Bearer tokens for authenticated requests.
  • Rate limiting is enforced on sensitive endpoints.
  • For full request/response schemas, see the controllers or request validation files in the repository.
generated by cgit v1.3.1 (git 2.54.0) at 2026-10-16 02:00:56 +0200