# TinyCloud bug reports

This endpoint collects reports from agents and developers working with TinyCloud: building TinyCloud apps, using the TinyCloud CLI, or signing in with OpenKey. Send one report per problem or suggestion.

Reports are write-only. You get an id back; you can't read or list reports from here. The TinyCloud team reviews them.

## What to report

- **bug**: something broke or behaved differently from the documentation.
- **friction**: it worked, but it was confusing, slow, or took more steps than it should have.
- **improvement**: a change that would make TinyCloud easier or better to use.
- **security**: a possible vulnerability. Security reports are kept separately and reviewed privately. Describe the issue; don't include working exploits against real accounts.

## Never include secrets

Never include secrets, tokens, private keys, seed phrases, passwords, or owner data (other people's files, messages, or personal details) in a report. Replace them with a placeholder such as `<token>`. The server also removes likely secrets before storing a report, but don't rely on that.

## How to send a report

```
curl -sS -X POST https://bugs.tinycloud.xyz/reports \
  -H 'Content-Type: application/json' \
  -d '{
    "area": "cli",
    "kind": "bug",
    "title": "tc kv put fails with a 403 after login",
    "tried": "Ran tc login, then tc kv put notes/a hello",
    "happened": "The put failed with 403 Forbidden; tc whoami still showed the session",
    "expected": "The value is written, or a clear message says which permission is missing",
    "versions": { "cli": "1.2.0", "sdk": "2.1.0" },
    "repro_steps": "1. tc login\n2. tc kv put notes/a hello",
    "agent": "example-agent"
  }'
```

A stored report returns `201 {"id": "<id>"}`. Keep the id if you want to refer to the report later.

## Fields

| Field | Required | Value |
|---|---|---|
| `area` | yes | `app-building`, `cli`, `openkey`, or `other` |
| `kind` | yes | `bug`, `friction`, `improvement`, or `security` |
| `title` | yes | one-line summary, up to 200 characters |
| `tried` | yes | what you were doing, up to 4000 characters |
| `happened` | yes | what actually happened, including error messages, up to 4000 characters |
| `expected` | yes | what you expected instead, up to 4000 characters |
| `versions` | no | object with optional `cli`, `sdk`, `openkey`, `other` strings, up to 100 characters each |
| `repro_steps` | no | steps to reproduce, up to 4000 characters |
| `agent` | no | your agent or client name, up to 100 characters |

The whole body must be JSON, sent with `Content-Type: application/json`, and at most 16 KB. Fields not listed above are rejected.

## Errors

Errors return a 4xx status and `{"error": {"code": "...", "message": "...", "field": "..."}}`. Codes: `unsupported_media_type`, `invalid_json`, `invalid_body`, `unknown_field`, `missing_field`, `empty_field`, `invalid_type`, `invalid_enum`, `field_too_long`, `payload_too_large`, `rate_limited`, `not_found`, `method_not_allowed`.

Each sender is limited to 10 reports a minute. If you get `429 rate_limited`, wait a minute and send again.