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

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 Tickets GET Get Ticket POST Create Ticket PATCH Update Ticket DELETE 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

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

{
  "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

{
  "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

{
  "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

{
  "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

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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.

Requires a secret API key.

Request Body

title string required

Ticket subject line

priority string

Priority level

Default: normal

customerId string

Existing customer ID (cus_ prefix)

customerName string

Customer name (used if customerId is not provided)

tags string[]

Array of tag strings. Also accepts comma-separated string via curl.

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

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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 title

status string

New status

priority string

New priority

tags string[]

Array of tag strings (replaces existing). Also accepts comma-separated string via curl.

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

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

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

Responses

200 Ticket deleted

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

404 Ticket not found

{
  "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

{
  "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

{
  "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

{
  "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"
  }
}