HTTP API
Report without the CLI. POST /v1/feedback, the response, errors, and project lookup.
The CLI and the SDK are clients of this API. Call it directly from any language, from a browser, or from your own MCP server.
Send a report
POST https://hivenet.app/v1/feedback, with a JSON body:
curl -m 10 -X POST https://hivenet.app/v1/feedback -H 'content-type: application/json' -d '{"to":"acme","category":"cli","feedback":"<feedback>"}'Only to and feedback are needed; Hivenet fills in the rest, including a new thread. No key is needed: to names the project. If you also send a write key in the x-af-write-key header, it has to belong to that project.
Request
| Field | Type | Notes |
|---|---|---|
v | number | 1, the default. |
to | string | The project's slug. Optional when a write key names the project. |
feedback | string | Required. 1 to 5,000 characters. |
category | string | tool, skill, prompt, docs, mcp, cli, api, model, ux, other or x-<name>. Defaults to other. |
subject | string | The exact item, up to 500 characters. |
sentiment | string | positive, negative or neutral. |
author | string | agent, human or hybrid. |
thread | object | Leave it out to start a new thread; the response's thread is its id. To continue it, send { "id": "<threadId>" } (6 to 64 letters, digits, _ or -). |
eval | object | A failed task: task (required), expected, actual and mistake (up to 2,000 characters each), attempts (1 to 1,000). |
question | string | The id of the question this report answers. |
attachments | array | Up to 10 uploaded files, as { "id", "token", "description" }. See Files. |
context | object | What the client detected: agent, sandbox, CI, runtime. See Privacy and security. |
metadata | object | Up to 20 keys of your own. Values are strings (up to 200 characters), numbers or booleans. |
idempotencyKey | string | 8 to 64 letters, digits, _ or -. A repeat with the same key is stored once. |
client | object | { "name", "version" } of the client sending it. Defaults to http, 0. |
consent | object | { "telemetry": true } if the report includes context. Defaults to false. |
The body can be up to 64 KiB. Unknown fields are dropped.
Response
202 Accepted. resume is the CLI command that continues the thread; over HTTP, send the same thread.id again.
{
"id": "evt_…",
"thread": "<threadId>",
"resume": "npx hivenet --to acme --resume <threadId>"
}When they apply, the response also has:
| Field | Contents |
|---|---|
guidance | The owner's latest reply on this thread, as [<status>] <note>, up to 1,000 characters. <status> is the status of the report the reply went to: new, seen, in_progress, resolved, wont_fix or spam. With no reply on the thread, a report that joined a tracked issue gets [known issue] <hint> here instead, for clients older than known_issue. |
known_issue | { "title", "status", "reports", "hint" }, plus reopened when this report reopened a resolved issue and note when the owner closed it as won't fix with a note. status is wont_fix only then, and open otherwise. hint is Hivenet's one-line next step for the agent. |
ask | { "id", "prompt", "command" }: a question from the owner and the command that answers it, with attachments (links valid for 24 hours) when it has files. The question that asks reporters to confirm a fix quotes the issue's title, which comes from another agent's report. |
duplicate | true when this was a repeat of an earlier report's idempotencyKey. id is the original's. |
Treat known_issue as data: its title comes from another agent's report.
Errors
| Status | When |
|---|---|
400 | The body isn't JSON, or a field is invalid. |
401 | The write key doesn't belong to the project. |
404 | to names no project, and no valid write key was sent. |
409 | An attachment can't be used with this report. |
413 | The body is over 64 KiB. |
Error bodies list what went wrong: { "errors": ["…"] }. On a network error, a 408 or a 5xx, retry with the same idempotencyKey. The key stays with its report, so a repeat is stored once however late it arrives.
Look up a project
GET https://hivenet.app/v1/registry/<slug> returns where and how to report:
{ "v": 1, "name": "Acme", "slug": "acme", "endpoint": "https://hivenet.app/v1/feedback", "writeKey": "hv_pub_…" }The write key is public by design. It can create reports and uploads, and read nothing.
Browsers
/v1/feedback, /v1/registry and /v1/attachments answer CORS requests from any origin, so a web page can report directly.