Overview
Secret-key API for backend integrations.
The server-to-server API lets your backend integrate with Confetti directly — for example, to pull data into a scheduled pipeline or custom dashboard.
For ad-hoc reporting and summaries, use
MCP reporting first. This API is best when you need
repeatable automation, engagement funnel metrics (GET …/stats), or to feed
data into your own systems.
All endpoints live under https://confetti.gov.sg/api/v1/protected/ and return
JSON wrapped in a data envelope (list endpoints also include pagination
fields).
Authentication
Requests are authenticated with a secret API key, sent as a bearer token:
GET /api/v1/protected/surveys/{surveyId}/responses HTTP/1.1
Host: confetti.gov.sg
Authorization: Bearer cfti_sk_<your-secret-key>Create and revoke secret keys on the Setup page in Confetti. The key is shown only once when created — store it somewhere safe.
The secret API key grants access to your team's data. Keep it on your server — never expose it in client-side code or commit it to source control. For browser use, use the public API and its publishable key instead.
Rate limits
Authenticated calls are limited to 10 requests per second per secret key.
Exceeding the limit returns 429 Too Many Requests with a Retry-After header
— honour it (and back off) rather than retrying immediately.
For real-time delivery of each new response, use webhooks instead of polling this API.
Endpoints
| Resource | Endpoint | Use when you need… |
|---|---|---|
| Surveys | GET /surveys | A paginated list of surveys in your team |
| Survey | GET /surveys/{surveyId} | The full survey definition, including question IDs |
| Responses | GET /surveys/{surveyId}/responses | Individual response records (newest first, cursor-paginated) |
| Stats | GET /surveys/{surveyId}/stats | Engagement totals — views, dismissals, and responses (total and unique) |
| Score distributions | GET /surveys/{surveyId}/score-distributions | Score histograms for rating questions over a time range |
For score breakdowns in conversation, use
MCP reporting (get_score_distributions). This API
section is for programmatic access in automated pipelines.
Browse the endpoints grouped by resource in the sidebar.
Was this page helpful?