Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/yocxy2/2a/llms.txt

Use this file to discover all available pages before exploring further.

The AI Ticket Support System exposes a REST API that powers ticket creation, classification, retrieval, and management. When a ticket is submitted, the API synchronously runs GPT-4o-mini classification, hybrid RAG search against the knowledge base, and GraphRAG entity-context retrieval before persisting the result. Every response body is JSON.

​
Base URL

http://localhost:3001/api/v1
When running via Docker Compose the backend container is published on host port 3001. All ticket endpoints are prefixed with /api/v1. The health check endpoint sits at /api/health (outside the versioned prefix).

​
Content Type

All requests that carry a body must include the header: 
Content-Type: application/json
All successful responses are returned with Content-Type: application/json.

​
Endpoints Summary

MethodPathDescription
POST/api/v1/ticketsCreate a ticket and trigger AI classification
GET/api/v1/ticketsList all tickets, optionally filtered by status
GET/api/v1/tickets/:idGet a specific ticket by its numeric ID
PATCH/api/v1/tickets/:idUpdate ticket status, category, or response
GET/api/healthHealth check — returns service status and timestamp

​
Ticket Object

Every ticket endpoint returns objects that conform to the following TypeScript interface, which mirrors the Prisma Ticket model backed by PostgreSQL: 
interface Ticket {
  id?: number;                           // Auto-incremented primary key
  user_description: string;             // Original user problem description
  category?: string;                    // AI-assigned: Billing, Technical, Shipping, Returns, Account, Other
  ai_suggested_response?: string;       // AI-generated response with RAG context
  confidence_score?: number;            // 0.0–1.0 AI confidence; ≥0.7 = auto-resolved
  status: 'ai_resolved' | 'pending_agent' | 'closed'; // Ticket lifecycle status
  created_at?: Date;                    // Timestamp set on creation
  updated_at?: Date;                    // Timestamp updated on every write
}

​
Field descriptions

FieldTypeDescription
idnumberAuto-incremented primary key assigned by the database.
user_descriptionstringThe raw problem description submitted by the customer.
categorystring | nullAI-assigned support category. One of: Billing, Technical, Shipping, Returns, Account, Other. null until classification runs.
ai_suggested_responsestring | nullGPT-4o-mini response enriched with matching knowledge base articles and GraphRAG entity context. null until classification runs.
confidence_scorenumber | nullFloat between 0.0 and 1.0 representing AI classification confidence. Tickets with a score ≥ 0.7 are automatically set to ai_resolved.
statusstringLifecycle status. ai_resolved — handled automatically; pending_agent — needs human review; closed — resolved and closed. Default on creation is pending_agent, overridden by the confidence threshold.
created_atstringISO 8601 UTC timestamp set at row insertion.
updated_atstringISO 8601 UTC timestamp updated automatically on every write.

​
Error Responses

All error responses share a single-field JSON envelope: 
{ "error": "<error message string>" }
HTTP StatusWhen it occurs
400 Bad RequestA required field is missing (e.g. user_description) or no valid update fields were provided.
404 Not FoundThe requested ticket ID does not exist in the database.
500 Internal Server ErrorAn unexpected server-side error occurred (database failure, AI service error, etc.).

​
Explore Endpoints

Create Ticket

POST /api/v1/tickets — Submit a ticket and trigger the full AI pipeline.

List Tickets

GET /api/v1/tickets — Retrieve all tickets, with optional status filtering.

Get Ticket

GET /api/v1/tickets/:id — Fetch a single ticket by its numeric ID.

Update Ticket

PATCH /api/v1/tickets/:id — Update status, category, or AI response.

Build docs developers (and LLMs) love

Get started for freeTalk to us