POST /v1/analyses/{id}/postmortem/polish

Takes a Markdown postmortem (produced by /postmortem or hand-edited) and rewrites the prose for flow, tone, and consistency. Polish is intended to refine prose — review the output before sharing externally.

Plan gate. This endpoint is available on Pro and above. Starter accounts receive 403 FEATURE_NOT_AVAILABLE.

Authentication

API key with analysis:read permission.

Endpoint

POST /v1/analyses/{id}/postmortem/polish

Path parameters

Param	Type	Notes
`id`	UUID	The analysis id (used to verify tenant ownership)

Request body

Field	Type	Required	Notes
`markdown`	string (≥ 1 char)	✓	The Markdown to polish

{
  "markdown": "# Outage\n\n## Summary\nThe API was slow..."
}

Response

200 OK

{
  "success": true,
  "data": {
    "markdown": "# API Latency Incident — 2026-04-25\n\n## Summary\n..."
  }
}

Field	Type	Notes
`markdown`	string	The polished Markdown — same structure, refined prose

Error responses

Status	`error.code`	When
400	`VALIDATION_ERROR`	`id` is not a UUID, or `markdown` is empty
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Key lacks `analysis:read`
403	`FEATURE_NOT_AVAILABLE`	Plan tier doesn't include AI polish (Starter)
404	`NOT_FOUND`	No analysis with that id

Example

curl -X POST https://api.sigsentry.com/v1/analyses/ana_x1y2/postmortem/polish \
  -H "Authorization: Bearer ss_secret_..." \
  -H "Content-Type: application/json" \
  -d '{ "markdown": "# Outage\n\n## Summary\nThe API was slow..." }'

Patterns

The typical flow is:

POST /postmortem to get the structured Markdown
Hand-edit if you want to add team-specific context
POST /postmortem/polish to clean up the result before sharing externally

Idempotency

POST /v1/analyses/{id}/postmortem/polish honors the Idempotency-Key header — see Idempotency.

POST /v1/analyses/{id}/postmortem/polish

On this page