Support Tickets API — Create, Update & Comment

The Tickets API lets you create and manage support tickets programmatically. Every ticket gets a unique tracking code (format: TK-XXXXXXXX) and automatic priority assignment. All endpoints under /api/tickets require a valid Bearer token.

GET /api/tickets

Returns a paginated list of tickets belonging to the authenticated user. Tickets are matched by both user ID and email address, so tickets submitted via email that share your account email are also included. Authentication: Required — Authorization: Bearer {token}

Query Parameters

string

Filter by ticket status. Accepted values: open, in-progress, closed.

string

Filter by priority. Accepted values: low, normal, high.

string

Filter by category string (exact match).

string

Search term matched against the tracking code, subject, and message body.

integer

Number of tickets per page. Defaults to 15.

Response Fields

boolean

true on success.

array

Array of ticket summary objects for the current page.

integer

Unique ticket ID.

string

Human-readable tracking code, e.g. TK-A3BF92C1.

string

Ticket subject line.

string

Current status: open, in-progress, or closed.

string

Priority level: low, normal, or high.

string

Optional category string, or null.

object

The staff member assigned to the ticket, or null. Contains id, first_name, last_name.

array

Array of tag objects with id and name.

string

ISO 8601 creation timestamp.

object

Pagination metadata: current_page, last_page, per_page, total.

Example Request

curl -X GET "https://your-domain.com/api/tickets?status=open&per_page=10" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 34,
      "tracking_code": "TK-A3BF92C1",
      "subject": "Unable to upload project documents",
      "status": "open",
      "priority": "high",
      "category": "technical",
      "assignee": {
        "id": 5,
        "first_name": "Sara",
        "last_name": "Tehrani"
      },
      "tags": [
        { "id": 2, "name": "upload" }
      ],
      "created_at": "2024-11-14T08:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 10,
    "total": 27
  }
}

Error Responses

Unauthenticated — 401:

{
  "message": "Unauthenticated."
}

GET /api/tickets/stats

Returns a summary count of your tickets broken down by status. Useful for dashboard widgets. Authentication: Required — Authorization: Bearer {token} Request: No parameters.

Response Fields

boolean

true on success.

integer

Total number of tickets associated with your account.

integer

Tickets with status open.

integer

Tickets with status in-progress.

integer

Tickets with status closed.

Example Request

curl -X GET https://your-domain.com/api/tickets/stats \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "data": {
    "total": 27,
    "open": 12,
    "in_progress": 4,
    "closed": 11
  }
}

POST /api/tickets

Creates a new support ticket. The system automatically assigns a unique tracking code and calculates a priority if you do not specify one. A confirmation email is sent to the authenticated user’s email address upon creation. Authentication: Required — Authorization: Bearer {token}

Request Body

string

required

A clear, concise summary of the issue. Maximum 255 characters.

string

required

Detailed description of the issue. Minimum 10 characters.

string

Requested priority: low, normal, or high. If omitted, the platform assigns one automatically based on the subject and message content.

string

Optional category string to help route the ticket.

array

Optional array of tag IDs (integers) to attach to the ticket.

array

Optional array of file uploads. Each file must be under 10 MB. Accepted types: jpg, jpeg, png, gif, pdf, doc, docx, txt, zip, rar.

Response Fields

boolean

true when the ticket is created.

string

Confirmation message.

object

The full newly created ticket object including tracking code, assignee, tags, and attachments.

integer

Ticket ID.

string

Unique tracking code, e.g. TK-B7CE41F2.

string

Always open for a newly created ticket.

string

Assigned priority: low, normal, or high.

string

ISO 8601 timestamp of the resolution deadline.

Example Request

curl -X POST https://your-domain.com/api/tickets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Unable to upload project documents",
    "message": "When I try to upload a PDF on the project creation form the page shows a 500 error after selecting the file.",
    "priority": "high",
    "category": "technical"
  }'

curl -X POST https://your-domain.com/api/tickets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -F "subject=Unable to upload project documents" \
  -F "message=When I try to upload a PDF the page shows a 500 error." \
  -F "priority=high" \
  -F "attachments[]=@/path/to/screenshot.png"

Example Response

{
  "success": true,
  "message": "Ticket created successfully.",
  "data": {
    "id": 35,
    "tracking_code": "TK-B7CE41F2",
    "subject": "Unable to upload project documents",
    "message": "When I try to upload a PDF on the project creation form...",
    "status": "open",
    "priority": "high",
    "category": "technical",
    "sla_deadline": "2024-11-16T08:30:00Z",
    "assignee": null,
    "tags": [],
    "attachments": [],
    "created_at": "2024-11-14T08:30:00Z"
  }
}

Error Responses

Validation failure — 422:

{
  "success": false,
  "message": "Validation error.",
  "errors": {
    "subject": ["The subject field is required."],
    "message": ["The message must be at least 10 characters."]
  }
}

GET /api/tickets/

Returns full details for a single ticket, including the complete comment thread, all attachments, tags, and activity log. You may only view tickets associated with your account. Authentication: Required — Authorization: Bearer {token}

Path Parameters

integer

required

The ticket ID to retrieve.

Response Fields

boolean

true on success.

object

The full ticket object.

array

Chronologically ordered array of comment objects, each containing id, user, message, attachments, and created_at.

array

Array of attachment objects: id, file_name, file_type, file_size, created_at.

array

Audit trail of status changes and field updates.

Example Request

curl -X GET https://your-domain.com/api/tickets/35 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "data": {
    "id": 35,
    "tracking_code": "TK-B7CE41F2",
    "subject": "Unable to upload project documents",
    "message": "When I try to upload a PDF...",
    "status": "open",
    "priority": "high",
    "category": "technical",
    "sla_deadline": "2024-11-16T08:30:00Z",
    "assignee": { "id": 5, "first_name": "Sara", "last_name": "Tehrani", "email": "sara@example.com" },
    "user": { "id": 12, "first_name": "Ali", "last_name": "Mohammadi", "email": "ali@example.com" },
    "comments": [],
    "tags": [],
    "attachments": [],
    "activities": [],
    "created_at": "2024-11-14T08:30:00Z"
  }
}

Error Responses

Ticket not found or not owned by you — 404:

{
  "message": "No query results for model [Ticket] 35."
}

PUT /api/tickets/

Updates the priority and/or category of an open ticket. Closed tickets cannot be edited. The resolution deadline is recalculated automatically when priority changes. Authentication: Required — Authorization: Bearer {token}

Path Parameters

integer

required

The ticket ID to update.

Request Body

string

New priority. One of: low, normal, high.

string

New category string. Pass null to clear the category.

Example Request

curl -X PUT https://your-domain.com/api/tickets/35 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"priority": "normal"}'

Example Response

{
  "success": true,
  "message": "Ticket updated successfully.",
  "data": {
    "id": 35,
    "tracking_code": "TK-B7CE41F2",
    "priority": "normal",
    "sla_deadline": "2024-11-18T08:30:00Z",
    "status": "open"
  }
}

Error Responses

Attempting to edit a closed ticket — 400:

{
  "success": false,
  "message": "Cannot edit a closed ticket."
}

Validation failure — 422:

{
  "success": false,
  "message": "Validation error.",
  "errors": {
    "priority": ["The selected priority is invalid."]
  }
}

PUT /api/tickets//close

Closes an open ticket and records the resolution timestamp. Once closed, the ticket cannot be edited, but adding a new comment will automatically reopen it. Authentication: Required — Authorization: Bearer {token}

Path Parameters

integer

required

The ticket ID to close.

Request: No body required.

Example Request

curl -X PUT https://your-domain.com/api/tickets/35/close \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "message": "Ticket closed successfully.",
  "data": {
    "id": 35,
    "status": "closed",
    "resolved_at": "2024-11-15T14:22:00Z"
  }
}

Error Responses

Ticket is already closed — 400:

{
  "success": false,
  "message": "Ticket is already closed."
}

POST /api/tickets//comments

Adds a comment to an existing ticket. If the ticket was closed, adding a comment automatically reopens it. Attachments may be uploaded together with the comment as multipart form data. Authentication: Required — Authorization: Bearer {token}

Path Parameters

integer

required

The ticket ID to comment on.

Request Body

string

required

Comment text. Minimum 5 characters.

array

Optional array of file uploads. Each file must be under 10 MB. Accepted types: jpg, jpeg, png, gif, pdf, doc, docx, txt, zip, rar.

Response Fields

boolean

true when the comment is saved.

string

Confirmation message.

object

The new comment object, including id, ticket_id, user, message, attachments, and created_at.

Example Request

curl -X POST https://your-domain.com/api/tickets/35/comments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"message": "I have tried clearing my browser cache and the error persists."}'

Example Response

{
  "success": true,
  "message": "Comment added successfully.",
  "data": {
    "id": 88,
    "ticket_id": 35,
    "message": "I have tried clearing my browser cache and the error persists.",
    "user": { "id": 12, "first_name": "Ali", "last_name": "Mohammadi" },
    "attachments": [],
    "created_at": "2024-11-15T10:05:00Z"
  }
}

Error Responses

Validation failure — 422:

{
  "success": false,
  "message": "Validation error.",
  "errors": {
    "message": ["The message must be at least 5 characters."]
  }
}

GET /api/tickets//attachments//download

Downloads a file attachment associated with a ticket. Returns the raw file with appropriate Content-Disposition and Content-Type headers. You may only download attachments on tickets associated with your account. Authentication: Required — Authorization: Bearer {token}

Path Parameters

integer

required

The ticket ID that owns the attachment.

integer

required

The attachment ID to download.

Response

On success the response body is the raw file binary (not JSON). Use the Content-Disposition header to obtain the original file name.

Example Request

curl -X GET https://your-domain.com/api/tickets/35/attachments/14/download \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output screenshot.png

Error Responses

File no longer exists on the server — 404:

{
  "success": false,
  "message": "File not found."
}

​GET /api/tickets

​Query Parameters

​Response Fields

​Example Request

​Example Response

​Error Responses

​GET /api/tickets/stats

​Response Fields

​Example Request

​Example Response

​POST /api/tickets

​Request Body

​Response Fields

​Example Request

​Example Response

​Error Responses

​GET /api/tickets/

​Path Parameters

​Response Fields

​Example Request

​Example Response

​Error Responses

​PUT /api/tickets/

​Path Parameters

​Request Body

​Example Request

​Example Response

​Error Responses

​PUT /api/tickets//close

​Path Parameters

​Example Request

​Example Response

​Error Responses

​POST /api/tickets//comments

​Path Parameters

​Request Body

​Response Fields

​Example Request

​Example Response

​Error Responses

​GET /api/tickets//attachments//download

​Path Parameters

​Response

​Example Request

​Error Responses

GET /api/tickets

Query Parameters

Response Fields

Example Request

Example Response

Error Responses

GET /api/tickets/stats

Response Fields

Example Request

Example Response

POST /api/tickets

Request Body

Response Fields

Example Request

Example Response

Error Responses

GET /api/tickets/

Path Parameters

Response Fields

Example Request

Example Response

Error Responses

PUT /api/tickets/

Path Parameters

Request Body

Example Request

Example Response

Error Responses

PUT /api/tickets//close

Path Parameters

Example Request

Example Response

Error Responses

POST /api/tickets//comments

Path Parameters

Request Body

Response Fields

Example Request

Example Response

Error Responses

GET /api/tickets//attachments//download

Path Parameters

Response

Example Request

Error Responses