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 uuid

Unique ticket identifier

title string

Ticket subject line

status string

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

priority string

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

customer_id uuid

Associated customer ID

assigned_to uuid

Assigned agent ID

tags string[]

Array of tag strings

notes string

Internal notes (not visible to customers)

message_count integer

Number of messages on this ticket

created_at datetime

When the ticket was created

updated_at datetime

Last modification timestamp

resolved_at datetime

When the ticket was resolved (if applicable)

Endpoints

GET List Tickets GET Get Ticket POST Create Ticket PATCH Update Ticket DELETE Delete Ticket

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

List Tickets

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 uuid

Filter tickets by customer

page integer

Page number (1-indexed)

Default: 1

pageSize integer

Results per page (max 100)

Default: 20

Code Examples

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

Responses

200 Paginated list of tickets

{
			  "data": [
			    {
			      "id": "550e8400-e29b-41d4-a716-446655440000",
			      "title": "Cannot log in to my account",
			      "status": "open",
			      "priority": "high",
			      "customer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
			      "tags": [
			        "login",
			        "authentication"
			      ],
			      "message_count": 3,
			      "created_at": "2025-12-10T14:30:00Z"
			    }
			  ],
			  "pagination": {
			    "page": 1,
			    "pageSize": 20,
			    "total": 142,
			    "totalPages": 8
			  }
			}

401 Authentication failed — missing or invalid API key

{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}

403 Insufficient permissions — wrong key type or team access

{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}

429 Rate limit exceeded

{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}

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

Get Ticket

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

Path Parameters

ticketId uuid required

The ticket ID

Code Examples

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

Responses

200 The ticket object with messages

{
			  "data": {
			    "id": "550e8400-e29b-41d4-a716-446655440000",
			    "title": "Cannot log in to my account",
			    "status": "open",
			    "priority": "high",
			    "customer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
			    "assigned_to": null,
			    "tags": [
			      "login",
			      "authentication"
			    ],
			    "notes": null,
			    "message_count": 3,
			    "messages": [
			      {
			        "id": "msg_001",
			        "content": "I keep getting \"invalid credentials\" when I try to log in.",
			        "sender": "customer",
			        "sender_name": "Jane Smith",
			        "created_at": "2025-12-10T14:30:00Z"
			      }
			    ],
			    "created_at": "2025-12-10T14:30:00Z",
			    "updated_at": "2025-12-10T15:00:00Z"
			  }
			}

404 Ticket not found

{
			  "error": {
			    "code": "resource_missing",
			    "message": "Ticket not found"
			  }
			}

401 Authentication failed — missing or invalid API key

{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}

403 Insufficient permissions — wrong key type or team access

{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}

429 Rate limit exceeded

{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}

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

Create Ticket

Create a new support ticket. Optionally attach it to an existing customer or provide customer details inline.

Requires a secret API key.

Request Body

title string required

Ticket subject line

priority string

Priority level

Default: normal

customerId uuid

Existing customer ID

customerName string

Customer name (used if customerId is not provided)

tags string

Comma-separated tags

notes string

Internal notes

Code Examples

curl -X POST "https://app.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

{
			  "data": {
			    "id": "550e8400-e29b-41d4-a716-446655440000",
			    "title": "Cannot log in to my account",
			    "status": "new",
			    "priority": "high",
			    "tags": [
			      "login",
			      "authentication"
			    ],
			    "created_at": "2025-12-10T14:30:00Z"
			  }
			}

400 Missing required fields

{
			  "error": {
			    "code": "parameter_missing",
			    "message": "title is required",
			    "param": "title"
			  }
			}

401 Authentication failed — missing or invalid API key

{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}

403 Insufficient permissions — wrong key type or team access

{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}

429 Rate limit exceeded

{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}

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

Update Ticket

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 uuid required

The ticket ID

Request Body

title string

New title

status string

New status

priority string

New priority

tags string

Comma-separated tags (replaces existing)

notes string

Internal notes

Code Examples

curl -X PATCH "https://app.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

{
			  "data": {
			    "id": "550e8400-e29b-41d4-a716-446655440000",
			    "title": "Cannot log in to my account",
			    "status": "resolved",
			    "priority": "high",
			    "updated_at": "2025-12-10T16:00:00Z"
			  }
			}

404 Ticket not found

{
			  "error": {
			    "code": "resource_missing",
			    "message": "Ticket not found"
			  }
			}

401 Authentication failed — missing or invalid API key

{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}

403 Insufficient permissions — wrong key type or team access

{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}

429 Rate limit exceeded

{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}

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

Delete Ticket

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 uuid required

The ticket ID

Code Examples

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

Responses

200 Ticket deleted

{
			  "data": {
			    "deleted": true
			  }
			}

404 Ticket not found

{
			  "error": {
			    "code": "resource_missing",
			    "message": "Ticket not found"
			  }
			}

401 Authentication failed — missing or invalid API key

{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}

403 Insufficient permissions — wrong key type or team access

{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}

429 Rate limit exceeded

{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}