Create, read, update, and delete support tickets. Add messages to existing tickets.

Endpoints

Method Path Description
GET /api/v1/teams/{teamId}/tickets List tickets
POST /api/v1/teams/{teamId}/tickets Create a ticket
GET /api/v1/teams/{teamId}/tickets/{ticketId} Get a ticket
PATCH /api/v1/teams/{teamId}/tickets/{ticketId} Update a ticket
DELETE /api/v1/teams/{teamId}/tickets/{ticketId} Delete a ticket
GET /api/v1/teams/{teamId}/tickets/{ticketId}/messages List messages
POST /api/v1/teams/{teamId}/tickets/{ticketId}/messages Add a message

The single-resource endpoints accept both prefixed IDs (tkt_abc123) and UUIDs.

List Tickets

GET /api/v1/teams/{teamId}/tickets

Query Parameters

Parameter Type Description
page integer Page number (default: 1)
pageSize integer Results per page (default: 20, max: 100)
status string Filter: new, open, pending, resolved, closed
priority string Filter: low, normal, high, urgent
assignedTo string Filter by assigned agent ID
customerId string Filter by customer UUID
search string Search in title and customer name
expand string Comma-separated expansions. customer is supported on list.

Example Request

curl "https://www.cstar.help/api/v1/teams/{teamId}/tickets?status=open&priority=high" \
  -H "Authorization: Bearer sk_live_xxx"

Response

{
  "success": true,
  "data": [
    {
      "id": "tkt_a1B2c3D4e5F6",
      "object": "ticket",
      "title": "Need help with billing",
      "priority": "high",
      "status": "open",
      "customerId": "cus_x9Y8z7W6v5U4",
      "customerName": "Jane Doe",
      "assignedTo": null,
      "tags": ["billing"],
      "notes": null,
      "messageCount": 3,
      "responseDeadline": null,
      "resolutionDeadline": null,
      "firstResponseAt": null,
      "responseTier": null,
      "resolutionTier": null,
      "slaPaused": false,
      "metadata": {},
      "createdAt": "2026-03-30T10:00:00Z",
      "closedAt": null,
      "updatedAt": "2026-03-30T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  },
  "meta": {
    "requestId": "req_a1B2c3D4e5F6",
    "timestamp": "2026-03-30T10:30:00Z"
  }
}

Create Ticket

POST /api/v1/teams/{teamId}/tickets

Requires a secret key (sk_live_* or sk_test_*).

Request Body

Field Type Required Description
title string Yes Ticket subject line
priority string No low, normal (default), high, urgent
status string No new (default), open, pending, resolved, closed
customerId string No Customer ID to associate
customerName string No Customer display name (defaults to "Unknown Customer")
tags string[] No Array of tags
notes string No Internal notes
metadata object No Key-value pairs (max 50 keys, string values) 
curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/tickets" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{
    "title": "Cannot access dashboard",
    "priority": "high",
    "tags": ["login", "dashboard"]
  }'

Returns 201 Created with the new ticket object.

Idempotency

Include an Idempotency-Key header on POST and PATCH requests. If you retry the same key within 24 hours, you'll get the original response back without creating a duplicate.

Get Ticket

GET /api/v1/teams/{teamId}/tickets/{ticketId}

Returns the ticket with its messages included by default. Use ?expand=customer to also inline the customer object.

Update Ticket

PATCH /api/v1/teams/{teamId}/tickets/{ticketId}

Requires a secret key. Send only the fields you want to change.

Field Type Description
title string Update the subject line
priority string low, normal, high, urgent
status string Changing to closed or resolved sets closedAt automatically
assignedTo string/null Assign or unassign an agent
tags string[] Replace the tags array
notes string Update internal notes
metadata object Merged with existing metadata (set a key to null to remove it) 
curl -X PATCH "https://www.cstar.help/api/v1/teams/{teamId}/tickets/tkt_a1B2c3D4e5F6" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved", "metadata": {"resolution": "password_reset"}}'

Delete Ticket

DELETE /api/v1/teams/{teamId}/tickets/{ticketId}

Requires a secret key with delete permissions. Messages are cascade-deleted.

Returns:

{
  "success": true,
  "data": { "deleted": true, "id": "tkt_a1B2c3D4e5F6" }
}

List Messages

GET /api/v1/teams/{teamId}/tickets/{ticketId}/messages

Returns messages in chronological order. Agent messages include senderName and senderAvatarUrl when available.

Message Object

{
  "id": "msg_j2K3l4M5n6O7",
  "object": "message",
  "ticketId": "tkt_a1B2c3D4e5F6",
  "sender": "agent",
  "content": "Thanks for reaching out! I can help with that.",
  "senderId": "agt_p8Q9r0S1t2U3",
  "senderName": "Alex",
  "senderAvatarUrl": "https://...",
  "isInternal": false,
  "createdAt": "2026-03-30T10:35:00Z"
}

Add Message

POST /api/v1/teams/{teamId}/tickets/{ticketId}/messages

Requires a secret key.

Field Type Required Description
content string Yes Message text
sender string No agent (default), customer, or system
senderId string No ID of the sending agent
senderName string No Display name of the sender
messageType string No public (default) or internal. Internal messages are visible to your team only and don't notify the customer.

If this is the first agent reply, firstResponseAt on the ticket is set automatically for SLA tracking.

# Public reply
curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/tickets/tkt_abc/messages" \
  -H "Authorization: Bearer sk_live_xxx" \
  -d '{ "content": "Thanks for reaching out!", "sender": "agent" }'

# Internal note (team-only)
curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/tickets/tkt_abc/messages" \
  -H "Authorization: Bearer sk_live_xxx" \
  -d '{ "content": "FYI customer is on the Pro plan", "messageType": "internal" }'

Returns 201 Created. The response includes isInternal: true when messageType was internal.

Webhook Events

Event Fires When
ticket.created Ticket is created
ticket.updated Ticket fields change
ticket.closed Status changes to closed or resolved
ticket.message_added New message added
ticket.assigned Ticket is assigned to an agent
ticket.deleted Ticket is deleted

Related