> ## 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. > ## Agent Instructions > Arcmira has three API capabilities: Search (entities, mentions, appearances, commercial intelligence), Monitors (trackers plus alert delivery), and Transcripts (read, generate, correct). Community Review is the cross-surface correction layer. > Discover pages at https://docs.arcmira.com/llms.txt, then fetch the matching page's .md export. Each capability has a self-contained ' for coding agents' page; prefer it. > Auth: Authorization: Bearer arc_sk_... or x-api-key: arc_sk_... (x-api-key wins if both are sent). Never put keys in browser code. Check GET /v1/me for tier, scopes, and remaining rows before metered pulls. > Search: resolve names with GET /v1/entities/lookup and pin ent_* IDs before pulling metered rows. Only person entities have appearances. Mention and recommendation rows carry canonical numeric timestamps in start_seconds/end_seconds (integer seconds; 0 means full episode); the MM:SS string fields are deprecated. Commercial routes need Pro+ tier AND the recommendations:read scope and bill 10 rows per row. > Monitors: a tracker watches one entity; a monitor groups trackers with shared delivery (email, Slack, HMAC-signed webhooks). Create trackers with POST /v1/trackers, then attach by id: POST /v1/monitors/{id}/trackers { trackerIds: [...] }. Each fired alert occurrence debits 100 rows. Poll GET /v1/monitors/{id}/alerts?n= for recent deliveries. Send Idempotency-Key on every POST/PATCH. > Transcripts: switch on the access field (unlocked, locked, premium_pending, not_transcribed, unauthenticated). Honor Retry-After when polling POST /v1/transcriptions jobs. Corrections (POST /v1/videos/{video_id}/corrections; kinds line_edit, speaker_reassign, speaker_identify, add_person, entity_tag, segment_rewrite) cost 0 rows; anchored kinds need revision + anchor.contentHash (djb2 base-36); handle 409 (re-anchor) and 412 (expectedSeq). segment_rewrite replaces an inclusive segment range with new segments (empty replacements array deletes; timestamps repaired server-side). > Community Review is free (0 rows) and surface-typed: POST /v1/feedback with a type matching the surface you called, the reproducing query, and corrections targeting public IDs (ent_*, men_*, com_*). Nothing auto-applies. Do not send untyped notes. > Errors: switch on error.code, follow doc_url, quote X-Request-Id to support. Honor Retry-After on 429. Retries of POST/PATCH must reuse the same Idempotency-Key; replays return Idempotency-Replayed: true. # Submit feedback and corrections for a prior API query > Attach corrections to the exact query you ran: pass the feedback type, the query object you sent, and optional per-item corrections. Public submissions are recorded for human review (status "logged"); nothing is auto-applied. Read the review status back later via GET /v1/feedback/{feedback_id}. recommendations and channel_sponsors feedback types require the recommendations:read scope; every other type needs read. monitor_alert feedback targets fired alert rows: query carries monitor_id and/or tracker_id and/or alert_id, corrections target the alert row id, and every referenced alert row must belong to the caller (otherwise 404 alert_not_found). missed_alert corrections are expectations with no row to target: omit the correction id and put { source_url, approximate_timestamp_seconds?, entity_id? } in suggested_change. delivery_issue corrections may carry { channel } in suggested_change. Supports the Idempotency-Key header. ## OpenAPI ````yaml /openapi/arcmira-v1.json post /v1/feedback openapi: 3.1.0 info: title: Arcmira API version: 1.0.0 contact: name: Arcmira url: https://arcmira.com servers: - url: https://api.arcmira.com security: [] paths: /v1/feedback: post: tags: - Feedback summary: Submit feedback and corrections for a prior API query description: >- Attach corrections to the exact query you ran: pass the feedback type, the query object you sent, and optional per-item corrections. Public submissions are recorded for human review (status "logged"); nothing is auto-applied. Read the review status back later via GET /v1/feedback/{feedback_id}. recommendations and channel_sponsors feedback types require the recommendations:read scope; every other type needs read. monitor_alert feedback targets fired alert rows: query carries monitor_id and/or tracker_id and/or alert_id, corrections target the alert row id, and every referenced alert row must belong to the caller (otherwise 404 alert_not_found). missed_alert corrections are expectations with no row to target: omit the correction id and put { source_url, approximate_timestamp_seconds?, entity_id? } in suggested_change. delivery_issue corrections may carry { channel } in suggested_change. Supports the Idempotency-Key header. operationId: submit_feedback parameters: - schema: type: string enum: - recommendations - channel_sponsors - mentions - entities_search - entities - channels - monitor_alert - appearances - search description: >- The surface being reviewed. Values: recommendations (/v1/recommendations rows by com_* id; requires recommendations:read), channel_sponsors (sponsor entities on a channel; requires recommendations:read), mentions (/v1/mentions rows by men_* id), entities_search (/v1/entities/search hits), entities (/v1/entities/lookup and /v1/entities/{id} payloads), channels (/v1/channels/{slug} payloads), monitor_alert (fired alert rows from /v1/monitors/{id}/alerts or /v1/trackers/{id}/alerts; corrections target the alert row id), appearances (person appearance rows), search (rows from /v1/search or /v1/entities/search). required: true description: >- The surface being reviewed. Values: recommendations (/v1/recommendations rows by com_* id; requires recommendations:read), channel_sponsors (sponsor entities on a channel; requires recommendations:read), mentions (/v1/mentions rows by men_* id), entities_search (/v1/entities/search hits), entities (/v1/entities/lookup and /v1/entities/{id} payloads), channels (/v1/channels/{slug} payloads), monitor_alert (fired alert rows from /v1/monitors/{id}/alerts or /v1/trackers/{id}/alerts; corrections target the alert row id), appearances (person appearance rows), search (rows from /v1/search or /v1/entities/search). name: type in: query - schema: type: string minLength: 1 required: false name: query in: query requestBody: content: application/json: schema: type: object properties: type: type: string enum: - recommendations - channel_sponsors - mentions - entities_search - entities - channels - monitor_alert - appearances - search description: >- The surface being reviewed. Values: recommendations (/v1/recommendations rows by com_* id; requires recommendations:read), channel_sponsors (sponsor entities on a channel; requires recommendations:read), mentions (/v1/mentions rows by men_* id), entities_search (/v1/entities/search hits), entities (/v1/entities/lookup and /v1/entities/{id} payloads), channels (/v1/channels/{slug} payloads), monitor_alert (fired alert rows from /v1/monitors/{id}/alerts or /v1/trackers/{id}/alerts; corrections target the alert row id), appearances (person appearance rows), search (rows from /v1/search or /v1/entities/search). query: type: object additionalProperties: {} description: >- The query object that produced the result you are reviewing, echoed back verbatim so reviewers can replay it. For monitor_alert feedback, carry monitor_id and/or tracker_id and/or alert_id. endpoint: type: string maxLength: 500 method: type: string enum: - GET - POST - PATCH - PUT - DELETE request_id: type: string maxLength: 200 result_url: type: string maxLength: 2000 source_url: type: string maxLength: 2000 notes: type: string maxLength: 4000 corrections: type: array items: type: object properties: id: type: string minLength: 1 description: >- Public id of the row being corrected, from the response you received: men_* (mentions, appearances), com_* (recommendations), ent_* (entities, sponsors), or the alert row id (monitor_alert). Omit for missed_alert and missing_result corrections, which have no row to target. mention_class: type: string enum: - ad_read - endorsement - mention reason: type: string enum: - false_positive_ad_read - false_positive_endorsement - missed_ad_read - missed_endorsement - wrong_classification - wrong_entity - other issue_type: type: string enum: - wrong_entity_type - wrong_entity - duplicate_entity - merge_suggestion - missing_result - stale_metadata - wrong_classification - bad_ranking - false_positive_alert - wrong_media - wrong_timestamp - duplicate_alert - missed_alert - delivery_issue - person_not_present - wrong_person - wrong_appearance_role - other description: >- Issue classification for the correction. Entity-family values: wrong_entity_type (right entity, wrong type), wrong_entity (the row points at the wrong canonical entity), duplicate_entity (results split across variants of the same entity), merge_suggestion (propose the canonical merge for split variants), missing_result (a result you know should exist is absent), stale_metadata (name/website/channel metadata is outdated), wrong_classification (class-level error on a commercial row), bad_ranking (duplicates or aliases ranking above the canonical entity). monitor_alert values: false_positive_alert (the alert should not have fired), wrong_media (fired against the wrong video), wrong_timestamp (fired at the wrong position in the video), duplicate_alert (the same occurrence fired more than once), missed_alert (an expectation: an alert that should have fired but did not; no row to target), delivery_issue (the delivery itself was wrong: wrong channel, not received). appearances values: person_not_present (the person does not appear in the media), wrong_person (the appearance is attributed to the wrong person), wrong_appearance_role (right person, wrong role, e.g. guest vs host). other (escape hatch; detail in notes). suggested_change: anyOf: - $ref: '#/components/schemas/MergeSuggestionChange' - $ref: '#/components/schemas/WrongEntityChange' - $ref: '#/components/schemas/WrongEntityTypeChange' - $ref: '#/components/schemas/MissingResultChange' - $ref: '#/components/schemas/WrongClassificationChange' - $ref: '#/components/schemas/StaleMetadataChange' - $ref: '#/components/schemas/BadRankingChange' - $ref: '#/components/schemas/MissedAlertChange' - $ref: '#/components/schemas/DeliveryIssueChange' - $ref: '#/components/schemas/FreeformSuggestedChange' description: >- Your concrete proposed fix, shaped by issue_type: merge_suggestion → MergeSuggestionChange, wrong_entity/wrong_person → WrongEntityChange, wrong_entity_type → WrongEntityTypeChange, missing_result → MissingResultChange, wrong_classification → WrongClassificationChange, stale_metadata → StaleMetadataChange, bad_ranking → BadRankingChange, missed_alert → MissedAlertChange, delivery_issue → DeliveryIssueChange. Unknown keys are accepted and logged verbatim; only non-object values are rejected. Omit suggested_change entirely when you do not have a concrete fix. notes: type: string maxLength: 2000 maxItems: 100 responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/FeedbackResponse' '400': description: Invalid request content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string param: type: string doc_url: type: string request_id: type: string required: - type - code - message - doc_url - request_id required: - error '401': description: Authentication error content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string param: type: string doc_url: type: string request_id: type: string required: - type - code - message - doc_url - request_id required: - error '402': description: Quota exceeded content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string param: type: string doc_url: type: string request_id: type: string required: - type - code - message - doc_url - request_id required: - error '403': description: Permission error content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string param: type: string doc_url: type: string request_id: type: string required: - type - code - message - doc_url - request_id required: - error '404': description: Not found content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string param: type: string doc_url: type: string request_id: type: string required: - type - code - message - doc_url - request_id required: - error '409': description: Conflict content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string param: type: string doc_url: type: string request_id: type: string required: - type - code - message - doc_url - request_id required: - error '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string param: type: string doc_url: type: string request_id: type: string required: - type - code - message - doc_url - request_id required: - error '500': description: Server error content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string param: type: string doc_url: type: string request_id: type: string required: - type - code - message - doc_url - request_id required: - error security: - bearerAuth: [] - apiKeyAuth: [] components: schemas: MergeSuggestionChange: type: object properties: sourceEntityId: type: string description: Public id ("ent_{n}") of the duplicate/variant entity to merge away. targetEntityId: type: string description: Public id ("ent_{n}") of the canonical entity to merge into. sourceName: type: string description: Name of the duplicate entity when you do not have its id. merge_into: type: string description: >- Name or public id of the canonical entity when you do not have targetEntityId. scopeType: type: string description: Scope of the merge rule, e.g. "global". additionalProperties: {} description: >- For issue_type merge_suggestion (and duplicate_entity): the canonical merge you are proposing. Provide ids when you have them, names otherwise. WrongEntityChange: type: object properties: entity_id: type: string description: Public id ("ent_{n}") of the entity the row should point at. entity_name: type: string description: Name of the correct entity when you do not have its id. entity_type: type: string description: >- Type of the correct entity: person, organization, product, topic, or channel. additionalProperties: {} description: >- For issue_type wrong_entity (and wrong_person): the entity the row should have been attributed to. WrongEntityTypeChange: type: object properties: field: type: string enum: - type description: Always "type". value: type: string description: >- The correct entity type: person, organization, product, topic, or channel. additionalProperties: {} description: >- For issue_type wrong_entity_type: { "field": "type", "value": "organization" }. MissingResultChange: type: object properties: name: type: string description: Name of the missing entity or result. entity_type: type: string description: >- Type of the missing entity: person, organization, product, topic, or channel. source_url: type: string description: URL evidencing the missing result (video, channel, or article). additionalProperties: {} description: >- For issue_type missing_result: what should have been returned. Put video/channel/timestamp context in notes. WrongClassificationChange: type: object properties: mention_class: type: string enum: - ad_read - endorsement - mention description: >- The correct commercial classification. Values: ad_read (a paid sponsorship read), endorsement (an unpaid personal recommendation), mention (a neutral commercial mention). additionalProperties: {} description: >- For issue_type wrong_classification: the commercial class the row should carry. StaleMetadataChange: type: object properties: field: type: string description: The metadata field that is outdated, e.g. "website" or "name". value: description: The current, correct value. source_url: type: string description: URL evidencing the correct value. additionalProperties: {} description: >- For issue_type stale_metadata: the field and its correct value, with a source URL when you have one. BadRankingChange: type: object properties: expected_rank: type: integer description: Where the row should have ranked (1-based). observed_rank: type: integer description: >- Where the row actually ranked (1-based). Most useful on search feedback. additionalProperties: {} description: >- For issue_type bad_ranking: the expected and observed positions of the row. MissedAlertChange: type: object properties: source_url: type: string description: URL of the media that should have produced an alert. approximate_timestamp_seconds: type: number description: >- Approximate position of the missed occurrence, in seconds from the start of the media. entity_id: type: string description: >- Public id ("ent_{n}") of the tracked entity the missed alert concerns. required: - source_url additionalProperties: {} description: >- For issue_type missed_alert: an expectation with no alert row to target. Omit the correction id and describe where the alert should have fired. DeliveryIssueChange: type: object properties: channel: type: string enum: - email - webhook - slack description: >- The delivery channel the issue concerns. Values: email, webhook, slack. required: - channel additionalProperties: {} description: >- For issue_type delivery_issue: targets the delivery row (the correction id) and names the channel that was wrong or never received. FreeformSuggestedChange: type: object additionalProperties: {} description: >- Any other object shape. Accepted and logged verbatim for human review; prefer the typed shapes above when one fits your issue_type. FeedbackResponse: type: object properties: feedback_id: type: integer description: >- Id of the persisted feedback record. Read it back via GET /v1/feedback/{feedback_id}. type: type: string description: >- The feedback type you submitted. Values: recommendations, channel_sponsors, mentions, entities_search, entities, channels, monitor_alert, appearances, search. query: type: object additionalProperties: {} description: The query object the feedback is attached to, echoed back. applied: type: integer description: >- Count of corrections applied automatically. CURRENTLY always 0: public submissions are logged for review, never auto-applied. unchanged: type: integer description: >- Count of corrections whose target already had the requested value. Currently always 0 for public submissions. failed: type: integer description: >- Count of corrections that could not be processed. Currently always 0 for public submissions. logged: type: integer description: Count of corrections recorded for human review. corrections: type: array items: $ref: '#/components/schemas/FeedbackCorrectionResult' description: Per-correction outcomes, in submission order. required: - feedback_id - type - query - applied - unchanged - failed - logged - corrections FeedbackCorrectionResult: type: object properties: item_id: type: string description: >- The correction target id you supplied (or a generated placeholder when omitted). item_kind: type: string description: >- Inferred kind of the target. Values include: recommendation, sponsor_entity, entity, entity_merge, mention, appearance, alert, alert_expectation, unknown. status: type: string enum: - applied - unchanged - not_found - invalid - logged description: >- Outcome. Values: applied (the correction was applied automatically), unchanged (the target already had the requested value), not_found (the target does not exist), invalid (the correction payload was malformed for its kind), logged (recorded for human review; no automatic apply). previous_mention_class: type: - string - 'null' description: >- The mention_class before the correction. Only present for recommendation-class corrections. new_mention_class: type: string description: >- The mention_class requested. Only present for recommendation-class corrections. rows_affected: type: integer description: Rows updated by an applied correction. reason: type: string description: The reason code you supplied, echoed back. message: type: string description: Human-readable explanation of the outcome. recommendation: allOf: - $ref: '#/components/schemas/Recommendation' - description: >- The recommendation after the correction. Only present for recommendation-class corrections that resolved a row. required: - item_id - item_kind - status Recommendation: type: object properties: id: type: string description: Public recommendation id in the form "com_{n}". recommendation_id: type: integer description: >- Raw integer id of the recommendation row. Same number as in the "com_{n}" public id. mention_class: type: string description: >- Commercial mention classification. Values: ad_read (a paid sponsorship read), endorsement (an unpaid personal recommendation), mention (a neutral commercial mention). entity: $ref: '#/components/schemas/EntityRef' media: type: object properties: video_id: type: string description: YouTube video id (11 characters). title: type: - string - 'null' description: Video title. published_at: type: - string - 'null' description: Video publish timestamp. channel_id: type: - string - 'null' description: YouTube channel id of the source channel. source_channel: type: - object - 'null' properties: id: type: string description: Public entity id ("ent_{n}") of the source channel. name: type: - string - 'null' description: Source channel name. required: - id - name description: >- The channel entity that published the video. Null when the video has not been linked to a channel entity. required: - video_id - title - published_at - channel_id - source_channel start_timestamp: type: string deprecated: true description: >- DEPRECATED: prefer the numeric sibling field. This "MM:SS" (or "HH:MM:SS") string remains until a dated, changelog-announced removal (see /requests#versioning-and-deprecation). Use start_seconds. end_timestamp: type: string deprecated: true description: >- DEPRECATED: prefer the numeric sibling field. This "MM:SS" (or "HH:MM:SS") string remains until a dated, changelog-announced removal (see /requests#versioning-and-deprecation). Use end_seconds. start_seconds: type: - integer - 'null' description: >- Start position in the video in integer SECONDS, parsed from start_timestamp. Prefer this over the deprecated string field. 0 means "full episode / no specific moment" (the string sentinel "00:00"). Null when the string timestamp is null or unparseable. end_seconds: type: - integer - 'null' description: >- End position in the video in integer SECONDS, parsed from end_timestamp. 0 means "full episode / no specific moment" (the string sentinel "00:00"). Null when the string timestamp is null or unparseable. verbatim_quote: type: - string - 'null' description: >- Verbatim quote from the transcript. Null when no quote was extracted. promo_code: type: - string - 'null' description: Promo code read out in the mention. Null unless one was detected. offer: type: - string - 'null' description: >- Offer text, e.g. "20% off your first order". Null unless one was detected. sentiment: type: - number - 'null' deprecated: true description: >- DEPRECATED: use sentiment_score, which carries the same number. Removal will be announced in the changelog. Raw NUMERIC sentiment score between -1 and 1. Null when not computed. sentiment_score: type: - number - 'null' description: >- Raw sentiment score between -1 and 1, same semantics as sentiment_score on mention rows. Null when not computed. confidence: type: number description: >- Classifier confidence between 0 and 1. Rows below the min_confidence filter (default 0.7) are excluded from list responses. speaker_role: type: string description: Role of the speaker delivering the mention, e.g. "host" or "guest". conflict_status: type: - string - 'null' description: >- Set when community feedback disputes the classification (e.g. "disputed"). Null when undisputed. Disputed rows are excluded unless include_disputed=true. resolution: type: - string - 'null' description: >- How a disputed classification was resolved. Null until a dispute has been resolved. required: - id - recommendation_id - mention_class - entity - media - start_timestamp - end_timestamp - start_seconds - end_seconds - verbatim_quote - promo_code - offer - sentiment - sentiment_score - confidence - speaker_role - conflict_status - resolution EntityRef: type: object properties: id: type: string description: Public entity id in the form "ent_{n}". name: type: string description: Canonical entity name. type: type: string description: >- Entity type. Values: person (an individual), organization (a company or institution; legacy rows may read company or brand), product (a product or service), topic (a subject or theme), channel (a media source such as a YouTube channel), unknown (type was never classified). required: - id - name - type securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: arc_sk_* apiKeyAuth: type: apiKey in: header name: x-api-key ````