Introduction

Welcome to the Support API documentation. This API allows you to manage support tickets, retrieve categories, and more.

Base URL: https://api.example.com/v1/support

Authentication: All requests must be authenticated using an API key passed in the X-API-Key header.

Tickets

GET /tickets

Retrieves a list of all support tickets.

Query Parameters

Name Type Description Required
status String Filter tickets by their status (e.g., open, closed, in_progress). No
assignee_id Integer Filter tickets assigned to a specific user ID. No

Responses

Success (200 OK)
[
    {
        "id": 101,
        "subject": "Login Issue",
        "description": "User cannot log in to their account.",
        "status": "open",
        "priority": "high",
        "category": "account",
        "created_at": "2023-10-27T10:00:00Z",
        "updated_at": "2023-10-27T10:00:00Z",
        "assignee_id": 5
    },
    {
        "id": 102,
        "subject": "Feature Request: Dark Mode",
        "description": "Request for a dark mode option in the user interface.",
        "status": "closed",
        "priority": "low",
        "category": "ui",
        "created_at": "2023-10-26T15:30:00Z",
        "updated_at": "2023-10-27T09:00:00Z",
        "assignee_id": null
    }
]
Unauthorized (401 Unauthorized)

API key is missing or invalid.

POST /tickets

Creates a new support ticket.

Request Body

Field Type Description Required
subject String The subject of the support ticket. Yes
description String A detailed description of the issue or request. Yes
priority String The priority level (e.g., low, medium, high, urgent). No (defaults to medium)
category_id Integer The ID of the category this ticket belongs to. No 
{
    "subject": "Password Reset Needed",
    "description": "I forgot my password and need to reset it.",
    "priority": "high",
    "category_id": 3
}

Responses

Created (201 Created)

The ticket was successfully created.

{
    "id": 103,
    "subject": "Password Reset Needed",
    "description": "I forgot my password and need to reset it.",
    "status": "open",
    "priority": "high",
    "category": {"id": 3, "name": "Account Access"},
    "created_at": "2023-10-27T11:00:00Z",
    "updated_at": "2023-10-27T11:00:00Z",
    "assignee_id": null
}
Bad Request (400 Bad Request)

Invalid input data.

Unauthorized (401 Unauthorized)

API key is missing or invalid.

GET /tickets/{ticket_id}

Retrieves a specific support ticket by its ID.

Path Parameters

Name Type Description Required
ticket_id Integer The unique identifier of the ticket. Yes

Responses

OK (200 OK)
{
    "id": 101,
    "subject": "Login Issue",
    "description": "User cannot log in to their account.",
    "status": "open",
    "priority": "high",
    "category": "account",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:00:00Z",
    "assignee_id": 5,
    "comments": [
        {
            "id": 201,
            "author": "user@example.com",
            "content": "This started happening this morning.",
            "created_at": "2023-10-27T10:05:00Z"
        },
        {
            "id": 202,
            "author": "agent@example.com",
            "content": "We are investigating this issue.",
            "created_at": "2023-10-27T10:15:00Z"
        }
    ]
}
Not Found (404 Not Found)

The ticket with the specified ID was not found.

Unauthorized (401 Unauthorized)

API key is missing or invalid.

PUT /tickets/{ticket_id}

Updates an existing support ticket.

Path Parameters

Name Type Description Required
ticket_id Integer The unique identifier of the ticket to update. Yes

Request Body

Fields to update. All fields are optional.

Field Type Description
subject String The new subject of the ticket.
description String The new description of the ticket.
status String The new status (e.g., open, closed, in_progress).
priority String The new priority level.
category_id Integer The ID of the new category.
assignee_id Integer / null The ID of the user to assign the ticket to, or null to unassign. 
{
    "status": "closed",
    "assignee_id": null
}

Responses

OK (200 OK)

The ticket was successfully updated.

{
    "id": 101,
    "subject": "Login Issue",
    "description": "User cannot log in to their account.",
    "status": "closed",
    "priority": "high",
    "category": "account",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T11:30:00Z",
    "assignee_id": null
}
Not Found (404 Not Found)

The ticket with the specified ID was not found.

Bad Request (400 Bad Request)

Invalid input data.

Unauthorized (401 Unauthorized)

API key is missing or invalid.

DELETE /tickets/{ticket_id}

Deletes a support ticket. This action is irreversible.

Path Parameters

Name Type Description Required
ticket_id Integer The unique identifier of the ticket to delete. Yes

Responses

No Content (204 No Content)

The ticket was successfully deleted.

Not Found (404 Not Found)

The ticket with the specified ID was not found.

Unauthorized (401 Unauthorized)

API key is missing or invalid.

Lookups

GET /categories

Retrieves a list of available ticket categories.

Responses

OK (200 OK)
[
    {"id": 1, "name": "Account Access"},
    {"id": 2, "name": "Billing Inquiry"},
    {"id": 3, "name": "Technical Support"},
    {"id": 4, "name": "Feature Request"},
    {"id": 5, "name": "General Question"}
]
Unauthorized (401 Unauthorized)

API key is missing or invalid.

GET /priorities

Retrieves a list of available ticket priorities.

Responses

OK (200 OK)
[
    {"id": 1, "name": "Low"},
    {"id": 2, "name": "Medium"},
    {"id": 3, "name": "High"},
    {"id": 4, "name": "Urgent"}
]
Unauthorized (401 Unauthorized)

API key is missing or invalid.