REST API - Getting Started

Welcome to the HelpDesk Pro REST API documentation! This guide will help you get started with integrating your applications with our powerful API.

📋 Table of Contents

• Overview
• Base URL
• API Versioning
• Authentication
• Response Format
• Rate Limiting
• Quick Start
• Next Steps

---

Overview

The HelpDesk Pro REST API provides programmatic access to all features of the helpdesk system. You can use it to:

• Manage Tickets - Create, update, and track support tickets
• Handle Contacts - Manage customer and contact information
• User Management - Control user accounts and permissions
• Real-time Data - Access dashboards, reports, and analytics
• AI Features - Leverage AI-powered classification and suggestions
• And Much More - Full access to all system features

Key Features

• ✅ RESTful Design - Follows REST conventions for intuitive usage
• ✅ Token-Based Authentication - Secure using Laravel Sanctum
• ✅ Standardized Responses - Consistent JSON format across all endpoints
• ✅ Comprehensive Error Handling - Clear error messages with proper HTTP status codes
• ✅ Rate Limiting - Built-in protection against abuse
• ✅ Pagination - Efficient handling of large datasets
• ✅ Filtering & Sorting - Flexible query options

---

Base URL

All API requests should be made to:

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

Replace your-domain.com with your actual HelpDesk Pro installation domain.

Example

If your helpdesk is installed at https://helpdesk.example.com, your API base URL would be:

https://helpdesk.example.com/api/v1

---

API Versioning

The API uses URL-based versioning. The current version is v1, which is included in the base URL:

/api/v1/tickets
/api/v1/contacts
/api/v1/users

Future versions will be available at /api/v2, /api/v3, etc., ensuring backward compatibility.

---

Authentication

The API uses Laravel Sanctum for token-based authentication. Most endpoints require authentication.

Getting an Access Token

1. Login to get your access token:

POST /api/v1/auth/login
Content-Type: application/json

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

2. Response includes your token:

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "user@example.com",
      ...
    },
    "token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "v1"
  }
}

3. Use the token in subsequent requests:

Authorization: Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Token Expiration

Tokens do not expire by default, but you can:

• Logout to revoke a token: POST /api/v1/auth/logout
• Get current user: GET /api/v1/auth/me

📝 Note: Keep your tokens secure. Never expose them in client-side code or public repositories.

For detailed authentication information, see the Authentication Guide.

---

Response Format

All API responses follow a consistent structure:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "v1"
  }
}

Paginated Response

{
  "success": true,
  "data": [
    // Array of items
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 15,
      "total": 100,
      "last_page": 7,
      "from": 1,
      "to": 15
    },
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "v1"
  }
}

Error Response

{
  "success": false,
  "message": "Error description",
  "errors": {
    "field_name": ["Error message"]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "v1"
  }
}

---

Rate Limiting

To ensure fair usage and system stability, the API implements rate limiting:

• General API: 60 requests per minute per user/IP
• Authentication: 5 requests per minute per IP

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
Retry-After: 15

When you exceed the rate limit, you'll receive a 429 Too Many Requests response.

---

Quick Start

Let's make your first API call! This example shows how to retrieve a list of tickets.

Step 1: Get Authentication Token

curl -X POST https://your-domain.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response:

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

Step 2: Use the Token

curl -X GET https://your-domain.com/api/v1/tickets \
  -H "Authorization: Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "uid": "100001",
      "subject": "Need help with login",
      "status": {...},
      "priority": {...},
      ...
    }
  ],
  "meta": {
    "pagination": {...},
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "v1"
  }
}

Step 3: Create a Ticket

curl -X POST https://your-domain.com/api/v1/tickets \
  -H "Authorization: Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "subject": "API Test Ticket",
    "details": "This ticket was created via API",
    "priority_id": 1,
    "category_id": 1
  }'

---

Next Steps

Now that you understand the basics, explore more:

1. Authentication Guide - Detailed authentication documentation
2. API Endpoints - Complete list of all available endpoints
3. Code Examples - Ready-to-use code samples
4. Error Handling - Understanding API errors
5. Rate Limiting - Managing API usage limits

---

Support

Need help? We're here for you:

• 📖 Documentation: Browse the complete API documentation
• 💬 Support: Contact our support team
• 🐛 Issues: Report bugs or request features

---

Happy coding! 🚀