Tellstack One POST and it is in
Tellstack takes feedback in through three routes: hosted form, web widget and REST API. All three need nothing but the public project key, which may only write.
REST API
curl -X POST https://…/api/v1/feedback \
-H "Content-Type: application/json" \
-H "X-Tellstack-Key: ts_live_…" \
-d '{
"message": "PDF export gets stuck on large files",
"category": "bug",
"email": "anna@example.com",
"metadata": { "appVersion": "1.4.2", "platform": "ios" }
}'Response on success (201):
{
"id": "…",
"status": "new",
"createdAt": "2026-08-19T09:12:44.101Z"
}Full API referenceWeb widget
<script src="https://…/widget.js" data-project="ts_live_…" async></script>The widget builds its panel in the shadow DOM. Your page CSS does not affect it, and it does not affect yours. Tellstack.identify() passes context along, Tellstack.open({ type: 'bug' }) opens it with a preselected type.
Limits and rules
- Rate limit
- 120 requests per minute per key.
- Size
- 64 KB per request, 5,000 characters per message.
- Key permissions
- Write yes, read no. Always.
- Workspace
- Derived from the key, never taken from the client.
- Validation
- Every input goes through a schema; errors name the field and the reason.
Frequently asked questions
What authentication does ingestion need?
A public project key in the X-Tellstack-Key header. Alternatively as a bearer token or the key query parameter. The key may only write feedback and never read, which is why it can sit in client code.
What are the limits of the public API?
120 requests per minute per project key, at most 64 kilobytes per request and 5,000 characters per message. Hosted forms allow ten submissions per IP in five minutes.
What do error responses look like?
Always the same: an error object with code, message and optionally details. The codes are validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, payload_too_large, not_configured and internal_error.
Can I rotate the project key?
Yes. A new key is issued immediately and the old one becomes invalid at the same moment. Useful when a key has ended up somewhere it should not be.
Are there webhooks?
Yes, from the Indie plan. Tellstack sends each event as a POST to your address — feedback.created, feedback.replied and feedback.status_changed. Signed with HMAC-SHA256 over timestamp and raw body, five retries with growing gaps, plus a log of the attempts. You set them up in your account under Webhooks.
Can I export feedback?
Yes, from the Indie plan as CSV or JSON — with the same filters the inbox is showing. The CSV carries a BOM so spreadsheet apps render accented characters correctly.
Get going
Create an account, create a project, copy the key. The Documentation walks you through it in five minutes.