Patchy Documentation

Patchy is a bug triage tool built for indie game developers. It collects player-reported bugs from Discord, public pages, and webhooks, then automatically categorizes, scores, and deduplicates them so your team can focus on fixing.

Quick Start

Triage & Algorithm

When a report arrives, Patchy runs it through a triage pipeline that categorizes, scores severity, checks for spam, and detects duplicates. The result determines how the report is routed.

Routing outcomes

What the algorithm does

• Category detection — Classifies reports into categories like Gameplay, UI/UX, Crash, Performance, etc.
• Severity scoring — Assigns a priority level: critical, high, medium, or low.
• Spam filtering — Detects test submissions, gibberish, and non-bug content.
• Duplicate detection — Uses semantic similarity to find existing reports that describe the same issue, with a confidence score.
• Bug grouping — Automatically groups related reports under a single bug ticket with a generated title.

Configuration

You can tune the algorithm per-project in Settings → Algorithm:

• Confidence threshold — Reports below this confidence level are sent to human review instead of being auto-filed.
• Duplicate threshold — How similar two reports need to be before they’re considered duplicates.
• Semantic search — Toggle semantic (meaning-based) matching on or off for duplicate detection and search.
• Platforms — Define target platforms (Windows, Mac, Linux, etc.) so reports can be tagged by platform.

Releases

Releases let you track which bugs were addressed in which version. Each release has a label, optional patch notes, and a list of linked reports.

How releases work

• Creating a release — Add a release from the Releases tab. Give it a version label (e.g. v1.2.0).
• Active release — One release can be “active” at a time. New incoming reports are automatically tagged with the active release.
• Patch notes — Write patch notes in Markdown. These are displayed on the public page’s Releases tab.
• Filtering — Filter your entire report view by release to see what came in during a specific version.
• Discord announcements — Optionally post a release embed to a Discord channel when you publish. See Release Announcements.

Roles & Permissions

Each project has a role-based permission system. The project owner can create custom roles and assign granular permissions to team members.

Built-in roles

Permissions

Roles can be customized with individual permissions including: viewing reports, managing reports, editing project settings, managing members, creating releases, clearing logs, and more. Configure these in Settings → Roles.

Discord Bot

The Patchy Discord bot lets players report bugs directly from your server using slash commands. Reports flow into your dashboard instantly.

Commands

Report flow

1. A player runs /report in a linked channel.
2. If the project has platforms configured (e.g. Windows, Mac, Linux), a dropdown appears for platform selection.
3. A text modal opens where the player describes the bug (10–2,000 characters).
4. Patchy triages the report (category, severity, spam check, duplicate detection) and posts a confirmation embed with the results.
5. A “Attach Screenshots” button appears. The player can send up to 4 images (or 1 video on Pro/Studio) within 2 minutes.

Report to Patchy (context menu)

If someone mentions a bug in chat without using the /report command, anyone can forward that message to Patchy by right-clicking it:

1. Right-click the message containing the bug description.
2. Select Apps → Report to Patchy.
3. If platforms are configured, pick the platform from a dropdown.
4. The message content is submitted as a bug report, attributed to the original message author.
5. A confirmation embed appears with triage results and an option to attach screenshots.

Setup

1. Go to your project’s Settings → Integrations tab in the dashboard.
2. Click Invite Patchy to add the bot to your Discord server.
3. In the Discord channel where you want bug reports, run /setup project:your-slug.
4. The bot will confirm the channel is linked. Players can now use /report and the context menu.

Required bot permissions

The Patchy bot needs the following Discord permissions to function properly:

• Send Messages — Required. Post confirmation embeds and responses.
• Embed Links — Required for release announcements. Enable this in your server’s role settings for the Patchy bot role.
• Read Message History — Needed for the context menu to read the target message content.
• Add Reactions — Used to confirm screenshot uploads with a checkmark.

Release Announcements

Patchy can automatically post a Discord embed when you publish a release. The announcement includes the release title, summary or patch notes, platforms, and a link to the full release page.

Setup

1. Go to Settings → Integrations in your project dashboard.
2. Scroll to the Release Announcements section under the Discord Bot settings.
3. Select the Discord server and channel where announcements should be posted.
4. Click Set.

What gets posted

When a release is published (either on creation or when a draft is published later), the bot posts an embed containing:

• Title — The project name and release label (e.g. “My Game — v1.3.0”).
• Description — The release summary if set, otherwise the first 300 characters of patch notes.
• Platforms — Listed if the release has platform tags.
• Link — A direct link to the full patch notes on the public page.

Behavior

• Announcements are only sent when a release is published — saving a draft or editing an already-published release does not trigger a post.
• One announcement channel per project. You can change or remove it at any time from project settings.
• If the bot loses access to the channel or the server, announcements silently fail — release publishing is never blocked.

GitHub Issues

Two-way sync between Patchy and GitHub Issues. Bugs reported in Patchy automatically become GitHub issues, and issues created or closed on GitHub are reflected back in Patchy.

Setup

1. Go to Settings → Integrations in your project dashboard.
2. In the GitHub Issues section, click Connect GitHub.
3. Authorize Patchy to access your repositories. This grants repo scope so Patchy can create and manage issues on your behalf.
4. Select the repository to link from the dropdown.
5. Click Link. Patchy automatically registers a webhook on the repository to receive issue events.

Patchy → GitHub

• New bug reported — Patchy creates a GitHub issue with the bug summary, severity, and category. The issue body links back to the bug on Patchy.
• Bug resolved — The linked GitHub issue is automatically closed.
• Bug unresolved — The linked GitHub issue is reopened.

GitHub → Patchy

• New issue opened — A report is created in Patchy from the issue title and body. It goes through the normal triage pipeline (scoring, duplicate detection, etc.).
• Issue closed — The linked Patchy bug is resolved.
• Issue reopened — The linked Patchy bug is unresolved.

Behavior

• One repository per project. You can change or remove the link at any time.
• Duplicate reports that merge into an existing bug do not create additional issues.
• Actions triggered by Patchy on GitHub (e.g. closing an issue) do not loop back — Patchy ignores its own events.
• Removing the integration also removes the webhook from the repository. Existing issues on GitHub are not deleted.
• If the GitHub token expires or is revoked, sync silently fails — report processing is never blocked. Reconnect GitHub from project settings to restore it.

Inbound Webhooks

Each project has a unique webhook token you can use to submit reports programmatically — from in-game report forms, CI pipelines, or custom tools. No authentication beyond the token is needed.

Submit a report

POST /webhook/{token}
Content-Type: application/json

{
  "text": "The game crashes when I open the inventory after loading a save.",
  "source": "in-game",
  "reporter": "player123",
  "platform": "Windows"
}

Response

On success, you get back the full triaged report with category, severity, confidence, routing decision, and duplicate detection results:

{
  "id": 42,
  "text": "The game crashes when I open the inventory...",
  "category": "crash",
  "severity": "high",
  "confidence": 0.87,
  "routing": "algorithm",
  "isSpam": false,
  "isDuplicate": false,
  "duplicateOf": null,
  "source": "in-game",
  "reporter": "player123",
  "platform": "Windows",
  "createdAt": "2026-07-06T14:30:00.000Z",
  "bugId": 12
}

Attachments

To include screenshots or video with a webhook report, use a two-step upload flow:

1. Upload files first — POST each file to /webhook/{token}/upload with a unique uploadToken.
2. Submit the report — Include the same uploadToken in your report body. The files are linked automatically.

curl -X POST https://patchyapp.com/webhook/{token}/upload \
  -F "file=@screenshot.png" \
  -F "uploadToken=my-unique-token-123"

curl -X POST https://patchyapp.com/webhook/{token} \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Inventory screen is broken",
    "uploadToken": "my-unique-token-123"
  }'

Error responses

Outbound Webhooks

Webhooks let you push Patchy events to your own HTTP endpoints. Use them to pipe reports into Trello, Notion, Slack, or your own tools.

Setup

1. Go to Settings → Webhooks in your project.
2. Add a webhook URL (must be HTTPS).
3. Choose which events to subscribe to.
4. Patchy generates a signing secret — use it to verify payloads.

Events

Verifying signatures

Every webhook request includes a X-Patchy-Signature header containing an HMAC-SHA256 hex digest of the request body, signed with your webhook’s secret. Verify it before processing:

import { createHmac } from 'crypto';

function verifySignature(body, signature, secret) {
  const expected = createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return expected === signature;
}

// In your handler:
const sig = req.headers['x-patchy-signature'];
const raw = JSON.stringify(req.body); // or use raw body
if (!verifySignature(raw, sig, YOUR_WEBHOOK_SECRET)) {
  return res.status(401).send('Invalid signature');
}

The X-Patchy-Event header also contains the event name (e.g. report.created) for quick routing.

Outbound Webhook Payloads

All outbound webhook deliveries are POST requests with a JSON body. The structure is the same across all events:

{
  "event": "report.created",
  "timestamp": "2026-07-06T14:30:00.000Z",
  "data": {
    "id": 42,
    "text": "Game freezes on the title screen after the update.",
    "category": "crash",
    "severity": "high",
    "confidence": 0.87,
    "routing": "algorithm",
    "isSpam": false,
    "isDuplicate": false,
    "duplicateOf": null,
    "reporter": "player123",
    "source": "discord",
    "platform": "Windows",
    "createdAt": "2026-07-06T14:30:00.000Z",
    "releaseId": 5,
    "bugId": 12
  }
}

Headers

API Authentication

The Patchy API lets you read and manage bugs from external tools, scripts, or CI/CD pipelines. All API endpoints require a project API key.

Generating a key

1. Go to Settings → Integrations in your project dashboard.
2. Click Generate API Key.
3. Copy the key immediately — it is shown only once and cannot be retrieved later.

Using the key

Send the key in the Authorization header as a Bearer token:

GET /api/v1/my-game/bugs
Authorization: Bearer pk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Rate limits

60 requests per minute per API key. If you exceed this, you’ll receive a 429 Too Many Requests response. Wait and retry.

Scope

• Each key is scoped to a single project — the slug in the URL must match the project the key belongs to.
• One key per project. Regenerating creates a new key and invalidates the old one.
• Only the project owner can generate, regenerate, or revoke keys.

Error responses

Bug Endpoints

All endpoints are prefixed with /api/v1/{slug} where {slug} is your project slug.

List bugs

GET /api/v1/{slug}/bugs
Authorization: Bearer YOUR_API_KEY

{
  "bugs": [
    {
      "id": 12,
      "summary": "Screen goes black when opening inventory",
      "category": "ui",
      "severity": "high",
      "reportCount": 3,
      "resolvedAt": null,
      "createdAt": "2026-07-01T10:00:00.000Z"
    }
  ]
}

Get bug details

GET /api/v1/{slug}/bugs/{id}
Authorization: Bearer YOUR_API_KEY

Returns the bug object plus all linked reports.

{
  "bug": {
    "id": 12,
    "summary": "Screen goes black when opening inventory",
    "category": "ui",
    "severity": "high",
    "reportCount": 3,
    "resolvedAt": null
  },
  "reports": [
    {
      "id": 42,
      "text": "The screen went black when I opened my inventory...",
      "reporter": "player123",
      "source": "discord",
      "createdAt": "2026-07-01T10:00:00.000Z"
    }
  ]
}

Update a bug

PATCH /api/v1/{slug}/bugs/{id}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "category": "crash",
  "severity": "critical",
  "status": "investigating",
  "summary": "Updated title",
  "description": "Additional context"
}

All fields are optional. Include only the fields you want to change.

Resolve a bug

POST /api/v1/{slug}/bugs/{id}/resolve
Authorization: Bearer YOUR_API_KEY

Marks the bug (and all linked reports) as resolved. Returns 400 if already resolved. Fires a bug.resolved outbound webhook.

Unresolve a bug

POST /api/v1/{slug}/bugs/{id}/unresolve
Authorization: Bearer YOUR_API_KEY

Reopens a resolved bug. Returns 400 if not resolved. Fires a bug.unresolved outbound webhook.

Common errors

Public Pages

Each project can have a public-facing page at /p/your-slug. Players can view known bugs, check server status, browse releases, and submit reports — no Patchy account required.

What’s included

• Overview tab — Project description, server status banner, and a customizable overview section (Markdown supported).
• Bugs tab — A list of known, confirmed bugs with category and severity. Players can upvote bugs to help prioritize.
• Releases tab — Release history with patch notes. Each release links to the bugs it addressed.
• Report form — A “Report a Bug” button that opens a submission form with optional screenshot/video uploads.

Access controls

In project settings, you can configure who can submit reports through the public page:

Server status

Set your game’s server status from the dashboard (online, degraded, maintenance, or offline). A banner appears on the public page whenever the status is not “online”, with an optional custom message.