Skip to main content

Ticketing Platform API Reference

This document provides a comprehensive reference for the Ticketing Platform API endpoints.

Base URL​

All API endpoints are relative to the base URL:

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

For local development:

http://localhost:3000/api/v1

Authentication​

Most API endpoints require authentication. The API uses JWT (JSON Web Tokens) for authentication.

Include the JWT token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Getting a Token​

To obtain a JWT token, use the login endpoint:

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

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

#### Create Ticket

```http
POST /tickets
Content-Type: application/json

{
  "title": "Cannot export reports",
  "description": "The export button doesn't work when I try to export monthly reports",
  "priority": "medium",
  "tags": ["reports", "export"],
  "custom_fields": {
    "browser": "Firefox 102.0",
    "os": "MacOS 13.4"
  },
  "attachments": [
    {
      "filename": "error_log.txt",
      "content": "base64_encoded_content...",
      "mime_type": "text/plain"
    }
  ]
}

Response:

{
  "data": {
    "id": "ticket124",
    "title": "Cannot export reports",
    "description": "The export button doesn't work when I try to export monthly reports",
    "status": "open",
    "priority": "medium",
    "created_at": "2025-05-04T14:25:00Z",
    "updated_at": "2025-05-04T14:25:00Z",
    "created_by": {
      "id": "user456",
      "name": "Jane Smith",
      "email": "jane@example.com"
    },
    "assigned_to": null,
    "tags": ["reports", "export"],
    "custom_fields": {
      "browser": "Firefox 102.0",
      "os": "MacOS 13.4"
    }
  }
}

Update Ticket​

PATCH /tickets/{ticket_id}
Content-Type: application/json

{
  "status": "in_progress",
  "priority": "high",
  "assigned_to": "agent789"
}

Response:

{
  "data": {
    "id": "ticket123",
    "title": "Cannot access customer dashboard",
    "description": "I'm getting a 404 error when trying to access the dashboard",
    "status": "in_progress",
    "priority": "high",
    "created_at": "2025-05-01T09:30:00Z",
    "updated_at": "2025-05-04T15:10:00Z",
    "created_by": {
      "id": "user456",
      "name": "Jane Smith",
      "email": "jane@example.com"
    },
    "assigned_to": {
      "id": "agent789",
      "name": "Support Agent",
      "email": "agent@example.com"
    },
    "tags": ["dashboard", "access", "error"]
  }
}

Delete Ticket​

DELETE /tickets/{ticket_id}

Response:

204 No Content

Comments​

Add Comment to Ticket​

POST /tickets/{ticket_id}/comments
Content-Type: application/json

{
  "content": "I've checked the server logs and found the issue.",
  "is_internal": true,
  "attachments": [
    {
      "filename": "server_logs.txt",
      "content": "base64_encoded_content...",
      "mime_type": "text/plain"
    }
  ]
}

Response:

{
  "data": {
    "id": "comment125",
    "content": "I've checked the server logs and found the issue.",
    "created_at": "2025-05-04T16:05:00Z",
    "created_by": {
      "id": "agent789",
      "name": "Support Agent",
      "email": "agent@example.com"
    },
    "is_internal": true,
    "attachments": [
      {
        "id": "attach124",
        "filename": "server_logs.txt",
        "size": 15240,
        "mime_type": "text/plain",
        "url": "https://api.example.com/files/server_logs.txt",
        "created_at": "2025-05-04T16:05:00Z"
      }
    ]
  }
}

Users​

List Users​

GET /users

Query parameters:

ParameterTypeDescription
rolestringFilter by role (admin, agent, customer)
statusstringFilter by status (active, inactive)
qstringSearch in name and email

Response:

{
  "data": [
    {
      "id": "user789",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "admin",
      "status": "active",
      "created_at": "2024-12-01T00:00:00Z",
      "last_login_at": "2025-05-03T08:15:00Z"
    },
    // More users...
  ],
  "pagination": {
    // Pagination data
  }
}

Webhooks​

The API supports webhooks for real-time event notifications.

Available Events​

  • ticket.created - When a new ticket is created
  • ticket.updated - When a ticket is updated
  • ticket.status_changed - When a ticket's status changes
  • comment.created - When a comment is added to a ticket
  • user.created - When a new user is registered

Webhook Payload Example​

{
  "event": "ticket.status_changed",
  "timestamp": "2025-05-04T16:30:00Z",
  "data": {
    "ticket": {
      "id": "ticket123",
      "title": "Cannot access customer dashboard",
      "status": {
        "previous": "open",
        "current": "in_progress"
      },
      "updated_by": {
        "id": "agent789",
        "name": "Support Agent",
        "email": "agent@example.com"
      }
    }
  }
}

Rate Limiting​

The API implements rate limiting to prevent abuse. Rate limits are applied on a per-API key basis.

Current rate limits:

  • 100 requests per minute for standard accounts
  • 300 requests per minute for premium accounts

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1714997400

When the rate limit is exceeded, the API returns a 429 Too Many Requests response.

API Versioning​

The API is versioned in the URL path (e.g., /v1/tickets).

When breaking changes are introduced, a new API version will be released. Older versions will remain available for a deprecation period of at least 6 months.


Response:

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-06-04T12:00:00Z",
  "user": {
    "id": "user123",
    "name": "John Doe",
    "email": "user@example.com",
    "role": "agent"
  }
}

Error Handling​

The API uses standard HTTP status codes to indicate the success or failure of requests.

Common error codes:

  • 400 - Bad Request (invalid input)
  • 401 - Unauthorized (authentication required)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found (resource doesn't exist)
  • 409 - Conflict (resource already exists)
  • 422 - Unprocessable Entity (validation error)
  • 500 - Internal Server Error

Error response format:

{
  "error": {
    "code": "invalid_input",
    "message": "The request data is invalid",
    "details": [
      {
        "field": "priority",
        "message": "Priority must be one of: low, medium, high, critical"
      }
    ]
  }
}

Pagination​

List endpoints support pagination with the following query parameters:

  • page - Page number (default: 1)
  • per_page - Items per page (default: 20, max: 100)

Response format for paginated results:

{
  "data": [...],
  "pagination": {
    "total": 243,
    "per_page": 20,
    "current_page": 1,
    "last_page": 13,
    "next_page_url": "/api/v1/tickets?page=2",
    "prev_page_url": null
  }
}

Endpoints​

Tickets​

List Tickets​

GET /tickets

Query parameters:

ParameterTypeDescription
statusstringFilter by status (open, in_progress, resolved, closed)
prioritystringFilter by priority (low, medium, high, critical)
assigned_tostringFilter by agent ID
created_bystringFilter by creator ID
qstringSearch in title and description
sortstringSort field (created_at, updated_at, priority)
orderstringSort order (asc, desc)

Response:

{
  "data": [
    {
      "id": "ticket123",
      "title": "Cannot access customer dashboard",
      "description": "I'm getting a 404 error when trying to access the dashboard",
      "status": "open",
      "priority": "high",
      "created_at": "2025-05-01T09:30:00Z",
      "updated_at": "2025-05-01T09:30:00Z",
      "created_by": {
        "id": "user456",
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "assigned_to": {
        "id": "agent789",
        "name": "Support Agent",
        "email": "agent@example.com"
      },
      "tags": ["dashboard", "access", "error"]
    },
    // More tickets...
  ],
  "pagination": {
    // Pagination data
  }
}

Get Ticket​

GET /tickets/{ticket_id}

Response:

{
  "data": {
    "id": "ticket123",
    "title": "Cannot access customer dashboard",
    "description": "I'm getting a 404 error when trying to access the dashboard",
    "status": "open",
    "priority": "high",
    "created_at": "2025-05-01T09:30:00Z",
    "updated_at": "2025-05-01T09:30:00Z",
    "created_by": {
      "id": "user456",
      "name": "Jane Smith",
      "email": "jane@example.com"
    },
    "assigned_to": {
      "id": "agent789",
      "name": "Support Agent",
      "email": "agent@example.com"
    },
    "tags": ["dashboard", "access", "error"],
    "comments": [
      {
        "id": "comment123",
        "content": "I've tried clearing my browser cache but still having the issue.",
        "created_at": "2025-05-01T10:15:00Z",
        "created_by": {
          "id": "user456",
          "name": "Jane Smith",
          "email": "jane@example.com"
        },
        "is_internal": false
      },
      {
        "id": "comment124",
        "content": "Looking into this issue. Could be related to the recent deployment.",
        "created_at": "2025-05-01T10:30:00Z",
        "created_by": {
          "id": "agent789",
          "name": "Support Agent",
          "email": "agent@example.com"
        },
        "is_internal": true
      }
    ],
    "attachments": [
      {
        "id": "attach123",
        "filename": "error_screenshot.png",
        "size": 258940,
        "mime_type": "image/png",
        "url": "https://api.example.com/files/error_screenshot.png",
        "created_at": "2025-05-01T09:30:00Z"
      }
    ],
    "custom_fields": {
      "browser": "Chrome 112.0",
      "os": "Windows 11",
      "product_area": "Dashboard"
    }
  }
}"