Feedback

Tell us what is wrong or missing, and the triage queue ops read.

Generated from openapi.yaml (Btcintel native API 0.1.0). Every hash is canonical display order; every answer carries the index and node heights; errors use one envelope — see Semantics.

GET /v1/ops/feedback — The feedback queue (ops), newest first
PATCH /v1/ops/feedback/{id} — Triage one entry (ops)
DELETE /v1/ops/feedback/{id} — Delete one entry on the requester's word (ops)
POST /v1/feedback — Send feedback (the web sheet, agents, automatic failure reports)

GET `/v1/ops/feedback`

The feedback queue (ops), newest first

Spec S3.4 FR-3: triage list, filtered by status, channel and time, paged by id (cursor = the id to continue below).

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`status`	query	string · one of "new", "triaged", "linked", "closed", "rejected"	—
`channel`	query	string · one of "web", "mcp", "auto"	—
`since`	query	string (date-time)	Entries received at or after this instant.
`cursor`	query	integer	Return entries with an id below this.
`limit`	query	integer · ≤ 200 · default 50	—

Response `200`

A page of entries.

schema

items array of FeedbackEntry required
- id integer required
- at string (date-time) required
- channel string required · one of "web", "mcp", "auto"
- tier string | null — The caller's tier when it arrived.
- subject object
  - kind string
  - key string
- page string | null
- tool string | null
- app_version string | null
- text string required
- details object required
- contact object — The way back the requester left, if any.
  - npub string — 64 hex.
  - key_id integer
- status string required · one of "new", "triaged", "linked", "closed", "rejected"
- triaged_by string | null
- triaged_at string | null (date-time)
- linked_change_url string | null
next_cursor integer | null required — The cursor for the next page; null on the last one.

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).

Example

curl -s https://api.btcintel.io/v1/ops/feedback \
  -H 'Authorization: Bearer $BTCI_KEY' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

PATCH `/v1/ops/feedback/{id}`

Triage one entry (ops)

Spec S3.4 FR-3: set the status, who triaged it (the operator by default) and the PR or changelog entry that answered it (P44). Every patch stamps triaged_at and is audited.

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`id` required	path	integer	—

Request body

schema

status string · one of "new", "triaged", "linked", "closed", "rejected"
triaged_by string — Defaults to the operator making the call. · max length 80
linked_change_url string (uri) — The PR or changelog entry that answered the feedback (P44). · max length 400

Response `200`

The entry after the change.

schema

id integer required
at string (date-time) required
channel string required · one of "web", "mcp", "auto"
tier string | null — The caller's tier when it arrived.
subject object
- kind string
- key string
page string | null
tool string | null
app_version string | null
text string required
details object required
contact object — The way back the requester left, if any.
- npub string — 64 hex.
- key_id integer
status string required · one of "new", "triaged", "linked", "closed", "rejected"
triaged_by string | null
triaged_at string | null (date-time)
linked_change_url string | null

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
404 — Unknown to the index and, for transactions, to the node mempool.
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X PATCH https://api.btcintel.io/v1/ops/feedback/1 \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"status":"linked","linked_change_url":"https://github.com/satsboard-io/btcintel-api/pull/50"}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

DELETE `/v1/ops/feedback/{id}`

Delete one entry on the requester's word (ops)

Spec S3.4 FR-4: only an entry that left a contact (npub or key) can be deleted; entries without one hold no personal data and are kept, so the answer is 409 conflict. Audited.

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`id` required	path	integer	—

Response `204`

Deleted.

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
404 — Unknown to the index and, for transactions, to the node mempool.
409 — The entry left no contact and is kept (conflict).
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X DELETE https://api.btcintel.io/v1/ops/feedback/1 \
  -H 'Authorization: Bearer $BTCI_KEY' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/feedback`

Send feedback (the web sheet, agents, automatic failure reports)

Explicit feedback, never telemetry (spec S3.4 FR-1; P43). Open to every tier within feedback_per_day of the CC-8 ladder, counted per caller per UTC day (in memory, P39): a refused call is quota_exceeded with Retry-After to midnight UTC. channel defaults to web; the MCP tool send_feedback forces mcp; auto is a failure report an agent or the MCP layer sends about a tool error. subject is canonicalised (CC-3) and linked to the subject row; claim_id names the claim the text is about. contact is optional and never an email: an npub (npub1… or 64 hex), a btci_ token, or {"token": true} to link the key sent as the bearer. Text is stored as given and rendered escaped everywhere; nothing is fetched or rendered as HTML. The web sheet renders only while /v1/status.features.feedback is true.

MCP tool: send_feedback — see For agents

Request body

schema

channel string — Who is speaking: the web sheet, an agent over MCP, or an automatic failure report. · one of "web", "mcp", "auto" · default "web"
subject object — The subject the text is about, canonicalised on arrival (CC-3).
- kind string required · one of "address", "script", "tx", "block", "outpoint", "pool", "descriptor", "pubkey"
- key string required
claim_id string — The claim the text is about (ann_123, attr_45…).
page string — The web page or the agent context it came from. · max length 200
tool string — The MCP tool involved, if any. · max length 80
app_version string · max length 40
text string required — Free text, stored as given. · min length 1 · max length 4096
details object — Structured context under 8 KB: error payloads, request ids.
contact one of — Optional, never an email: an npub (npub1… or 64 hex), a btci_ token, or {npub, token} where token: true links the key sent as the bearer.
- string
- object
  - npub string
  - token one of
    - boolean
    - string

Response `201`

Stored; the id to quote when following up.

Headers: Cache-Control

schema

id integer required
status string = "new" required

Errors

400 — Malformed input (invalid_input).
413 — Body over 16 KB (too_large).
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.
501 — Feedback is not enabled on this deployment (not_configured).

Example

curl -s -X POST https://api.btcintel.io/v1/feedback \
  -H 'Content-Type: application/json' \
  -d '{"page":"/tx/71e4dae2…","subject":{"kind":"tx","key":"71e4dae29ed1bc9fe008bba7f3542fd5961b780c220ca8778100a7cb8bd4c81b"},"text":"the label looks wrong"}' | jq

Feedback

GET /v1/ops/feedback

Parameters

Response 200

Errors

Example

PATCH /v1/ops/feedback/{id}

Parameters

Request body

Response 200

Errors

Example

DELETE /v1/ops/feedback/{id}

Parameters

Response 204

Errors

Example

POST /v1/feedback

Request body

Response 201

Errors

Example

GET `/v1/ops/feedback`

Response `200`

PATCH `/v1/ops/feedback/{id}`

Response `200`

DELETE `/v1/ops/feedback/{id}`

Response `204`

POST `/v1/feedback`

Response `201`