# 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, and they aren't public. Only signed-in people and agents on the TinyCloud team read 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 reviewed privately. Describe the issue; don't include working exploits against real accounts.

## Ask your owner first

Before you send anything, ask the person you work for:

> I ran into some issues with TinyCloud. Can I send a report to help the TinyCloud devs improve how agents use TinyCloud?

Show them a short summary of what you'll send: the title, one line on what happened, and which attachments you'll add. Send only if they say yes. If they say no, send nothing.

Ask once. If they say no, don't ask again about the same problem.

## Never include secrets

Never include secrets, tokens, private keys, seed phrases, passwords, or personal data, whether it's your owner's files and messages or other people's details. Replace them with a placeholder such as `<token>`. The server tries to remove secrets before storing a report, but it can miss some, so don't rely on it.

## How to send a report

```
curl -sS -X POST https://feedback.tinycloud.xyz/reports \
  -H 'Content-Type: application/json' \
  -d '{
    "area": "cli",
    "kind": "bug",
    "title": "tinycloud kv put fails with a 403 after login",
    "tried": "Ran tinycloud login, then tinycloud kv put notes/a hello",
    "happened": "The put failed with 403 Forbidden; tinycloud 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. tinycloud login\n2. tinycloud kv put notes/a hello",
    "agent": "example-agent"
  }'
```

A stored report returns `201 {"id": "<id>", "attach_token": "<token>", "attach_expires_at": "<time>"}`. Keep the id if you want to refer to the report later. The attach token is shown only once. Keep it only until you've added your attachments, and don't share it.

Tell your owner in one line what you reported, with the id.

## Attach a trace

A trace helps the team reconstruct what happened. It should list:

- the steps you took, in order, with timestamps or durations if you have them;
- each command you ran, its exit code, and its error output;
- versions of the CLI, SDK and OpenKey, and the operating system.

Leave out your owner's own words and file contents, or replace them with placeholders such as `<message>` or `<file contents>`. Leave out names, emails, user names in paths (write `/home/<user>/`), account and space ids, DIDs, addresses, and anything secret.

Attach it to the report within 24 hours, using the report's attach token:

```
curl -sS -X POST https://feedback.tinycloud.xyz/reports/<id>/attachments \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <attach_token>' \
  -d '{"type": "trace", "name": "trace.txt", "content": "1. tinycloud login: exit 0\n2. tinycloud kv put notes/a hello: exit 1, 403 Forbidden"}'
```

`type` is `trace`, `cli-log` or `other`; `name` is optional (up to 100 characters). Each attachment can be up to 256 KB of JSON, and a report takes up to 5 attachments. The server tries to remove secrets, user names in paths, DIDs, addresses, UUIDs and IP addresses before storing an attachment, but it can miss some, so leave them out yourself.

Reports and attachments are deleted automatically after 90 days.

## 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 or 5xx 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`, `too_deep`, `intake_busy`, and for attachments `invalid_attach_token` and `attachment_limit`.

Each sender is limited to 10 requests a minute, reports and attachments together. If you get `429 rate_limited`, wait a minute and send again. `503 intake_busy` means the service has taken all the reports and attachments it can for now, from everyone. Try again later, not right away; it can take a day or more.

`too_deep` means the JSON is nested too deeply; keep the body as flat as the example.

## For agents

- API description: https://feedback.tinycloud.xyz/openapi.json
- Agent skill: https://feedback.tinycloud.xyz/.well-known/agent-skills/index.json
- How the TinyCloud team signs in to read reports: https://feedback.tinycloud.xyz/auth.md