API Reference

cStar is a headless customer support platform — you bring the UI, we provide the API. Organized around REST with JSON request/response bodies, standard HTTP codes, and Bearer token auth.

Authentication

Authenticate API requests by including your API key in the Authorization header as a Bearer token. You can manage API keys from the CLI or your team settings.

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

Secret

sk_live_* / sk_test_*

Full read/write access. Keep server-side only — never expose in client code.

Publishable

pk_live_* / pk_test_*

Read-only access. Safe for frontend apps, widgets, and public-facing code.

Base URL

https://www.cstar.help/api/v1/teams/{teamId}

All endpoints are scoped to your team. Replace {teamId} with your team's UUID (found in team settings or via cstar status).

Errors

cStar uses conventional HTTP status codes. Codes in the 2xx range indicate success, 4xx indicate a client error, and 5xx indicate a server error. See the full Error Reference for detailed troubleshooting of every error code.

200 OK — Request succeeded

201 Created — Resource created successfully

400 Bad Request — Missing or invalid parameters

401 Unauthorized — Invalid or missing API key

403 Forbidden — Key lacks required permissions

404 Not Found — Resource doesn't exist

429 Rate Limited — Too many requests

500 Server Error — Something went wrong on our end

Error response shape

{
  "success": false,
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The 'title' field is required.",
    "param": "title",
    "doc_url": "https://www.cstar.help/developers/errors#parameter_missing",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

Rate Limits

The API is rate-limited per key. Limits are returned in response headers. When exceeded, requests return 429 with a retryAfter value in the error body.

Secret keys 1,000 requests / hour

Publishable keys 100 requests / hour

Idempotency

For safe retries on POST and PATCH requests, include an Idempotency-Key header. If the same key is sent again within 24 hours, the original response is returned instead of creating a duplicate.

curl -X POST .../tickets \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"title": "My ticket"}'

# Retry with the same key → returns the same ticket, no duplicate

Resources

Explore each resource for full endpoint documentation, parameters, and code examples.

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

GET /{ticketId}

Customers Customers represent the people who submit tickets. Track their history, sentiment, and metadata across all interactions.

GET /{customerId}

Customer Groups Customer groups let you organize customers into flexible categories — like Zendesk organizations, Intercom companies, or custom segments. Customers can belong to multiple groups.

GET /{groupId}

Articles Articles power your knowledge base. Create, publish, and manage help content that customers and agents can search.

GET /{articleId}

Messages Messages belong to tickets and represent the conversation thread between agents and customers. Each message has a sender type and optional metadata.

Webhooks Webhooks notify your application in real-time when events happen in cStar. Subscribe to ticket, customer, article, and gamification events.

GET /{webhookId}

Categories Categories organize your knowledge base articles into logical groups. Customers see public categories when browsing your help center.

PATCH /{categoryId}

Community Community posts let customers ask questions, share feedback, and vote on feature requests. Agents can manage posts, set statuses, and moderate content.

PATCH /posts/{postId}

Members Team members are the agents and admins who use cStar. Manage roles, view stats, and send invites.

GET /{memberId}

PATCH /{memberId}

Settings Team settings control statuses, quick replies, business hours, and widget appearance. Secret key required.

GET /statuses

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

GET /unread-count

POST /mark-all-read

Custom Fields Define custom data fields for tickets and customers. Supports text, number, select, date, and boolean types.

SLA Rules Service Level Agreement rules define response and resolution time targets by ticket priority.

Analytics Team performance analytics, agent stats, and CSAT data. All analytics endpoints require a secret key.

GET /overview

Bulk Operations Perform bulk updates or deletes on tickets, customers, or articles. Max 100 items per request.

Export Export tickets, customers, or articles as JSON or CSV. Synchronous — max 10,000 rows per resource.

Import Import tickets, customers, or articles. Synchronous processing — max 500 records per request. Supports merge strategies.

Audit Log Immutable audit trail of all actions taken in your team. Filter by action, resource, actor, or date range.

Search Search across tickets, customers, and articles in a single query. Works with publishable keys (read-only).

Tags Manage tags used across tickets. List tags with usage counts, create new ones, or remove unused tags.

Game The cStar gamification system — player stats, boss battles, leaderboards, achievements, quests, puzzles, social features, cosmetics, seasons, and skill trees. Read endpoints accept any API key; write endpoints require a secret key.

GET /player/{memberId}

AI Actions AI-powered actions for ticket management — auto-tag tickets, generate reply suggestions, summarize conversations, and improve draft text.

Automations Automation rules that trigger actions when specific events occur. Rules have conditions, actions, and can be tested with dry runs.

POST /{ruleId}/test

Saved Views Saved filter presets for tickets, customers, articles, or community posts. Create reusable views and execute them to get filtered results.

GET /{viewId}/tickets

Billing Access subscription status and create Stripe billing portal sessions. Secret key required.

GET /subscription