Drop/docs
GitHubOpen Drop
Core Resources
View as Markdown

Report

A bug, feature request, or question filed against Drop. Each Report is backed by a GitHub issue in `himarley/drop`; the case number is the issue number.

A Report is how anyone files a bug, feature request, or question about Drop. Filing a report opens a GitHub issue in himarley/drop (labeled by kind), and the case number is that issue number. A thin Postgres row bridges the reporter (a Drop user, not a GitHub account) to the issue — that's what powers "my reports" listing, attribution, and email notifications. GitHub stays the source of truth for the body, comment thread, and authoritative status, which are reconciled on read. The conversational AI intake (drop report interactively, or POST /api/reports/intake) and the inbound GitHub webhook are hand-written surfaces and are not listed among the methods below.

The Report object

Every Report carries these attributes.

Attributes

caseNumber
number
The case number — identical to the GitHub issue number in himarley/drop. Stable for the lifetime of the report; appears in every API path (/api/reports/{caseNumber}) and in drop reports commands.
kind
enum
BUGFEATUREQUESTION
What kind of report this is. Set at filing time and written to GitHub as a label. BUG — something is broken; FEATURE — a request for new behavior; QUESTION — a how-do-I / clarification.
status
enum
OPENTRIAGEDIN_PROGRESSRESOLVEDWONT_FIX
Triage status, reconciled from the GitHub issue on read. OPEN at filing. Admins move it through TRIAGED → IN_PROGRESS → RESOLVED / WONT_FIX (each writes the matching GitHub label/state and emails the reporter). Reporters can open/close their own report via state but cannot set status.
title
string
Short title for the issue (4–160 characters). Becomes the GitHub issue title.
appSlug
string· nullable
Optional slug of the Droplet this report is about. Lowercase letters, digits, and hyphens. Surfaced in the issue body so triagers know which Droplet is affected.
githubUrl
string· nullable
Direct link to the backing GitHub issue. Null only transiently if the issue link has not yet been resolved.
commentCount
number
Number of comments on the GitHub issue thread. Present on the detail shape (get), reconciled on read.
More attributes+ Show 7
body
string· nullable
Full description (markdown), up to 20,000 characters. Returned on the detail shape (get / create); omitted from the list summary. Source of truth is the GitHub issue body.
source
string· nullable
Where the report was filed from: cli | drop-bar | web | slack | mcp. Provenance only — does not affect routing.
reporterName
string· nullable
Display name of the Drop user who filed the report. Used for attribution in the issue body and comments (Drop's bot identity writes to GitHub on their behalf).
reporterEmail
string· nullable
Email of the reporter. Used for SES status-change notifications. Only returned to the reporter themselves or an admin.
closedAt
timestamp· nullable
ISO 8601 timestamp the backing issue was closed, or null while open. Detail shape only.
createdAt
timestamp
ISO 8601 timestamp the report was filed.
updatedAt
timestamp
ISO 8601 timestamp of the last status / metadata change.
THE REPORT OBJECT
{
  "caseNumber": 142,
  "kind": "BUG",
  "status": "IN_PROGRESS",
  "title": "PDF export spins forever on the Q3 board",
  "body": "**Steps**: open q3-board, click Export PDF.\n**Expected**: a PDF.\n**Actual**: spinner never resolves.",
  "appSlug": "q3-board",
  "source": "cli",
  "reporterName": "Dana Reyes",
  "reporterEmail": "dana.reyes@himarley.com",
  "githubUrl": "https://github.com/himarley/drop/issues/142",
  "commentCount": 2,
  "closedAt": null,
  "createdAt": "2026-06-18T15:02:00.000Z",
  "updatedAt": "2026-06-18T16:20:00.000Z"
}

Methods

Endpoints to operate on a Report. The example switches between curl, drop CLI, and MCP via the dropdown — your choice persists across the page.

GET

List Reports

/api/reports

List reports you filed (most recent first). Admins can pass all=true to list every reporter's reports. Filter by status and/or kind.

Parameters

all
boolean· query
Admin only: include all reporters' reports.
status
string· query
Filter by status (OPEN|TRIAGED|IN_PROGRESS|RESOLVED|WONT_FIX).
kind
string· query
Filter by kind (BUG|FEATURE|QUESTION).
GET/api/reports
drop reports list --status OPEN
Response200
[
  {
    "caseNumber": 142,
    "kind": "BUG",
    "status": "OPEN",
    "title": "PDF export spins forever on the Q3 board",
    "appSlug": "q3-board",
    "source": "cli",
    "reporterName": "Dana Reyes",
    "reporterEmail": "dana.reyes@himarley.com",
    "githubUrl": "https://github.com/himarley/drop/issues/142",
    "createdAt": "2026-06-18T15:02:00.000Z",
    "updatedAt": "2026-06-18T15:02:00.000Z"
  }
]
POST

File a Report

/api/reports

File a report — creates a GitHub issue in himarley/drop (labeled with the kind) and returns the case number (= the issue number). Takes an already-structured { kind, title, body }; the conversational AI intake that produces that structure runs separately (drop report interactively, or POST /api/reports/intake). Optionally link a Droplet via appSlug.

Parameters

kind
string· body· required
bug | feature | question.
title
string· body· required
Short title for the issue.
body
string· body· required
Full description (markdown).
appSlug
string· body
Optional Droplet this concerns.
source
string· body
Provenance: cli | drop-bar | web | slack | mcp.
POST/api/reports
drop reports create --kind BUG --title "PDF export spins forever on the Q3 board" --body "**Steps**: open q3-board, click Export PDF.
**Expected**: a PDF.
**Actual**: spinner never resolves (since this morning)." --app-slug q3-board --source cli
Response201
{
  "caseNumber": 142,
  "kind": "BUG",
  "status": "OPEN",
  "title": "PDF export spins forever on the Q3 board",
  "body": "**Steps**: open q3-board…",
  "appSlug": "q3-board",
  "source": "cli",
  "reporterName": "Dana Reyes",
  "reporterEmail": "dana.reyes@himarley.com",
  "githubUrl": "https://github.com/himarley/drop/issues/142",
  "createdAt": "2026-06-18T15:02:00.000Z",
  "updatedAt": "2026-06-18T15:02:00.000Z",
  "closedAt": null,
  "commentCount": 0
}
GET

Get a Report

/api/reports/{caseNumber}

Fetch one report by case number, including its current status (reconciled from GitHub on read), body, and comment count. Returns 404 if the report isn't yours (and you're not an admin) — no enumeration leak.

Parameters

caseNumber
number· path· required
The case number (= GitHub issue number).
GET/api/reports/{caseNumber}
drop reports get 142
Response200
{
  "caseNumber": 142,
  "kind": "BUG",
  "status": "IN_PROGRESS",
  "title": "PDF export spins forever on the Q3 board",
  "body": "**Steps**: open q3-board…",
  "appSlug": "q3-board",
  "source": "cli",
  "reporterName": "Dana Reyes",
  "reporterEmail": "dana.reyes@himarley.com",
  "githubUrl": "https://github.com/himarley/drop/issues/142",
  "createdAt": "2026-06-18T15:02:00.000Z",
  "updatedAt": "2026-06-18T16:20:00.000Z",
  "closedAt": null,
  "commentCount": 2
}
PATCH

Update a Report

/api/reports/{caseNumber}

Change a report's triage status or open/closed state. Setting status (TRIAGED / IN_PROGRESS / RESOLVED / WONT_FIX) is admin only and writes the corresponding GitHub label/state, then notifies the reporter. state (open / closed) lets the reporter withdraw or reopen their own report.

Parameters

caseNumber
number· path· required
The case number.
status
string· body
New triage status (admin only).
state
string· body
open | closed (reporter or admin).
PATCH/api/reports/{caseNumber}
drop reports set-status 142 --status IN_PROGRESS
Response200
{
  "caseNumber": 142,
  "kind": "BUG",
  "status": "IN_PROGRESS",
  "title": "PDF export spins forever on the Q3 board",
  "body": null,
  "appSlug": "q3-board",
  "source": "cli",
  "reporterName": "Dana Reyes",
  "reporterEmail": "dana.reyes@himarley.com",
  "githubUrl": "https://github.com/himarley/drop/issues/142",
  "createdAt": "2026-06-18T15:02:00.000Z",
  "updatedAt": "2026-06-18T16:20:00.000Z",
  "closedAt": null,
  "commentCount": 2
}
POST

Comment on a Report

/api/reports/{caseNumber}/comments

Add a comment to a report. Posts to the GitHub issue attributed to the reporter (Drop's bot identity writes it; the reporter's name is in the body). Allowed for the reporter or an admin.

Parameters

caseNumber
number· path· required
The case number.
body
string· body· required
The comment text (markdown).
POST/api/reports/{caseNumber}/comments
drop reports comment 142 --body "Still happening on prod this morning."
Response201
{
  "caseNumber": 142,
  "author": "Dana Reyes",
  "body": "Still happening on prod this morning.",
  "url": "https://github.com/himarley/drop/issues/142#issuecomment-1",
  "createdAt": "2026-06-18T17:00:00.000Z"
}
GET

List Report Comments

/api/reports/{caseNumber}/comments

List the comment thread on a report (from the GitHub issue), oldest first. Allowed for the reporter or an admin.

Parameters

caseNumber
number· path· required
The case number.
GET/api/reports/{caseNumber}/comments
drop reports comments 142
Response200
[
  {
    "author": "Dana Reyes",
    "body": "Still happening on prod this morning.",
    "url": "https://github.com/himarley/drop/issues/142#issuecomment-1",
    "createdAt": "2026-06-18T17:00:00.000Z",
    "fromReporter": true
  }
]