Skip to main content
Submit a single piece of free-form feedback. Median acknowledges immediately with 202 Accepted and processes the submission asynchronously, optionally turning it into one or more tasks on your board.

​
Endpoint

POST https://api.median.sh/api/feedback

​
Headers

HeaderRequiredDescription
AuthorizationYes (or apiKey in body)Bearer <your-api-key>
Content-TypeYesapplication/json

​
Request body

FieldTypeRequiredDescription
contentstringYesThe feedback text. 1–10,000 characters.
authorstringNoA label for who submitted the feedback (email, handle, etc.). Stored on the resulting task.
sourceUrlstringNoURL where the feedback originated (e.g. the page the user was on).
metadataobjectNoArbitrary JSON stored alongside the request for your own debugging.
classifybooleanNoWhen true, an LLM classifier first decides whether the submission is real product feedback. Off-topic submissions are rejected without creating tasks. Defaults to false.
apiKeystringNoAPI key, if not sent via the Authorization header.

​
Example

curl -X POST https://api.median.sh/api/feedback \
  -H "Authorization: Bearer mdn_live_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I tried to export the report as CSV but the button does nothing in Safari 17.",
    "author": "alex@example.com",
    "sourceUrl": "https://app.example.com/reports/42",
    "classify": true
  }'

​
Response

202 Accepted is returned synchronously once the submission has been queued. 
{
  "requestId": "j97c8...",
  "status": "pending"
}
The actual task creation happens in the background. Created and updated tasks appear on your board moments later — typically within a few seconds.

​
Embed snippet

A minimal feedback widget should post to your own server endpoint. The server attaches the Median API key and forwards the request, so the long-lived workspace key never ships to the browser. 
<script>
  async function sendFeedback(content) {
    await fetch("/api/feedback", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        content,
        sourceUrl: window.location.href,
        classify: true,
      }),
    })
  }
</script>
Your server handler should read MEDIAN_KEY from the environment, set Authorization: Bearer ${MEDIAN_KEY}, and forward the body fields such as content, sourceUrl, and classify to https://api.median.sh/api/feedback.

​
Classification

Setting classify: true runs a lightweight LLM pass before extraction. It rejects submissions that are not actionable product feedback (compliments, off-topic chat, generic praise). Use it whenever submissions arrive from an open form where users may write anything. When classify is omitted or false, every submission is treated as feedback and goes straight to the task extractor. This is the right default for trusted internal sources where you know every submission is real feedback.

​
Errors

See Overview → Error shape.
StatusReason
400content missing, empty, longer than 10,000 chars, or another field has the wrong type.
401API key missing or invalid.
402Workspace has no active plan.
405Wrong HTTP method (only POST and OPTIONS are accepted).