Notifications

In-app notifications for team members. Every call names the team member with userId.

The Notification object

id string

Notification ID

type string

Notification type

title string

Notification title

body string

Notification body

ticketId string

Related ticket, or null

isRead boolean

Whether this team member has read it

readAt datetime

When it was read, or null

createdAt datetime

When the notification was created

Endpoints

GET List Notifications GET Get Unread Count POST Mark All Read

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

List Notifications

List notifications for one team member.

Query Parameters

userId string required

Team member whose notifications to list

isRead boolean

false for unread only, true for read only

type string

Filter by notification type

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}/notifications?userId=550e8400-e29b-41d4-a716-446655440001&isRead=false" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Notification list

json

{
  "success": true,
  "data": [
    {
      "id": "ntf_abc",
      "object": "notification",
      "type": "assigned",
      "title": "Ticket assigned",
      "isRead": false,
      "readAt": null
    }
  ]
}

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}/notifications/unread-count

Get Unread Count

Get the number of unread notifications for one team member.

Query Parameters

userId string required

Team member

Code Examples

bash

curl -X GET "https://www.cstar.help/api/v1/teams/{teamId}/notifications/unread-count?userId=550e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Unread count

json

{
  "success": true,
  "data": {
    "unreadCount": 5,
    "truncated": false
  }
}

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}/notifications/mark-all-read

Mark All Read

Mark all of one team member's notifications as read.

Request Body

userId string required

Team member

Code Examples

bash

curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/notifications/mark-all-read" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"userId":"550e8400-e29b-41d4-a716-446655440001"}'

Responses

200 All marked read

json

{
  "success": true,
  "data": {
    "markedRead": 5
  }
}

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