Tickets API | Keva Docs

The Tickets API allows you to create, retrieve, update, and list support tickets programmatically.

Endpoints

Method	Endpoint	Description
GET	`/api/v1/tickets`	List tickets
POST	`/api/v1/tickets`	Create a ticket
GET	`/api/v1/tickets/:id`	Get a ticket
PATCH	`/api/v1/tickets/:id`	Update a ticket
GET	`/api/v1/tickets/:id/messages`	List messages
POST	`/api/v1/tickets/:id/messages`	Add a message

List Tickets

Retrieve a paginated list of tickets.

GET /api/v1/tickets

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (max: 100, default: 20)
`status`	string	Filter by status: `open`, `pending`, `solved`, `closed`
`workspace_id`	string	Filter by workspace

Example Request

curl "https://app.keva.support/api/v1/tickets?status=open&per_page=10" \
  -H "Authorization: Bearer keva_live_your_api_key"

Example Response

{
  "data": [
    {
      "id": "tkt_abc123",
      "subject": "Cannot access my account",
      "status": "open",
      "priority": "high",
      "customerEmail": "customer@example.com",
      "customerName": "John Doe",
      "source": "email",
      "assignedTo": null,
      "resolutionType": null,
      "tags": ["login", "urgent"],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 10,
    "total": 45
  }
}

Create Ticket

Create a new support ticket.

POST /api/v1/tickets

Request Body

Field	Type	Required	Description
`subject`	string	Yes	Ticket subject line
`customerEmail`	string	Yes	Customer's email address
`customerName`	string	No	Customer's name
`body`	string	Yes	Initial message content
`source`	string	No	Source identifier (default: `api`)

Example Request

curl https://app.keva.support/api/v1/tickets \
  -H "Authorization: Bearer keva_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Order not delivered",
    "customerEmail": "customer@example.com",
    "customerName": "Jane Smith",
    "body": "My order #12345 was supposed to arrive yesterday but I havent received it yet."
  }'

Example Response

{
  "data": {
    "id": "tkt_xyz789",
    "subject": "Order not delivered",
    "status": "open",
    "priority": "medium",
    "customerEmail": "customer@example.com",
    "customerName": "Jane Smith",
    "source": "api",
    "createdAt": "2024-01-15T14:22:00Z"
  }
}

Get Ticket

Retrieve a single ticket by ID.

GET /api/v1/tickets/:id

Example Request

curl https://app.keva.support/api/v1/tickets/tkt_abc123 \
  -H "Authorization: Bearer keva_live_your_api_key"

Update Ticket

Update ticket properties.

PATCH /api/v1/tickets/:id

Request Body

Field	Type	Description
`status`	string	`open`, `pending`, `solved`, `closed`
`priority`	string	`low`, `medium`, `high`, `urgent`
`assignedTo`	string	User ID to assign

Example Request

curl -X PATCH https://app.keva.support/api/v1/tickets/tkt_abc123 \
  -H "Authorization: Bearer keva_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "pending", "priority": "high"}'

List Messages

Get all messages for a ticket.

GET /api/v1/tickets/:id/messages

Example Response

{
  "data": [
    {
      "id": "msg_001",
      "ticketId": "tkt_abc123",
      "direction": "inbound",
      "senderEmail": "customer@example.com",
      "senderName": "John Doe",
      "body": "I need help with my order",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "msg_002",
      "ticketId": "tkt_abc123",
      "direction": "outbound",
      "senderEmail": "support@company.com",
      "body": "Happy to help! Let me look into this.",
      "createdAt": "2024-01-15T10:31:00Z"
    }
  ]
}

Add Message

Add a message to an existing ticket.

POST /api/v1/tickets/:id/messages

Request Body

Field	Type	Required	Description
`body`	string	Yes	Message content
`senderEmail`	string	Yes	Sender's email
`senderName`	string	No	Sender's name
`direction`	string	No	`inbound` or `outbound` (default: `inbound`)
`bodyHtml`	string	No	HTML version of message

Example Request

curl -X POST https://app.keva.support/api/v1/tickets/tkt_abc123/messages \
  -H "Authorization: Bearer keva_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Any update on this?",
    "senderEmail": "customer@example.com",
    "direction": "inbound"
  }'