Notifications

In-app notifications for team members. List, read, and manage notification state.

The Notification object

id string

Notification ID

type string

Notification type

title string

Notification title

body string

Notification body

read boolean

Whether the notification has been read

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 the authenticated user.

Query Parameters

unreadOnly boolean

Only return unread notifications

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}/notifications" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Notification list

{
  "success": true,
  "data": [
    {
      "id": "ntf_abc",
      "type": "ticket_assigned",
      "title": "Ticket assigned",
      "read": false
    }
  ]
}

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

Get Unread Count

Get the number of unread notifications.

Code Examples

curl -X GET "https://www.cstar.help/api/v1/teams/{teamId}/notifications/unread-count" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Unread count

{
  "success": true,
  "data": {
    "object": "unread_count",
    "count": 5
  }
}

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

Mark All Read

Mark all notifications as read.

Code Examples

curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/notifications/mark-all-read" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 All marked read

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

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