> ## 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. # List mentions for an entity > Cursor-paginated mentions for one entity, newest media first. Read timestamps from start_seconds / end_seconds (integer seconds; 0 means full episode); the MM:SS (or HH:MM:SS) string fields are deprecated. is_appearance filtering applies to person entities only; passing is_appearance=true for any other type returns a 400 (appearances_person_only). details=full attaches per-mention commercial recommendations and requires the recommendations:read scope on a plan with Recommendations API access. ## OpenAPI ````yaml /openapi/arcmira-v1.json get /v1/entities/{id}/mentions 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/entities/{id}/mentions: get: tags: - Mentions summary: List mentions for an entity description: >- Cursor-paginated mentions for one entity, newest media first. Read timestamps from start_seconds / end_seconds (integer seconds; 0 means full episode); the MM:SS (or HH:MM:SS) string fields are deprecated. is_appearance filtering applies to person entities only; passing is_appearance=true for any other type returns a 400 (appearances_person_only). details=full attaches per-mention commercial recommendations and requires the recommendations:read scope on a plan with Recommendations API access. operationId: list_entity_mentions parameters: - schema: type: integer minimum: 1 maximum: 100 default: 20 required: false name: limit in: query - schema: type: string required: false name: cursor in: query - schema: type: string required: false name: channel_id in: query - schema: type: string required: false name: channel_name in: query - schema: type: string required: false name: q in: query - schema: type: string enum: - positive - neutral - negative required: false name: sentiment in: query - schema: type: boolean required: false name: is_appearance in: query - schema: type: string required: false name: date_from in: query - schema: type: string required: false name: date_to in: query - schema: type: string enum: - full required: false name: details in: query responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/MentionListResponse' '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: MentionListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/Mention' has_more: type: boolean description: True when more rows exist past this page. next_cursor: type: - string - 'null' description: Opaque cursor for the next page. Null on the last page. entity: allOf: - $ref: '#/components/schemas/Entity' - description: The resolved entity the mentions belong to. required: - data - has_more - next_cursor - entity Mention: type: object properties: id: type: string description: Public mention id in the form "men_{n}". appearance_id: type: integer description: >- Raw integer id of the underlying appearance row. Same number as in the "men_{n}" public id. entity: $ref: '#/components/schemas/EntityRef' media: type: object properties: id: type: integer description: Raw integer media row id. video_id: type: string description: YouTube video id (11 characters). title: type: - string - 'null' description: Video title. Null when the video was indexed without metadata. url: type: - string - 'null' description: Video URL. Null when unknown. published_at: type: - string - 'null' description: Video publish timestamp. Null when unknown. channel_id: type: - string - 'null' description: YouTube channel id of the source channel. Null when unknown. view_count: type: - integer - 'null' description: Video view count at index time. Null when never fetched. 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. url: type: - string - 'null' description: Source channel URL. Null when unknown. required: - id - name - url description: >- The channel entity that published the video. Null when the video has not been linked to a channel entity. required: - id - video_id - title - url - published_at - channel_id - view_count - source_channel start_timestamp: type: - string - 'null' 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. Null when the analyzer could not locate the mention in time. end_timestamp: type: - string - 'null' 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. Null when unknown. 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. is_appearance: type: boolean description: >- True when the person physically appears/speaks in the media (person entities only). Always false for organization, product, topic, and channel entities. Filtering with is_appearance=true on a non-person entity returns a 400 (appearances_person_only). description: type: - string - 'null' description: >- One-sentence description of the mention context. Null when not generated. confidence: type: - number - 'null' description: >- Analyzer confidence between 0 and 1. Null for legacy rows analyzed before confidence scoring. sentiment_score: type: - number - 'null' description: >- Raw sentiment score between -1 and 1. Null when sentiment was not computed for this mention. sentiment: type: string enum: - positive - neutral - negative description: >- Derived sentiment label from sentiment_score. Values: positive (score above 0.2), negative (score below -0.2), neutral (score between -0.2 and 0.2 inclusive, or no score computed). referenced_url: type: - string - 'null' description: URL referenced in the mention. Null unless one was extracted. referenced_platform: type: - string - 'null' description: >- Platform referenced in the mention, e.g. "twitter". Null unless one was extracted. extracted_content: type: - string - 'null' description: >- Verbatim content extracted for the mention. Null unless extraction ran. recommendations: type: object properties: items: type: array items: $ref: '#/components/schemas/RecommendationEnrichmentItem' description: >- Commercial mentions (ad reads, endorsements) for the same entity in the same video. required: - items description: >- Only present when the request used details=full (requires the recommendations:read scope on a plan with Recommendations API access). required: - id - appearance_id - entity - media - start_timestamp - end_timestamp - start_seconds - end_seconds - is_appearance - description - confidence - sentiment_score - sentiment - referenced_url - referenced_platform - extracted_content Entity: type: object properties: id: type: string description: >- Public entity id in the form "ent_{n}". Always the canonical entity id. numeric_id: type: integer description: >- Raw integer database id of the canonical entity. Prefer the public "ent_{n}" id in requests. canonical_id: type: string description: Public id of the canonical entity. Identical to id. 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). platform: type: - string - 'null' description: >- Source platform for channel entities, e.g. "youtube". Null unless the entity is platform-bound. url: type: - string - 'null' description: Canonical external URL for the entity. Null when none is known. image_url: type: - string - 'null' description: Entity image URL. Null until an image has been resolved. image_checked_at: type: - string - 'null' description: >- Timestamp of the last image resolution attempt. Null until the image pipeline has visited this entity. appearance_count: type: integer default: 0 description: >- Number of indexed appearance/mention rows for this entity. 0 when never counted. owner_entity_id: type: - string - 'null' description: >- Public id ("ent_{n}") of the owning entity, e.g. the organization behind a product. Null unless an ownership link exists. is_canonical: type: boolean description: >- True when the id you supplied is the canonical entity. False when your id was merged into this canonical record. merged_from_id: type: - string - 'null' description: >- Public id you supplied when it differs from the canonical entity, i.e. your id was merged into this record. Null unless a merge redirect happened. route: type: string description: >- Site-relative route for this entity on arcmira.com, e.g. "/people/jane-doe". required: - id - numeric_id - canonical_id - name - type - platform - url - image_url - image_checked_at - owner_entity_id - is_canonical - merged_from_id - route 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 RecommendationEnrichmentItem: type: object properties: id: type: string description: Public recommendation id in the form "com_{n}". 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). 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". Null unless one was detected. confidence: type: number description: Classifier confidence between 0 and 1. 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. 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. required: - id - mention_class - verbatim_quote - promo_code - offer - confidence - start_timestamp - end_timestamp - start_seconds - end_seconds securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: arc_sk_* apiKeyAuth: type: apiKey in: header name: x-api-key ````