API and tools
Submit reports from your software and understand the MCP tool contract.
The public complaint endpoint accepts reports for registered applications. It does not require a Complaintr login or API key. Application management and private workspace reads are separate authenticated features.
POST /api/v1/complaintsappName · title · description201 Createdid · application · createdAtKeep the returned complaint ID. It identifies the report in your workspace.
Submit a complaint
Send POST /api/v1/complaints to your Complaintr app origin with a JSON body.
curl --request POST 'https://app.complaintr.com/api/v1/complaints' \
--header 'Content-Type: application/json' \
--data '{
"appName": "Acme Store",
"title": "Checkout button does not respond",
"description": "Clicking Checkout on the cart page leaves me on the same page instead of opening payment.",
"sourceAgent": "custom-client",
"metadata": { "environment": "staging" }
}'| Field | Required | Description |
|---|---|---|
appName | Yes | Registered application name, at most 100 characters. Case-insensitive matching. |
title | Yes | Short summary, at most 200 characters. |
description | Yes | Expected and actual behavior, at most 5,000 characters. |
sourceAgent | No | Source label, at most 50 characters. |
metadata | No | JSON context supplied with the report. Use an object with named fields. |
Keep secrets and personal information out of the submitted content. A successful response has status 201:
{
"id": "example-complaint-id",
"title": "Checkout button does not respond",
"application": "Acme Store",
"category": null,
"severity": null,
"createdAt": "2026-09-21T09:00:00.000Z",
"shareUrl": "https://app.complaintr.com/share/example-complaint-id"
}Category and severity can be null when triage is disabled or unavailable. Save the returned id to identify the report. The shareUrl is an opt-in entry link: opening it activates public sharing.
MCP tools
Connect using the integration guide. The remote endpoint is:
https://app.complaintr.com/api/mcpreport_complaint
Creates a complaint. Its input fields match the submission table above. Verify that the tool succeeds and returns a complaint ID before reporting success to the user.
share_complaint
Creates a public share link. Pass complaintId, the ID returned when the complaint was created. Call this only when the user wants to share the report publicly.
Sharing endpoints
| Request | Result |
|---|---|
POST /api/v1/complaints/:id/share | Creates or returns a token and shareUrl. |
DELETE /api/v1/complaints/:id/share | Revokes the current token and returns {"revoked": true}. |
GET /share/:id | Activates sharing and redirects to the public card. |
Sharing endpoints operate using the complaint ID without a workspace login. Treat IDs as sensitive references. Read Sharing before exposing links in your own interface.
Errors and retries
| Status | Meaning | Next step |
|---|---|---|
400 | Required submission fields are missing or invalid. | Check field types and lengths. |
404 | The application or complaint does not exist. | Check the registered name or returned complaint ID. |
429 | Too many requests. | Wait before retrying. Submission responses include Retry-After in seconds. |
500 | The request could not be completed. | Inspect the response and check whether a report arrived before retrying. |
HTTP complaint submission permits 10 requests per IP address per 60 seconds. Sharing permits 30 requests per IP address per 60 seconds across creation and revocation.
Complaint submission has no public idempotency key. A retry can create a duplicate, particularly if the connection was lost after the server stored the report. Check the inbox before repeating an uncertain submission.