Documentation Index
Fetch the complete documentation index at: https://docs.arcmira.com/llms.txt
Use this file to discover all available pages before exploring further.
POST /v1/feedback lets Pro+ integrators correct Arcmira’s commercial classifications inline. Every submission carries a type, the query you ran, and optionally a list of corrections. Supported types apply corrections immediately and re-aggregate downstream rollups; the rest are logged for review.
POST /v1/feedback?type=...
Feedback is gated behind Pro+ and requires the recommendations:write scope. Lower tiers receive 403 recommendations_not_enabled; correctly tiered keys missing the scope receive 403 insufficient_scope. See Scopes. Anatomy of a submission
curl -X POST 'https://api.arcmira.com/v1/feedback?type=recommendations' \
-H "Authorization: Bearer $ARCMIRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": {
"channel_id": "UC-DRzaGnL_vtBUpCFH5M0tg",
"mention_class": "ad_read",
"limit": 100
},
"corrections": [
{ "id": "com_119682", "mention_class": "mention", "reason": "false_positive_ad_read" }
]
}'
type — what surface the feedback is about.query — the parameters of the call you made. Lets reviewers reproduce the exact result set.corrections — optional per-row fixes. Omit for free-form notes-only feedback.
Supported types
type | What it covers | Auto-applies? |
|---|
recommendations | A /v1/recommendations result row. | Yes |
channel_sponsors | A sponsor entity on a channel. | Yes |
mentions | A /v1/mentions row. | Logged |
entities_search | A /v1/entities/search hit. | Logged |
entities | A /v1/entities/{id} payload. | Logged |
channels | A /v1/channels/{slug} payload. | Logged |
api_feedback and api_feedback_corrections for review; nothing changes in the live index until a human looks at them.
Three ways to pass query
The request merges query from three sources (later sources override earlier):
- URL
?query= parameter. Either URL-encoded JSON (?query=%7B%22channel_id%22%3A%22UC-...%22%7D) or a nested query string (?query=channel_id=UC-...&mention_class=ad_read).
- Loose query-string params on the URL itself. Anything other than
type and query is folded into query (e.g. ?channel_id=UC-...&mention_class=ad_read).
- JSON body
query object. The most common form — strongly recommended for non-trivial payloads.
Empty query returns 400 invalid_feedback_request.
Auto-apply behavior
type=recommendations
Each correction targets one row by its com_* ID.
{
"query": { "entity_id": "ent_124261", "mention_class": "ad_read" },
"corrections": [
{ "id": "com_119682", "mention_class": "mention", "reason": "false_positive_ad_read", "notes": "Host was reading from a guest's bio, not a paid promo." }
]
}
id (a com_* ID or numeric recommendation ID) and mention_class (the new class). reason and notes are optional but help the audit trail.
Result per correction:
applied — the row’s class was changed.unchanged — the row already had the target class.not_found — the com_* ID doesn’t exist.invalid — the correction is malformed or the row can’t be corrected (e.g. it was already manually resolved).
After all corrections are processed, Arcmira re-aggregates brand_profiles for every affected entity.
Each correction targets one entity on the channel from query.channel_id. The id must be an ent_*. All matching recommendations rows for that entity on that channel are reclassified.
curl -X POST 'https://api.arcmira.com/v1/feedback?type=channel_sponsors' \
-H "Authorization: Bearer $ARCMIRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": { "channel_id": "UC-DRzaGnL_vtBUpCFH5M0tg", "min_ad_reads": 3 },
"corrections": [
{
"id": "ent_999",
"mention_class": "mention",
"reason": "false_positive_ad_read",
"notes": "One-off guest intro mis-classified as a sponsor read."
}
]
}'
mention_class defaults to mention if omitted. query.channel_id is required for this type.
Other types
mentions, entities_search, entities, and channels corrections are stored with status: logged. Use them to flag wrong-entity attribution, missed appearances, search-ranking issues, or stale channel metadata — Arcmira reviewers triage and apply manually.
Reason codes
| Code | Use for |
|---|
false_positive_ad_read | Pipeline classified a row as ad_read but it isn’t paid. |
false_positive_endorsement | Pipeline classified an organic endorsement that wasn’t there. |
missed_ad_read | A real paid read the pipeline didn’t surface (or classified as mention). |
missed_endorsement | A real endorsement the pipeline missed. |
wrong_classification | Any other class-level error (e.g. ad_read ↔ endorsement). |
wrong_entity | The row attributes the wrong entity (e.g. Apple Inc. vs. Apple fruit). |
other | Free-form. Add detail in notes. |
notes field.
Response shape
{
"feedback_id": 84,
"type": "recommendations",
"query": { "channel_id": "UC-DRzaGnL_vtBUpCFH5M0tg", "mention_class": "ad_read" },
"applied": 1,
"unchanged": 0,
"failed": 0,
"logged": 0,
"corrections": [
{
"item_id": "com_119682",
"item_kind": "recommendation",
"status": "applied",
"previous_mention_class": "ad_read",
"new_mention_class": "mention",
"rows_affected": 1,
"reason": "false_positive_ad_read",
"recommendation": {
"id": "com_119682",
"mention_class": "mention"
}
}
]
}
feedback_id is the row in api_feedback you can quote in support tickets. applied + unchanged + failed + logged always equals corrections.length.
Limits
- Up to 100 corrections per submission. Batch larger workflows across calls.
- A submission with
corrections: [] is valid — useful for free-form notes feedback against a query that returned poor results.
- Reuse the
Idempotency-Key header to make retries safe (cached for 24h, same as watchlists/trackers). See Idempotency.
Errors
| Code | When |
|---|
recommendations_not_enabled | Tier below Pro+. |
insufficient_scope | Pro+ key missing recommendations:write. |
invalid_feedback_request | Missing type, empty query, or malformed ?query= value. |
invalid_body | JSON body failed schema validation (e.g. too many corrections, bad reason). |
