A Bug Report API for Games: Submit Reports from Launchers, Servers and Tools

Quick answer: Send a POST to https://api.bugnet.io/api/bugs/submit with your project's key in the X-API-Key header and a JSON body with at least a title and description. Optional fields cover priority, category, platform, version, device, steps, a base64 screenshot, up to 16 KB of metadata and up to 10 attachments. By default, reports with the same title stack onto one bug. It is the same endpoint every Bugnet SDK uses, available on every plan.

Engine SDKs cover the game itself. Bugs also come from everywhere around it: the launcher that fails to patch, the dedicated server that throws, the QA script that finds a broken level, the support form on your website, or a custom engine with no SDK at all. A plain HTTP API lets all of them file into the same tracker as your crashes and player reports.

What this guide covers

The request
Fields
Responses
Examples
Where teams use it
Good practice
Frequently asked questions

The request

curl -X POST https://api.bugnet.io/api/bugs/submit \
  -H "X-API-Key: sk_live_YOUR_PROJECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launcher patch failed: checksum mismatch",
    "description": "Patch 1.4.2 failed to apply on pak 3.",
    "category": "network",
    "priority": "high",
    "platform": "Windows",
    "game_version": "1.4.2",
    "metadata": { "launcher_version": "2.0.1", "pak": 3 }
  }'

Fields

Field	Notes
`title`	Required, up to 300 characters. With grouping on (the default), reports with the exact same title stack onto one bug.
`description`	Required. Truncated to 60,000 bytes.
`priority`	`critical`, `high`, `medium` (default) or `low`
`category`	`crash`, `visual`, `gameplay`, `performance`, `audio`, `ui`, `network` or `other` (default)
`platform`, `game_version`, `os_info`, `device_info`	Context strings (50, 50, 100 and 200 characters)
`steps_to_reproduce`, `expected_behavior`, `actual_behavior`	Free text
`screenshot`	A base64-encoded image
`steam_id`, `reporter_name`, `reporter_email`	Links the report to a player; invalid emails are dropped
`metadata`	Any JSON value up to 16 KB, stored with the report
`attachments`	Up to 10 files (`filename`, `mime_type`, base64 `data`)
`auto_captured`	Set to `true` for machine-filed errors to keep your own category and priority

Responses

201: a new report was created. The response includes its id, report_number, the category and priority it ended up with, and up to three possible_duplicates.
200 with deduplicated: true: the report was stacked onto an existing bug with the same title, and occurrence_count went up.
400: missing title or description, an invalid priority or category, or malformed JSON. 401: a wrong key, or the project's Public setting is turned off (keys only work while it is on, which is the default). 403: the account reached its plan's report limit. 429: rate limited.

If you leave category and priority at their defaults and do not set auto_captured, Bugnet infers both from the text. To attach a large file after the fact, POST it to /api/bugs/{id}/attachments with the id from the response (text, image, video and JSON files up to 10 MB).

Examples

Python (standard library)

import json, urllib.request

def report_bug(title, description, **fields):
    body = json.dumps({"title": title, "description": description, **fields}).encode()
    req = urllib.request.Request(
        "https://api.bugnet.io/api/bugs/submit", data=body, method="POST",
        headers={"X-API-Key": "sk_live_YOUR_PROJECT_KEY", "Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=15) as resp:
        return json.load(resp)

JavaScript (Node 18+ or browser)

await fetch('https://api.bugnet.io/api/bugs/submit', {
  method: 'POST',
  headers: { 'X-API-Key': 'sk_live_YOUR_PROJECT_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'Server: match failed to start', description: err.stack, category: 'network', auto_captured: true }),
});

Where teams use it

Launchers and patchers, which run before the game and its SDK.
Dedicated servers and backends, for errors that should sit next to the client bugs they cause.
QA and test automation, filing a bug when a scripted run fails, with the log as an attachment.
Custom engines and frameworks without an SDK.
Website or Discord bot forms. For a ready-made form on a web page, see adding a bug report widget to your game's website.

Good practice

Keep titles stable. Grouping matches the exact title, so put variable values (ids, timestamps) in the description or metadata, not the title.
Respect rate limits. Public endpoints allow 30 requests a minute per IP; batch or throttle automated reporters.
Remember the quota. Every report, including stacked repeats, counts toward your plan's report limit.

Create a free project to get a key; the full spec is in the API explorer.

Frequently asked questions

Is there an API to submit game bug reports?

Yes. Bugnet's POST /api/bugs/submit endpoint accepts a JSON bug report authenticated with your project's API key in the X-API-Key header. It is the same endpoint the engine SDKs use.

Which fields are required?

Only title and description. Priority, category, platform, version, device, steps, a screenshot, metadata and attachments are optional.

How does Bugnet handle duplicate reports from the API?

With grouping on, which is the default, a report whose title exactly matches an existing report is stacked onto it, the response says deduplicated: true, and the occurrence count goes up. Grouping can be turned off per project.

What is the rate limit?

Public endpoints allow 30 requests per minute per IP address.

Can I attach files to an API report?

Yes. Include up to 10 attachments in the submit request, or upload one afterwards to /api/bugs/{id}/attachments. Text, image, video and JSON files up to 10 MB are accepted.

Bugs do not only happen inside the game. Give every part of your stack a way to report them to the same place.