Skip to main content

Tickets

Tickets are the core of cStar. Each one represents a customer support conversation. Create, update, and resolve tickets through the API.

The Ticket object

id string

Unique ticket identifier (tkt_ prefix)

title string

Ticket subject line, up to 255 characters. Subjects from email and the widget are shortened to fit.

status string

Current status "new" | "open" | "pending" | "resolved" | "closed"

priority string

Priority level "low" | "normal" | "high" | "urgent"

customerId string

Associated customer ID (cus_ prefix)

assignedTo string

Assigned agent ID

tags string[]

Array of tag strings

notes string

Internal notes (not visible to customers)

messageCount integer

Number of messages on this ticket

createdAt datetime

When the ticket was created

updatedAt datetime

Last modification timestamp

resolvedAt datetime

When the ticket was resolved (if applicable)

Endpoints

GET List TicketsGET Get TicketPOST Create TicketPATCH Update TicketDELETE Delete Ticket
GET /api/v1/teams/{teamId}/tickets

List Tickets

Try it

Retrieve a paginated list of tickets with optional filtering by status, priority, customer, or search term.

Query Parameters

status string

Filter by status

priority string

Filter by priority

search string

Full-text search in title and content

customerId string

Filter tickets by customer

page integer

Page number (1-indexed)

Default: 1

pageSize integer

Results per page (max 100)

Default: 20

Code Examples

bash 
curl -X GET "https://www.cstar.help/api/v1/teams/{teamId}/tickets?status=open&page=1" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Paginated list of tickets
json 
{
  "success": true,
  "data": [
    {
      "id": "tkt_550e8400e29b41d4a716446655440000",
      "title": "Cannot log in to my account",
      "status": "open",
      "priority": "high",
      "customerId": "cus_7c9e667974254de0944be07fc1f90ae7",
      "tags": [
        "login",
        "authentication"
      ],
      "messageCount": 3,
      "createdAt": "2025-12-10T14:30:00Z"
    }
  ],
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z",
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 142,
      "totalPages": 8
    }
  }
}

401 Authentication failed: missing or invalid API key
json 
{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access
json 
{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded
json 
{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

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

Get Ticket

Try it

Retrieve a single ticket by ID. Includes the full message thread.

Path Parameters

ticketId string required

The ticket ID (tkt_ prefix)

Code Examples

bash 
curl -X GET "https://www.cstar.help/api/v1/teams/{teamId}/tickets/{ticketId}" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 The ticket object with messages
json 
{
  "success": true,
  "data": {
    "id": "tkt_550e8400e29b41d4a716446655440000",
    "title": "Cannot log in to my account",
    "status": "open",
    "priority": "high",
    "customerId": "cus_7c9e667974254de0944be07fc1f90ae7",
    "assignedTo": null,
    "tags": [
      "login",
      "authentication"
    ],
    "notes": null,
    "messageCount": 3,
    "messages": [
      {
        "id": "msg_a1b2c3d4e5f6",
        "content": "I keep getting \"invalid credentials\" when I try to log in.",
        "sender": "customer",
        "senderName": "Jane Smith",
        "createdAt": "2025-12-10T14:30:00Z"
      }
    ],
    "createdAt": "2025-12-10T14:30:00Z",
    "updatedAt": "2025-12-10T15:00:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T15:00:00Z"
  }
}

404 Ticket not found
json 
{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Ticket not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed: missing or invalid API key
json 
{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access
json 
{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded
json 
{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

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

Create Ticket

Try it

Create a new support ticket. Optionally attach it to an existing customer or provide customer details inline. An unknown body field returns 400 with that field as param.

Requires a secret API key.

Request Body

title string required

Ticket subject line, 1 to 255 characters. Longer values return 400 with param "title".

priority string

Priority level

Default: normal

customerId string

Existing customer ID (cus_ prefix)

customerEmail string

Email of an existing customer on this team, used when customerId is not provided. Returns 422 if no customer has it.

customerName string

Customer name (used if customerId is not provided)

messages object[]

Opening messages, oldest first. Each is { sender: "customer" | "agent" | "system" | "ai", content }.

tags string[]

Array of tag strings.

notes string

Internal notes

metadata object

Arbitrary key-value metadata (max 50 keys). On update, keys are merged. Set a key to null to remove it.

Code Examples

bash 
curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/tickets" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cannot log in to my account",
    "priority": "high",
    "customerName": "Jane Smith",
    "tags": ["login", "authentication"]
  }'

Responses

201 Ticket created
json 
{
  "success": true,
  "data": {
    "id": "tkt_550e8400e29b41d4a716446655440000",
    "title": "Cannot log in to my account",
    "status": "new",
    "priority": "high",
    "tags": [
      "login",
      "authentication"
    ],
    "createdAt": "2025-12-10T14:30:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

400 Missing required fields
json 
{
  "success": false,
  "error": {
    "type": "validation_error",
    "code": "PARAMETER_MISSING",
    "message": "title is required",
    "param": "title",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed: missing or invalid API key
json 
{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access
json 
{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded
json 
{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

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

Update Ticket

Try it

Update one or more fields on an existing ticket. Only include the fields you want to change.

Requires a secret API key.

Path Parameters

ticketId string required

The ticket ID (tkt_ prefix)

Request Body

title string

New subject, up to 255 characters. Sending the unchanged subject of an older, longer ticket is allowed.

status string

New status. 'merged' returns 400 (param status): merging tickets sets it.

priority string

New priority

tags string[]

Array of tag strings (replaces existing).

notes string

Internal notes

metadata object

Key-value metadata to merge. Existing keys preserved, new keys added. Set a key to null to remove it.

Code Examples

bash 
curl -X PATCH "https://www.cstar.help/api/v1/teams/{teamId}/tickets/{ticketId}" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "status": "resolved", "notes": "Password reset sent" }'

Responses

200 Updated ticket
json 
{
  "success": true,
  "data": {
    "id": "tkt_550e8400e29b41d4a716446655440000",
    "title": "Cannot log in to my account",
    "status": "resolved",
    "priority": "high",
    "updatedAt": "2025-12-10T16:00:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T16:00:00Z"
  }
}

404 Ticket not found
json 
{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Ticket not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed: missing or invalid API key
json 
{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access
json 
{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded
json 
{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

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

Delete Ticket

Try it

Permanently delete a ticket and all its messages. This action cannot be undone.

Requires a secret API key. This is a destructive operation.

Path Parameters

ticketId string required

The ticket ID (tkt_ prefix)

Code Examples

bash 
curl -X DELETE "https://www.cstar.help/api/v1/teams/{teamId}/tickets/{ticketId}" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Ticket deleted
json 
{
  "success": true,
  "data": {
    "deleted": true
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

404 Ticket not found
json 
{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Ticket not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed: missing or invalid API key
json 
{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access
json 
{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded
json 
{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}