---
title: "Write back what you found out about an incident"
method: POST
path: "/api/v1/incidents/{id}/notes"
tags: ["Incidents"]
---

# Write back what you found out about an incident

`POST /api/v1/incidents/{id}/notes`

## Request

- Base URL: `https://app.lastping.dev`
- URL: `https://app.lastping.dev/api/v1/incidents/{id}/notes`
- Auth: API key in header `X-Api-Key`

The **push** half of failure delivery, and the reason the inbox is
worth reading. Instead of "check failed at 03:04", the person who gets
paged reads *"failed because the upstream API returned 503; same
failure as the last three nights; I retried twice and stopped."*

Notes appear on the incident's page in the dashboard, attributed to
their author, in the order they were written.

**Send one whether or not you fixed the problem.** With no note, an
incident is indistinguishable from one nobody has looked at yet — so
an agent that writes back only its successes leaves a record that is
worse than none. "Could not reproduce, gave up after two attempts" is
a finding.

**Notes are append-only.** There is no endpoint to edit one and none
to delete one, by design: a diagnosis that can be rewritten is not
evidence, and a reader has to be able to trust that a note still says
what it said when it was written. Corrections are made by appending
another note. Storage enforces this too: a stored note cannot be
changed.

**Authorship is not yours to choose.** The request body has no
`author` field. Authorship is derived from how the caller
authenticated: a session principal (a person in the dashboard) is
stored as `user`; an API key (a machine) is stored as `agent`. A
reader must never be misled about who diagnosed what, and an endpoint
whose caller could name its own author would make the distinction
meaningless.

Notes may be added to a **closed** incident on purpose: the run that
finally succeeded is usually the one that understood why the previous
one did not, and refusing the note would lose the explanation exactly
when it became available.

At most 50 notes per incident.

## Request body

- IncidentNoteCreate: Body for `POST /api/v1/incidents/{id}/notes`. One field, deliberately. There is no `author` — see the endpoint's own description — and no timestamp: the server stamps the note, so its position in the incident's log cannot be back-dated by its writer.
  - `body` string, required: What you found out, in two or three sentences: what you saw, what you tried, and where you stopped. Not a log dump — the failing run's own output is already stored and already shown beside your note. Must not be empty or whitespace-only (400). Bodies over 8192 bytes are **rejected, not truncated** (400): a truncated diagnosis reads as a complete one that trails off, and the reader has no way to tell that the sentence naming the cause was the one cut.

## Response `201`

The stored note.

- IncidentNote: One note on an incident: what an agent learned about a failure, in its own words. Returned by `POST /api/v1/incidents/{id}/notes` and rendered on the incident page in the dashboard.
  - `id` integer, required
  - `incident_id` integer, required: The incident this note is about.
  - `author` 'agent' | 'user', required: Who wrote it. Decided by the surface the note arrived on, never by the caller: a session principal (a person in the dashboard) is `user`; an API key (a machine) is `agent`.
  - `body` string, required
  - `created_at` string, date-time, required: RFC 3339 UTC timestamp, stamped by the server.

## Other responses

- `400`: The id is not a positive integer, the JSON is malformed, or the body is empty, whitespace-only, or over 8192 bytes.
- `401`: Missing or invalid API key.
- `404`: No such incident **in this project**. An incident belonging to another project answers exactly the same way as one that does not exist, so this endpoint cannot be used to probe for other tenants' incident ids.
- `409`: This incident already has the maximum of 50 notes.

---

[API](https://skmtc.dev/lastping/apis/lastping-management-api.md) · [All operations](https://skmtc.dev/lastping/apis/lastping-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lastping/apis/lastping-management-api/revisions/bbc6eda91c46?raw)