HelpDesk Pro

Appearance

REST API - Endpoints Reference ​

Complete reference for all available API endpoints, including request/response formats, parameters, and examples.

📋 Table of Contents ​

Overview ​

All endpoints follow RESTful conventions:

  • GET - Retrieve resources
  • POST - Create resources
  • PUT/PATCH - Update resources
  • DELETE - Delete resources

Base URL ​

https://your-domain.com/api/v1

Common Query Parameters ​

Most list endpoints support:

  • page - Page number (default: 1)
  • per_page - Items per page (default: 15, max: 100)
  • search - Search query
  • sort - Sort field
  • order - Sort direction (asc or desc)

Common Response Headers ​

Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45

Authentication ​

Manage user authentication and session management.

Login ​

POST /api/v1/auth/login

Request Body:

json
{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

json
{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "first_name": "John",
      "last_name": "Doe",
      "email": "user@example.com",
      "role": { ... }
    },
    "token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer"
  }
}

Register ​

POST /api/v1/auth/register

Request Body:

json
{
  "first_name": "John",
  "last_name": "Doe",
  "email": "newuser@example.com",
  "password": "secure-password",
  "password_confirmation": "secure-password"
}

Response:

json
{
  "success": true,
  "data": {
    "user": { ... },
    "token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer"
  }
}

Get Current User ​

GET /api/v1/auth/me

Headers:

Authorization: Bearer {token}

Response:

json
{
  "success": true,
  "data": {
    "id": 1,
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "role": { ... },
    ...
  }
}

Logout ​

POST /api/v1/auth/logout

Headers:

Authorization: Bearer {token}

Response:

json
{
  "success": true,
  "message": "Logged out successfully",
  "data": null
}

Request Password Reset ​

POST /api/v1/auth/password/reset

Request Body:

json
{
  "email": "user@example.com"
}

Response:

json
{
  "success": true,
  "message": "Password reset link sent to your email",
  "data": null
}

Reset Password with Token ​

POST /api/v1/auth/password/reset/{token}

Request Body:

json
{
  "email": "user@example.com",
  "password": "new-secure-password",
  "password_confirmation": "new-secure-password"
}

Response:

json
{
  "success": true,
  "message": "Password reset successfully",
  "data": null
}

📝 Note: For detailed authentication documentation, see the Authentication Guide.

Tickets ​

Manage support tickets - create, update, track, and resolve customer issues.

List Tickets ​

GET /api/v1/tickets

Query Parameters:

  • search - Search in subject, UID, status, priority
  • priority_id - Filter by priority
  • status_id - Filter by status
  • type_id - Filter by type
  • category_id - Filter by category
  • department_id - Filter by department
  • user_id - Filter by customer
  • assigned_to - Filter by assigned agent
  • date_from - Filter from date (YYYY-MM-DD)
  • date_to - Filter to date (YYYY-MM-DD)
  • type - Special filters: un_assigned, open, new
  • page - Page number
  • per_page - Items per page
  • sort - Sort field (id, subject, created_at, updated_at, priority_id, status_id)
  • order - Sort direction (asc, desc)

Response:

json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "uid": "100001",
      "subject": "Need help with login",
      "details": "I cannot log in to my account",
      "status": {
        "id": 1,
        "name": "Open",
        "slug": "open"
      },
      "priority": {
        "id": 1,
        "name": "High",
        "color": "#ff0000"
      },
      "category": { ... },
      "department": { ... },
      "user": { ... },
      "assignedTo": { ... },
      "created_at": "2025-01-15T10:30:00.000000Z",
      "updated_at": "2025-01-15T10:30:00.000000Z"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 15,
      "total": 100,
      "last_page": 7
    }
  }
}

Get Single Ticket ​

GET /api/v1/tickets/{id}

Accepts either ticket id or uid.

Response:

json
{
  "success": true,
  "data": {
    "id": 1,
    "uid": "100001",
    "subject": "Need help with login",
    "details": "Full ticket details...",
    "status": { ... },
    "priority": { ... },
    "category": { ... },
    "subCategory": { ... },
    "department": { ... },
    "ticketType": { ... },
    "contact": { ... },
    "user": { ... },
    "assignedTo": { ... },
    "attachments": [ ... ],
    "comments": [ ... ],
    "ticketEntries": [ ... ],
    "created_at": "2025-01-15T10:30:00.000000Z"
  }
}

Create Ticket ​

POST /api/v1/tickets

Request Body:

json
{
  "subject": "New Support Request",
  "details": "Detailed description of the issue",
  "priority_id": 1,
  "category_id": 1,
  "department_id": 1,
  "type_id": 1,
  "contact_id": 1,
  "assigned_to": 2,
  "due_date": "2025-01-20",
  "tags": ["urgent", "billing"]
}

Response (201):

json
{
  "success": true,
  "data": {
    "id": 123,
    "uid": "100123",
    "subject": "New Support Request",
    ...
  }
}

Update Ticket ​

PUT /api/v1/tickets/{id}
PATCH /api/v1/tickets/{id}

Request Body:

json
{
  "subject": "Updated Subject",
  "status_id": 2,
  "priority_id": 2,
  "assigned_to": 3
}

Delete Ticket ​

DELETE /api/v1/tickets/{id}

Response (204): No content

Restore Ticket ​

POST /api/v1/tickets/{id}/restore

Restore a soft-deleted ticket.

Add Comment ​

POST /api/v1/tickets/{id}/comments

Request Body:

json
{
  "comment": "This is a comment on the ticket",
  "is_internal": false
}

Response:

json
{
  "success": true,
  "data": {
    "id": 1,
    "comment": "This is a comment on the ticket",
    "user": { ... },
    "created_at": "2025-01-15T10:30:00.000000Z"
  }
}

Get Comments ​

GET /api/v1/tickets/{id}/comments

Get Ticket Conversations ​

GET /api/v1/tickets/{id}/conversations

Import Tickets ​

POST /api/v1/tickets/import

Request: Multipart form data with CSV file

Export Tickets ​

GET /api/v1/tickets/export

Query Parameters: Same as list tickets for filtering

Response: CSV file download

Contacts ​

Manage customer contacts and their information.

List Contacts ​

GET /api/v1/contacts

Query Parameters:

  • search - Search in name, email, phone
  • page, per_page, sort, order

Get Contact ​

GET /api/v1/contacts/{id}

Create Contact ​

POST /api/v1/contacts

Request Body:

json
{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "organization_id": 1
}

Update Contact ​

PUT /api/v1/contacts/{id}
PATCH /api/v1/contacts/{id}

Delete Contact ​

DELETE /api/v1/contacts/{id}

Restore Contact ​

POST /api/v1/contacts/{id}/restore

Customers ​

Manage customer accounts and profiles.

List Customers ​

GET /api/v1/customers

Get Customer ​

GET /api/v1/customers/{id}

Create Customer ​

POST /api/v1/customers

Request Body:

json
{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane@example.com",
  "password": "secure-password",
  "password_confirmation": "secure-password",
  "phone": "+1234567890",
  "organization_id": 1
}

Update Customer ​

PUT /api/v1/customers/{id}
PATCH /api/v1/customers/{id}

Delete Customer ​

DELETE /api/v1/customers/{id}

Restore Customer ​

POST /api/v1/customers/{id}/restore

Users ​

Manage system users (agents, admins, managers).

List Users ​

GET /api/v1/users

Query Parameters:

  • search - Search in name, email
  • role_id - Filter by role
  • page, per_page, sort, order

Get User ​

GET /api/v1/users/{id}

Create User ​

POST /api/v1/users

Request Body:

json
{
  "first_name": "Agent",
  "last_name": "User",
  "email": "agent@example.com",
  "password": "secure-password",
  "password_confirmation": "secure-password",
  "role_id": 2,
  "department_id": 1
}

Update User ​

PUT /api/v1/users/{id}
PATCH /api/v1/users/{id}

Delete User ​

DELETE /api/v1/users/{id}

Restore User ​

POST /api/v1/users/{id}/restore

List Pending Users ​

GET /api/v1/users/pending

Get list of users awaiting approval.

Approve User ​

POST /api/v1/users/pending/{id}/approve

Decline User ​

POST /api/v1/users/pending/{id}/decline

Organizations ​

Manage organizations and multi-tenant data.

List Organizations ​

GET /api/v1/organizations

Get Organization ​

GET /api/v1/organizations/{id}

Create Organization ​

POST /api/v1/organizations

Request Body:

json
{
  "name": "Acme Corporation",
  "email": "contact@acme.com",
  "phone": "+1234567890",
  "address": "123 Main St",
  "city": "New York",
  "state": "NY",
  "zip": "10001",
  "country": "US"
}

Update Organization ​

PUT /api/v1/organizations/{id}
PATCH /api/v1/organizations/{id}

Delete Organization ​

DELETE /api/v1/organizations/{id}

Restore Organization ​

POST /api/v1/organizations/{id}/restore

Conversations ​

Manage real-time chat conversations.

List Conversations ​

GET /api/v1/conversations

Query Parameters:

  • search - Search in messages
  • type - Filter by type (customer, internal)
  • status - Filter by status
  • page, per_page

Get Conversation ​

GET /api/v1/conversations/{id}

Create Conversation ​

POST /api/v1/conversations

Request Body:

json
{
  "ticket_id": 1,
  "type": "customer",
  "subject": "Chat about ticket"
}

Update Conversation ​

PUT /api/v1/conversations/{id}
PATCH /api/v1/conversations/{id}

Delete Conversation ​

DELETE /api/v1/conversations/{id}

Restore Conversation ​

POST /api/v1/conversations/{id}/restore

Send Message ​

POST /api/v1/conversations/{id}/messages

Request Body:

json
{
  "message": "Hello, how can I help you?",
  "is_internal": false
}

Get Messages ​

GET /api/v1/conversations/{id}/messages

Query Parameters:

  • page, per_page

Mark as Read ​

POST /api/v1/conversations/{id}/mark-read

Settings ​

Manage system settings including categories, priorities, statuses, departments, types, and roles.

Categories ​

Manage ticket categories.

List Categories ​

GET /api/v1/settings/categories

Query Parameters:

  • search - Search in name
  • page, per_page, sort, order

Get Category ​

GET /api/v1/settings/categories/{id}

Create Category ​

POST /api/v1/settings/categories

Request Body:

json
{
  "name": "Technical Support",
  "description": "Technical issues and support"
}

Update Category ​

PUT /api/v1/settings/categories/{id}
PATCH /api/v1/settings/categories/{id}

Delete Category ​

DELETE /api/v1/settings/categories/{id}

Restore Category ​

POST /api/v1/settings/categories/{id}/restore

Priorities ​

Manage ticket priorities.

List Priorities ​

GET /api/v1/settings/priorities

Query Parameters:

  • search - Search in name
  • page, per_page, sort, order

Get Priority ​

GET /api/v1/settings/priorities/{id}

Create Priority ​

POST /api/v1/settings/priorities

Request Body:

json
{
  "name": "High",
  "color": "#ff0000"
}

Update Priority ​

PUT /api/v1/settings/priorities/{id}
PATCH /api/v1/settings/priorities/{id}

Delete Priority ​

DELETE /api/v1/settings/priorities/{id}

Restore Priority ​

POST /api/v1/settings/priorities/{id}/restore

Statuses ​

Manage ticket statuses.

List Statuses ​

GET /api/v1/settings/statuses

Query Parameters:

  • search - Search in name, slug
  • page, per_page, sort, order

Get Status ​

GET /api/v1/settings/statuses/{id}

Create Status ​

POST /api/v1/settings/statuses

Request Body:

json
{
  "name": "In Progress",
  "slug": "in_progress"
}

Note: Slug is auto-generated from name if not provided.

Update Status ​

PUT /api/v1/settings/statuses/{id}
PATCH /api/v1/settings/statuses/{id}

Request Body:

json
{
  "name": "In Progress",
  "slug": "in_progress"
}

Delete Status ​

DELETE /api/v1/settings/statuses/{id}

Restore Status ​

POST /api/v1/settings/statuses/{id}/restore

Departments ​

Manage departments.

List Departments ​

GET /api/v1/settings/departments

Query Parameters:

  • search - Search in name
  • page, per_page, sort, order

Get Department ​

GET /api/v1/settings/departments/{id}

Create Department ​

POST /api/v1/settings/departments

Request Body:

json
{
  "name": "Customer Support",
  "description": "Customer support department"
}

Update Department ​

PUT /api/v1/settings/departments/{id}
PATCH /api/v1/settings/departments/{id}

Delete Department ​

DELETE /api/v1/settings/departments/{id}

Restore Department ​

POST /api/v1/settings/departments/{id}/restore

Types ​

Manage ticket types.

List Types ​

GET /api/v1/settings/types

Query Parameters:

  • search - Search in name
  • page, per_page, sort, order

Get Type ​

GET /api/v1/settings/types/{id}

Create Type ​

POST /api/v1/settings/types

Request Body:

json
{
  "name": "Bug Report"
}

Update Type ​

PUT /api/v1/settings/types/{id}
PATCH /api/v1/settings/types/{id}

Delete Type ​

DELETE /api/v1/settings/types/{id}

Restore Type ​

POST /api/v1/settings/types/{id}/restore

Roles ​

Manage user roles and permissions.

List Roles ​

GET /api/v1/settings/roles

Query Parameters:

  • search - Search in name
  • page, per_page, sort, order

Get Role ​

GET /api/v1/settings/roles/{id}

Create Role ​

POST /api/v1/settings/roles

Request Body:

json
{
  "name": "Support Agent",
  "slug": "agent",
  "permissions": ["view_tickets", "create_tickets"]
}

Update Role ​

PUT /api/v1/settings/roles/{id}
PATCH /api/v1/settings/roles/{id}

Delete Role ​

DELETE /api/v1/settings/roles/{id}

Knowledge Base ​

Manage knowledge base articles.

List Articles ​

GET /api/v1/knowledge-base

Query Parameters:

  • search - Search in title, details
  • type_id - Filter by type
  • page, per_page, sort, order

Get Article ​

GET /api/v1/knowledge-base/{id}

Create Article ​

POST /api/v1/knowledge-base

Request Body:

json
{
  "title": "How to Reset Password",
  "type_id": 1,
  "details": "Step-by-step guide to reset your password..."
}

Update Article ​

PUT /api/v1/knowledge-base/{id}
PATCH /api/v1/knowledge-base/{id}

Delete Article ​

DELETE /api/v1/knowledge-base/{id}

FAQs ​

Manage frequently asked questions.

List FAQs ​

GET /api/v1/faqs

Get FAQ ​

GET /api/v1/faqs/{id}

Create FAQ ​

POST /api/v1/faqs

Request Body:

json
{
  "name": "How do I contact support?",
  "details": "You can contact support via email or phone...",
  "status": true
}

Update FAQ ​

PUT /api/v1/faqs/{id}
PATCH /api/v1/faqs/{id}

Delete FAQ ​

DELETE /api/v1/faqs/{id}

Restore FAQ ​

POST /api/v1/faqs/{id}/restore

Posts ​

Manage blog posts and articles.

List Posts ​

GET /api/v1/posts

Get Post ​

GET /api/v1/posts/{id}

Create Post ​

POST /api/v1/posts

Request Body:

json
{
  "title": "New Blog Post",
  "details": "Post content...",
  "excerpt": "Short excerpt",
  "type_id": 1,
  "is_active": true,
  "image": "path/to/image.jpg"
}

Update Post ​

PUT /api/v1/posts/{id}
PATCH /api/v1/posts/{id}

Delete Post ​

DELETE /api/v1/posts/{id}

Notes ​

Manage personal and shared notes.

List Notes ​

GET /api/v1/notes

Query Parameters:

  • search - Search in name, details
  • user_id - Filter by user
  • page, per_page

Get Note ​

GET /api/v1/notes/{id}

Create Note ​

POST /api/v1/notes

Request Body:

json
{
  "name": "Meeting Notes",
  "details": "Notes from the meeting...",
  "user_id": 1
}

Update Note ​

PUT /api/v1/notes/{id}
PATCH /api/v1/notes/{id}

Delete Note ​

DELETE /api/v1/notes/{id}

Dashboard ​

Access dashboard data, metrics, and analytics.

Get Dashboard Data ​

GET /api/v1/dashboard

Returns overview statistics and recent activity.

Get Metrics ​

GET /api/v1/dashboard/metrics

Returns key performance metrics.

Get Analytics ​

GET /api/v1/dashboard/analytics

Returns detailed analytics data.

Get Performance Data ​

GET /api/v1/dashboard/performance

Returns performance metrics and trends.

Get Charts Data ​

GET /api/v1/dashboard/charts

Returns data formatted for charting.

Reports ​

Generate and access reports.

List Reports ​

GET /api/v1/reports

Generate Report ​

POST /api/v1/reports/generate

Request Body:

json
{
  "type": "tickets",
  "date_from": "2025-01-01",
  "date_to": "2025-01-31",
  "format": "pdf"
}

Get Report ​

GET /api/v1/reports/{id}

AI Features ​

Access AI-powered features for intelligent automation.

Get AI Status ​

GET /api/v1/ai/status

Returns AI service status and configuration.

Get Analytics ​

GET /api/v1/ai/analytics

Returns AI analytics and insights.

Batch Classify Tickets ​

POST /api/v1/ai/batch-classify

Request Body:

json
{
  "ticket_ids": [1, 2, 3, 4, 5]
}

Get Settings ​

GET /api/v1/ai/settings

Update Settings ​

POST /api/v1/ai/settings

Response Suggestions ​

POST /api/v1/ai/response-suggestions

Request Body:

json
{
  "ticket_id": 1,
  "context": "Customer is asking about refund"
}

Sentiment Analysis ​

POST /api/v1/ai/sentiment-analysis

Request Body:

json
{
  "text": "I am very frustrated with this service"
}

Knowledge Base Suggestions ​

GET /api/v1/ai/knowledge-base/suggestions

Query Parameters:

  • query - Search query
  • limit - Number of suggestions

Get Ticket Suggestions ​

GET /api/v1/ai/tickets/{id}/suggestions

Classify Ticket ​

POST /api/v1/ai/tickets/{id}/classify

Apply Classification ​

POST /api/v1/ai/tickets/{id}/apply-classification

Request Body:

json
{
  "classification_id": 1
}

Get Classification History ​

GET /api/v1/ai/tickets/{id}/classification-history

Media ​

Manage file uploads and attachments.

List Media ​

GET /api/v1/media

Upload Media ​

POST /api/v1/media

Request: Multipart form data

  • file - File to upload (required)
  • ticket_id - Optional ticket association

Response:

json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "document.pdf",
    "size": 1024000,
    "path": "media/document.pdf",
    "ticket_id": 1,
    "created_at": "2025-01-15T10:30:00.000000Z"
  }
}

Get Media ​

GET /api/v1/media/{id}

Update Media ​

PUT /api/v1/media/{id}
PATCH /api/v1/media/{id}

Request Body:

json
{
  "name": "Updated Name",
  "ticket_id": 2
}

Delete Media ​

DELETE /api/v1/media/{id}

Notifications ​

Manage user notifications.

List Notifications ​

GET /api/v1/notifications

Query Parameters:

  • page, per_page
  • unread_only - Filter unread only

Mark as Read ​

POST /api/v1/notifications/{id}/read

Mark All as Read ​

POST /api/v1/notifications/read-all

Next Steps ​

For detailed request/response examples, see the Code Examples guide.

Released under the MIT License.

Copyright © 2025 HelpDesk Pro