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.

Submitting a ticket triggers the full AI pipeline synchronously: GPT-4o-mini classifies the problem and generates a suggested response, a hybrid RAG search retrieves the most relevant knowledge base articles, and GraphRAG pulls in related graph entities to enrich the response. The assembled ticket is persisted to PostgreSQL and returned in the 201 response. After the response is sent, entity extraction for GraphRAG is queued as a background job and does not block the caller.

​
Request

POST /api/v1/tickets

​
Body Parameters

​
user_description
string
required
The customer’s problem description. This string is passed directly to GPT-4o-mini for classification and is also used as the query for both hybrid RAG search and GraphRAG context retrieval. Cannot be empty or omitted.

​
Example

curl -X POST http://localhost:3001/api/v1/tickets \
  -H "Content-Type: application/json" \
  -d '{"user_description": "I cannot access my account after changing my email address"}'

​
Response (201 Created)

Returns the fully populated ticket object created in the database.
​
id
number
Auto-incremented ticket ID assigned by the database. Use this value in subsequent GET /api/v1/tickets/:id or PATCH /api/v1/tickets/:id calls.
​
user_description
string
The description submitted in the request body, stored verbatim.
​
category
string
AI-assigned support category. One of: Billing, Technical, Shipping, Returns, Account, or Other.
​
ai_suggested_response
string
The AI-generated response, enhanced with snippets from relevant knowledge base articles (up to the first 100 characters each) and a list of related graph entities extracted by GraphRAG.
​
confidence_score
number
Float between 0.0 and 1.0 representing GPT-4o-mini’s classification confidence. Tickets with a score ≥ 0.7 are automatically set to ai_resolved.
​
status
string
ai_resolved when confidence_score >= 0.7; otherwise pending_agent.
​
created_at
string
ISO 8601 UTC timestamp recording when the ticket was inserted into the database.
​
updated_at
string
ISO 8601 UTC timestamp of the most recent update to this ticket. Equals created_at on initial creation.

​
Example Response

{
  "id": 42,
  "user_description": "I cannot access my account after changing my email address",
  "category": "Account",
  "ai_suggested_response": "To regain access, please use the password reset flow...\n\nRelated articles:\n- Reset your password: Click 'Forgot Password' on the login page...",
  "confidence_score": 0.88,
  "status": "ai_resolved",
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

​
Error Responses

HTTP StatusCondition
400 Bad Requestuser_description is missing or empty in the request body. Response: {"error": "user_description is required"}
500 Internal Server ErrorDatabase write failed, AI service returned an unexpected error, or another unhandled exception occurred. Response: {"error": "Internal server error"}
GraphRAG entity extraction is asynchronous. After the 201 response is returned, the controller enqueues a background job (via BullMQ) to extract named entities from user_description and store them in the entities and entity_relations tables. This enriches future GraphRAG lookups but does not affect the current response. If the queue is unavailable the ticket is still created successfully — only the entity job is skipped.

Build docs developers (and LLMs) love

Get started for freeTalk to us