openapi: 3.2.0
info:
  title: Arcmira Mentions API
  description: 'Search YouTube transcripts for timestamped passages. Find mentions of people, organizations, products and topics; research channel sponsors and recommendations; retrieve creator captions or Premium transcripts with speaker identification; and monitor entities for new mentions. Official API guides: https://arcmira.com/docs. Explicit Premium retrieval can purchase within the account plan and budget.'
  version: 1.0.0
  contact:
    name: Arcmira
    url: https://arcmira.com
servers:
- url: https://api.arcmira.com
tags:
- name: Mentions
paths:
  /v1/mentions:
    get:
      tags:
      - Mentions
      operationId: list_mentions
      summary: Search mentions across media
      description: Cursor-paginated mentions filtered by entity (entity_id is required; resolve a name first with GET /v1/entities/resolve, or the call answers 400 id_required naming the parameter), channel (channel_id), text query, sentiment, appearance flag, and publication window [after, before). The signed continuation binds the route, filters, caller and visibility; invalid or old cursors return invalid_cursor. A first-page ID fence excludes later insertions, including old-date backfills. Edits and deletions to existing rows remain live. Positions are start_seconds and end_seconds (integer seconds; 0 means full episode). 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 a Pro+ plan.
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        required: false
        name: limit
        in: query
      - schema:
          type: string
          description: Signed continuation from next_cursor. Bound to this route, normalized query, caller and visibility; invalid or old tokens return invalid_cursor.
        required: false
        description: Signed continuation from next_cursor. Bound to this route, normalized query, caller and visibility; invalid or old tokens return invalid_cursor.
        name: cursor
        in: query
      - schema:
          type: string
          minLength: 1
          description: 'The entity, as an id like ent_14. Required. Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve.'
        required: true
        description: 'The entity, as an id like ent_14. Required. Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve.'
        name: entity_id
        in: query
      - schema:
          type: string
          description: 'Only media from this YouTube channel id (UC plus 22 characters). Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve.'
        required: false
        description: 'Only media from this YouTube channel id (UC plus 22 characters). Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve.'
        name: channel_id
        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
          description: 'Only media published at or after this instant. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive.'
        required: false
        description: 'Only media published at or after this instant. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive.'
        name: after
        in: query
      - schema:
          type: string
          description: 'Only media published before this instant, so before=2026-09-02 includes all of 2026-09-01. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive.'
        required: false
        description: 'Only media published before this instant, so before=2026-09-02 includes all of 2026-09-01. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive.'
        name: before
        in: query
      - schema:
          type: string
          enum:
          - full
        required: false
        name: details
        in: query
      - schema:
          type: string
          enum:
          - mcp-tool
          description: The surface making this call. The Arcmira MCP server sends mcp-tool so every unlock link in a gate attributes to the directory install. Omit from your own client.
        required: false
        description: The surface making this call. The Arcmira MCP server sends mcp-tool so every unlock link in a gate attributes to the directory install. Omit from your own client.
        name: src
        in: query
      responses:
        '200':
          description: Success
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-Arcmira-Version:
              $ref: '#/components/headers/X-Arcmira-Version'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MentionListResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '402':
          $ref: '#/components/responses/QuotaExceeded'
        '403':
          $ref: '#/components/responses/PermissionError'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /v1/mentions/counts:
    get:
      tags:
      - Mentions
      operationId: count_mentions
      summary: Ranked catalog counts of who a set of channels mention
      description: A small ranked table of entity and channel counts, all-time unless after is set. Pass channel_ids for what shows talk about and entity_types to match the question (topic for subjects, person for guests, organization,product for brands). Pass video_ids with one id from GET /v1/channels/{channel_id}/videos for what a single episode mentions. Two or more channel_ids also return shared, the entities on more than one of them ranked by the smallest per-channel count, which is true overlap. An after later than the plan's freshness gate is refused with freshness_requires_paid rather than widened. Bills one row per table row returned. Every gate is a typed error whose error.unlock.url names the plan that lifts it; pass src=mcp-tool only from the Arcmira MCP server.
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          description: Comma-separated YouTube channel ids (UC...), at most 8. Two or more also return shared, the entities on more than one of them.
        required: false
        description: Comma-separated YouTube channel ids (UC...), at most 8. Two or more also return shared, the entities on more than one of them.
        name: channel_ids
        in: query
      - schema:
          type: string
          description: Comma-separated entity ids (ent_{n}), at most 20. Counts only these entities.
        required: false
        description: Comma-separated entity ids (ent_{n}), at most 20. Counts only these entities.
        name: entity_ids
        in: query
      - schema:
          type: string
          description: Comma-separated 11-character YouTube video ids, at most 20. Counts only these episodes; take the ids from GET /v1/channels/{channel_id}/videos.
        required: false
        description: Comma-separated 11-character YouTube video ids, at most 20. Counts only these episodes; take the ids from GET /v1/channels/{channel_id}/videos.
        name: video_ids
        in: query
      - schema:
          type: string
          description: 'Comma-separated entity types to count: person, organization, product, topic, channel. Subjects are topic; guests are person; brands are organization,product. Omit and organizations dominate.'
        required: false
        description: 'Comma-separated entity types to count: person, organization, product, topic, channel. Subjects are topic; guests are person; brands are organization,product. Omit and organizations dominate.'
        name: entity_types
        in: query
      - schema:
          type: string
          enum:
          - mentions
          - appearances
          - both
          default: mentions
          description: mentions counts talk about an entity; appearances counts a person being present; both counts either. Default mentions.
        required: false
        description: mentions counts talk about an entity; appearances counts a person being present; both counts either. Default mentions.
        name: mode
        in: query
      - schema:
          type: string
          description: 'Only media published at or after this instant. Counts are all-time without it. An after later than your plan''s freshness gate is refused with freshness_requires_paid rather than widened. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive.'
        required: false
        description: 'Only media published at or after this instant. Counts are all-time without it. An after later than your plan''s freshness gate is refused with freshness_requires_paid rather than widened. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive.'
        name: after
        in: query
      - schema:
          type: string
          description: 'Only media published before this instant, so before=2026-09-02 includes all of 2026-09-01. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive.'
        required: false
        description: 'Only media published before this instant, so before=2026-09-02 includes all of 2026-09-01. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive.'
        name: before
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 40
          default: 20
          description: Rows in the ranked table, 1 to 40. Default 20.
        required: false
        description: Rows in the ranked table, 1 to 40. Default 20.
        name: limit
        in: query
      - schema:
          type: string
          enum:
          - mcp-tool
          description: The surface making this call. The Arcmira MCP server sends mcp-tool so every unlock link in a gate attributes to the directory install. Omit from your own client.
        required: false
        description: The surface making this call. The Arcmira MCP server sends mcp-tool so every unlock link in a gate attributes to the directory install. Omit from your own client.
        name: src
        in: query
      responses:
        '200':
          description: Success
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-Arcmira-Version:
              $ref: '#/components/headers/X-Arcmira-Version'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MentionCountsResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '402':
          $ref: '#/components/responses/QuotaExceeded'
        '403':
          $ref: '#/components/responses/PermissionError'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    RateLimited:
      description: Rate limit exceeded. Retry-After carries the wait.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Arcmira-Version:
          $ref: '#/components/headers/X-Arcmira-Version'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Arcmira-Version:
          $ref: '#/components/headers/X-Arcmira-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidRequest:
      description: Invalid request
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Arcmira-Version:
          $ref: '#/components/headers/X-Arcmira-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    QuotaExceeded:
      description: Quota exceeded
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Arcmira-Version:
          $ref: '#/components/headers/X-Arcmira-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Server error
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Arcmira-Version:
          $ref: '#/components/headers/X-Arcmira-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AuthenticationError:
      description: Authentication error
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Arcmira-Version:
          $ref: '#/components/headers/X-Arcmira-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PermissionError:
      description: Permission error
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Arcmira-Version:
          $ref: '#/components/headers/X-Arcmira-Version'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ErrorResource:
      oneOf:
      - type: object
        properties:
          kind:
            type: string
            enum:
            - media_rows
          beyond_row:
            type: integer
        required:
        - kind
        - beyond_row
      - type: object
        properties:
          kind:
            type: string
            enum:
            - fresh_media
          window_days:
            type: integer
          cutoff:
            type:
            - string
            - 'null'
        required:
        - kind
        - window_days
        - cutoff
      - type: object
        properties:
          kind:
            type: string
            enum:
            - sidebar_rows
          section:
            type: string
            enum:
            - topics
            - entities
          beyond_row:
            type: integer
        required:
        - kind
        - section
        - beyond_row
      - type: object
        properties:
          kind:
            type: string
            enum:
            - counts
        required:
        - kind
      - type: object
        properties:
          kind:
            type: string
            enum:
            - chart
        required:
        - kind
      - type: object
        properties:
          kind:
            type: string
            enum:
            - pagination
          param:
            type:
            - string
            - 'null'
            enum:
            - offset
            - cursor
            - null
        required:
        - kind
        - param
      - type: object
        properties:
          kind:
            type: string
            enum:
            - premium_transcript
        required:
        - kind
      - type: object
        properties:
          kind:
            type: string
            enum:
            - filter
          param:
            type: string
        required:
        - kind
        - param
      - type: object
        properties:
          kind:
            type: string
            enum:
            - commercial
          what:
            type: string
            enum:
            - sponsors
            - recommendations
            - mention_details
            - community_review
            - paid_split
        required:
        - kind
        - what
      - type: object
        properties:
          kind:
            type: string
            enum:
            - feature
          feature:
            type: string
            enum:
            - api
            - export
        required:
        - kind
        - feature
      - type: object
        properties:
          kind:
            type: string
            enum:
            - rows
          requested:
            type:
            - integer
            - 'null'
          remaining:
            type:
            - integer
            - 'null'
        required:
        - kind
        - requested
        - remaining
      - type: object
        properties:
          kind:
            type: string
            enum:
            - key
          scope:
            type:
            - string
            - 'null'
            enum:
            - read
            - monitors:write
            - trackers:write
            - recommendations:read
            - null
        required:
        - kind
        - scope
      - type: object
        properties:
          kind:
            type: string
            enum:
            - requests
        required:
        - kind
      description: The value the boundary withheld, not the reason it refused. kind is a closed vocabulary and the fields beside it are fixed per kind; see https://arcmira.com/docs/errors#resource-kinds.
    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).'
        slug:
          type:
          - string
          - 'null'
          description: URL slug, the site's canonical id for every type but channel. Null when never slugged.
        page:
          type:
          - string
          - 'null'
          description: The entity's page on arcmira.com, absolute. Link the name to it when you write the entity into an answer. Null for a type the site has no page for.
      required:
      - id
      - name
      - type
      - slug
      - page
    MentionCountsResponse:
      type: object
      properties:
        mode:
          type: string
          enum:
          - mentions
          - appearances
          - both
          description: The mode applied.
        window:
          $ref: '#/components/schemas/PublicationWindow'
        channel_ids:
          type: array
          items:
            type: string
          description: The channel ids counted.
        video_ids:
          type: array
          items:
            type: string
          description: The video ids the count was scoped to. Empty when it was not.
        rows:
          type: array
          items:
            type: object
            properties:
              entity_id:
                type: string
                description: Public entity id ("ent_{n}").
              name:
                type: string
              type:
                type: string
              page:
                type:
                - string
                - 'null'
                description: The entity's page on arcmira.com, absolute. Link the name to it when you write the entity into an answer. Null for a type the site has no page for.
              appearances_page:
                type:
                - string
                - 'null'
                description: For a person, the list of their appearances on arcmira.com (their page opens on it). Null for every other type.
              mentions_page:
                type:
                - string
                - 'null'
                description: 'For a person, the list of mentions of them on arcmira.com, page/mentions. Null for every other type: their page is the mentions list already.'
              slug:
                type:
                - string
                - 'null'
                description: URL slug. Null when never slugged.
              channel_id:
                type:
                - string
                - 'null'
              channel_name:
                type:
                - string
                - 'null'
              channel_page:
                type:
                - string
                - 'null'
                description: The channel's page on arcmira.com, absolute. Null when no channel is known.
              count:
                type: integer
                description: Episodes the entity came up in.
              occurrences:
                type: integer
                description: Times the entity came up across those episodes (mentions or appearances per mode).
              as_of:
                type:
                - string
                - 'null'
                description: Newest media in this count.
            required:
            - entity_id
            - name
            - type
            - page
            - appearances_page
            - mentions_page
            - slug
            - channel_id
            - channel_name
            - channel_page
            - count
            - occurrences
            - as_of
          description: One row per entity and channel, ranked by count.
        returned:
          type: integer
        has_more:
          type: boolean
          description: True when more entity and channel pairs exist past limit.
        shared:
          type: array
          items:
            type: object
            properties:
              entity_id:
                type: string
              name:
                type: string
              type:
                type: string
              page:
                type:
                - string
                - 'null'
                description: The entity's page on arcmira.com, absolute. Link the name to it when you write the entity into an answer. Null for a type the site has no page for.
              appearances_page:
                type:
                - string
                - 'null'
                description: For a person, their appearances list. Null otherwise.
              mentions_page:
                type:
                - string
                - 'null'
                description: For a person, the mentions of them. Null otherwise.
              slug:
                type:
                - string
                - 'null'
                description: URL slug. Null when never slugged.
              channel_count:
                type: integer
                description: How many of the requested channels carry this entity.
              by_channel:
                type: array
                items:
                  type: object
                  properties:
                    channel_id:
                      type:
                      - string
                      - 'null'
                      description: YouTube channel id.
                    channel_name:
                      type:
                      - string
                      - 'null'
                    channel_page:
                      type:
                      - string
                      - 'null'
                      description: The channel's page on arcmira.com, absolute. Null when no channel is known.
                    count:
                      type: integer
                      description: Episodes the entity came up in.
                    occurrences:
                      type: integer
                      description: Times the entity came up across those episodes (mentions or appearances per mode).
                    as_of:
                      type:
                      - string
                      - 'null'
                      description: Newest media in this count.
                  required:
                  - channel_id
                  - channel_name
                  - channel_page
                  - count
                  - occurrences
                  - as_of
            required:
            - entity_id
            - name
            - type
            - page
            - appearances_page
            - mentions_page
            - slug
            - channel_count
            - by_channel
          description: Entities on two or more of the requested channels, ranked by the smallest per-channel count. Empty for one channel.
        as_of:
          type:
          - string
          - 'null'
          description: Newest media across rows. Null when there are none.
        note:
          type: string
          description: One steering sentence for the agent reading this.
      required:
      - mode
      - window
      - channel_ids
      - video_ids
      - rows
      - returned
      - has_more
      - shared
      - as_of
      - note
      example:
        mode: mentions
        window:
          after: '2026-06-01T00:00:00Z'
          before: null
        channel_ids:
        - UC-DRzaGnL_vtBUpCFH5M0tg
        - UClWkDGXEzsh77GAhs90wpXw
        video_ids: []
        rows:
        - entity_id: ent_14
          name: Ramp
          type: organization
          page: https://arcmira.com/org/ramp
          appearances_page: null
          mentions_page: null
          slug: ramp
          channel_id: UC-DRzaGnL_vtBUpCFH5M0tg
          channel_name: TBPN
          channel_page: https://arcmira.com/yt/@TBPNLive
          count: 23
          as_of: '2026-08-28T17:00:00.000Z'
        - entity_id: ent_14
          name: Ramp
          type: organization
          page: https://arcmira.com/org/ramp
          appearances_page: null
          mentions_page: null
          slug: ramp
          channel_id: UClWkDGXEzsh77GAhs90wpXw
          channel_name: Moment of Truth
          channel_page: https://arcmira.com/yt/@MomentofTruthShow
          count: 3
          occurrences: 7
          as_of: '2026-08-21T16:00:00.000Z'
        returned: 2
        has_more: false
        shared:
        - entity_id: ent_14
          name: Ramp
          type: organization
          page: https://arcmira.com/org/ramp
          appearances_page: null
          mentions_page: null
          slug: ramp
          channel_count: 2
          by_channel:
          - channel_id: UC-DRzaGnL_vtBUpCFH5M0tg
            channel_name: TBPN
            channel_page: https://arcmira.com/yt/@TBPNLive
            count: 23
            as_of: '2026-08-28T17:00:00.000Z'
          - channel_id: UClWkDGXEzsh77GAhs90wpXw
            channel_name: Moment of Truth
            channel_page: https://arcmira.com/yt/@MomentofTruthShow
            count: 3
            occurrences: 7
            as_of: '2026-08-21T16:00:00.000Z'
        as_of: '2026-08-28T17:00:00.000Z'
        note: Catalog counts, all-time unless you passed a window. shared ranks true overlap by the smallest per-channel count. Use search_transcripts afterwards only for quotes.
    Entity:
      type: object
      properties:
        id:
          type: string
          description: Public entity id in the form "ent_{n}". Always the canonical entity id.
        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.
        slug:
          type:
          - string
          - 'null'
          description: URL slug, the site's canonical id for every type but channel. Null when never slugged.
        route:
          type:
          - string
          - 'null'
          description: Site-relative route of this entity's page on arcmira.com, e.g. "/org/ramp", "/person/jane-doe", "/yt/@TBPNLive". Null for a type the site has no page for.
        page:
          type:
          - string
          - 'null'
          description: The entity's page on arcmira.com, absolute. Link the name to it when you write the entity into an answer. Null for a type the site has no page for.
        appearances_page:
          type:
          - string
          - 'null'
          description: For a person, the list of their appearances on arcmira.com (their page opens on it). Null for every other type.
        mentions_page:
          type:
          - string
          - 'null'
          description: 'For a person, the list of mentions of them on arcmira.com, page/mentions. Null for every other type: their page is the mentions list already.'
      required:
      - id
      - canonical_id
      - name
      - type
      - platform
      - url
      - image_url
      - image_checked_at
      - owner_entity_id
      - is_canonical
      - merged_from_id
      - slug
      - route
      - page
      - appearances_page
      - mentions_page
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - invalid_request_error
              - authentication_error
              - permission_error
              - quota_exceeded
              - rate_limit_error
              - not_found
              - conflict_error
              - server_error
              description: 'The error class. It fixes the HTTP status: invalid_request_error 400, authentication_error 401, quota_exceeded 402, permission_error 403, not_found 404, conflict_error 409, rate_limit_error 429, server_error 500. Switch on it for retry and gate handling.'
            code:
              type: string
              description: 'The specific condition, stable and snake_case; doc_url anchors on it. x-arcmira-codes on this schema lists every code with its type, gate and meaning. The list is open: new codes may appear inside an existing type, so switch on type and gate first.'
            reason:
              type: string
              enum:
              - no_credential
              - invalid
              - revoked
              description: 'Only on invalid_api_key. no_credential: nothing was sent. invalid: a credential was sent and is unknown or malformed. revoked: the key exists and is no longer usable.'
            message:
              type: string
              description: One plain line. Names the fix or the unlock.
            param:
              type: string
              description: The query or body parameter the gate refused, when one did.
            gate:
              type: string
              enum:
              - rows
              - key
              - plan
              - freshness
              - exposure_law
              - rate
              - pagination
              description: Which boundary refused. Present on every gate error; switch on it without parsing the message.
            resource:
              $ref: '#/components/schemas/ErrorResource'
            unlock:
              type: object
              properties:
                tier:
                  type: string
                  description: The plan that lifts the gate.
                url:
                  type: string
                  description: Absolute upgrade or sign-up URL carrying its ?src= attribution. Use it verbatim.
                offer:
                  type: 'null'
                  description: Reserved for the agent-discount offer. Always null today.
                action:
                  type: object
                  properties:
                    kind:
                      type: string
                      description: What the call does. send_signup_code sends a verification code to an address for an account key.
                    method:
                      type: string
                      description: HTTP method to use.
                    url:
                      type: string
                      description: Absolute endpoint carrying its ?src= attribution. Call it verbatim.
                  required:
                  - kind
                  - method
                  - url
                  description: The request that lifts the gate with no human, present when the caller can fix this itself. A key gate carries the signup send here; a plan or quota gate has no action and its url is a page a person opens.
              required:
              - tier
              - url
              - offer
              description: How to lift the gate. Present when the gate has an unlock.
            retry_after_seconds:
              type: integer
              description: Present on rate gates. Mirrors the Retry-After header.
            details:
              type: object
              properties:
                quote:
                  $ref: '#/components/schemas/RefusedQuote'
                existing_id:
                  type: string
                  description: On tracker_already_exists, the existing tracker id. Reuse it instead of creating another tracker.
                limit:
                  type: integer
                  description: On tracker_limit, the trackers the plan holds.
                count:
                  type: integer
                  description: On tracker_limit, the trackers the account holds now.
              description: Machine data the refusal carries for you to act on. Present only on the codes that name a field here.
            doc_url:
              type: string
            request_id:
              type: string
          required:
          - type
          - code
          - message
          - doc_url
          - request_id
      required:
      - error
      x-arcmira-codes:
      - code: alert_not_found
        type: not_found
        description: A referenced alert row does not exist or belongs to another account.
      - code: api_not_enabled
        type: permission_error
        gate: plan
        description: The plan does not include API access. unlock.url names the plan that does.
      - code: appearances_person_only
        type: invalid_request_error
        description: Appearance filtering applies to person entities only.
      - code: channel_not_found
        type: not_found
        description: No channel matches the id or slug.
      - code: email_verification_required
        type: permission_error
        description: Verify the account email before adding recipients.
      - code: entity_not_found
        type: not_found
        description: No entity matches the id, slug, or name.
      - code: feature_not_available
        type: permission_error
        gate: plan
        description: The plan does not include this feature. unlock.url names the plan that does.
      - code: feedback_not_found
        type: not_found
        description: No feedback submission with this id for this account.
      - code: filter_requires_paid
        type: permission_error
        gate: plan
        description: The parameter in param needs a paid plan; omit it for the free answer.
      - code: forbidden
        type: permission_error
        description: The caller may not perform this operation on this resource.
      - code: freshness_requires_paid
        type: permission_error
        gate: freshness
        description: The date window is newer than the plan serves; move it before the cutoff or upgrade.
      - code: id_required
        type: invalid_request_error
        description: A filter in param received a name where it takes an id (ent_{n} or UC...). Resolve the name first with GET /v1/entities/resolve and pass best.id or best.youtube_channel_id.
      - code: idempotency_conflict
        type: conflict_error
        description: The Idempotency-Key was sent before with a different request body. Send a new key for a new request.
      - code: idempotency_result_expired
        type: conflict_error
        description: The original one-time signing secret is no longer valid. Use a new request key for a new rotation.
      - code: insufficient_scope
        type: permission_error
        gate: key
        description: The key lacks the scope this route needs.
      - code: invalid_api_key
        type: authentication_error
        gate: key
        description: No usable credential. reason says whether none was sent, it is unknown, or it was revoked.
      - code: invalid_body
        type: invalid_request_error
        description: The JSON body failed validation; message names the field.
      - code: invalid_cursor
        type: invalid_request_error
        description: The continuation is invalid, expired, or belongs to another query. Restart without cursor.
      - code: invalid_email_recipients
        type: invalid_request_error
        description: Email recipients failed validation.
      - code: invalid_feedback_request
        type: invalid_request_error
        description: The feedback query or corrections do not fit the feedback type.
      - code: invalid_idempotency_key
        type: invalid_request_error
        description: Idempotency-Key must be 1 to 255 printable ASCII characters (0x21 to 0x7E). param is Idempotency-Key.
      - code: invalid_query
        type: invalid_request_error
        description: A query parameter failed validation; message names it.
      - code: invalid_slack_integration
        type: invalid_request_error
        description: Choose an active Slack integration owned by the account.
      - code: invalid_video_id
        type: invalid_request_error
        description: The video_id path segment is not an 11-character YouTube id.
      - code: job_requires_account
        type: authentication_error
        gate: key
        description: Transcription jobs belong to an account; sign up for a key.
      - code: monitor_creation_unavailable
        type: server_error
        description: Monitor creation is temporarily unavailable. Retry the same request with the same key.
      - code: monitor_creation_unconfirmed
        type: server_error
        description: Monitor creation could not be confirmed. Retry the same request with the same key.
      - code: monitor_not_found
        type: not_found
        description: No monitor with this id on the account.
      - code: not_found
        type: not_found
        description: No route or resource at this path.
      - code: owner_only
        type: permission_error
        description: Only the team owner may change or test a team monitor's webhook, rotate its secret, or delete it.
      - code: owner_plan_required
        type: permission_error
        description: A team monitor follows the team owner's plan, which does not include this. The owner can upgrade; a member's own plan does not apply.
      - code: pagination_gated
        type: permission_error
        gate: pagination
        description: Rows past the free window need a paid plan.
      - code: paid_plan_required
        type: permission_error
        description: The operation needs a paid plan. unlock.url names the plan that does.
      - code: premium_transcript_requested
        type: permission_error
        gate: exposure_law
        description: Premium transcript text needs a plan with Premium transcripts.
      - code: quota_exceeded
        type: quota_exceeded
        gate: rows
        description: The row pool is spent. unlock.url upgrades or raises the limit.
      - code: rate_limited
        type: rate_limit_error
        gate: rate
        description: Too many requests in the window. Retry-After carries the wait.
      - code: recipient_upgrade_required
        type: permission_error
        description: The requested email recipient count exceeds the plan allowance.
      - code: recommendations_not_enabled
        type: permission_error
        gate: plan
        description: Commercial data needs a Pro+ plan.
      - code: resource_conflict
        type: conflict_error
        description: The operation conflicts with existing resource state.
      - code: scope_too_broad
        type: invalid_request_error
        description: The requested exact video scope exceeds the search filename cap; narrow by channel or date.
      - code: search_unavailable
        type: server_error
        description: Transcript search is unavailable (HTTP 503). Retry-After carries the wait.
      - code: server_error
        type: server_error
        description: Unexpected failure. Retry with backoff and quote request_id if it persists.
      - code: signup_code_invalid
        type: invalid_request_error
        description: The signup code is wrong, expired, or spent; message names the attempts left.
      - code: signup_send_limited
        type: rate_limit_error
        description: Verification code sends hit a per-address, per-IP, or per-client cap. Retry-After carries the wait.
      - code: spend_limit_exceeded
        type: quota_exceeded
        description: The purchase would take on-demand spending past the account or seat spend limit this period. Nothing was charged. Raise the limit or wait for the next period, then send a new intent.
      - code: team_not_found
        type: not_found
        description: No team with this id that the caller belongs to.
      - code: tracker_already_exists
        type: conflict_error
        description: The account already tracks this entity. error.details.existing_id identifies the existing tracker.
      - code: tracker_limit
        type: permission_error
        description: The plan's tracker limit is reached. error.details carries limit and count.
      - code: tracker_not_found
        type: not_found
        description: No tracker with this id on the account.
      - code: transcript_fetching
        type: server_error
        description: The caption track is being fetched now (HTTP 503). Retry-After carries the wait; nothing was charged.
      - code: transcript_requires_account
        type: authentication_error
        gate: key
        description: Full transcripts need an account key; unlock.action sends a signup code.
      - code: transcript_unavailable
        type: not_found
        description: The video has no transcript in the requested lane or language; languages lists what exists.
      - code: unknown_entity
        type: invalid_request_error
        description: An explicit entity_ids value does not resolve to a searchable entity.
      - code: webhook_not_configured
        type: conflict_error
        description: The monitor has no webhook to rotate a secret for. Set webhook_url first.
    RecommendationEnrichmentItem:
      type: object
      properties:
        id:
          type: string
          description: Public recommendation id in the form "com_{n}".
        class:
          type: string
          enum:
          - sponsored
          - organic
          - mention
          description: 'Commercial class. Values: sponsored (an ad-style promotion heard at that moment: a paid sponsor read, promo code, affiliate plug, thanks for supplied goods or venue, or a show promoting its own product as an ad), organic (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_seconds:
          type:
          - integer
          - 'null'
          description: Start position in the video in integer seconds. 0 means "full episode / no specific moment". Null when the analyzer could not place it in time.
        end_seconds:
          type:
          - integer
          - 'null'
          description: End position in the video in integer seconds. 0 means "full episode / no specific moment". Null when the analyzer could not place it in time.
      required:
      - id
      - class
      - verbatim_quote
      - promo_code
      - offer
      - confidence
      - start_seconds
      - end_seconds
    TranscriptQuote:
      type: object
      properties:
        quarters:
          type: integer
          description: Number of 15-minute blocks in the video, ceiling'd, minimum 1.
        rows:
          type: integer
          description: 'Total unlock cost in rows: 75 rows per 15-minute block.'
      required:
      - quarters
      - rows
    RefusedQuote:
      allOf:
      - $ref: '#/components/schemas/TranscriptQuote'
      - type: object
        properties:
          charge:
            type: object
            properties:
              unit:
                type: string
                enum:
                - rows
                - credits
              amount:
                type: number
              from:
                type: string
                enum:
                - included
                - on_demand
                - mixed
                description: Where the charge would come from at the current balance.
            required:
            - unit
            - amount
            - from
            description: What the purchase would charge at the current balance. Absent when no current price could be read.
          max_on_demand_cents:
            type: integer
            description: The on-demand money, in whole cents, this purchase needs beyond included credits at the current balance.
      description: 'The refused price, on a priced refusal: quota_exceeded, spend_limit_exceeded and paid_plan_required.'
    PublicationWindow:
      type: object
      properties:
        after:
          type:
          - string
          - 'null'
          description: Inclusive start as an ISO instant. Null when the window has no start.
        before:
          type:
          - string
          - 'null'
          description: Exclusive end as an ISO instant. Null when the window has no end. Earlier than the before you sent when your plan's freshness gate cut the window.
      required:
      - after
      - before
      description: The publication window the answer covers, [after, before) in UTC, normalized from after and before.
    Mention:
      type: object
      properties:
        id:
          type: string
          description: Public mention id in the form "men_{n}".
        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. 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:
          - video_id
          - title
          - url
          - published_at
          - channel_id
          - view_count
          - source_channel
        start_seconds:
          type:
          - integer
          - 'null'
          description: Start position in the video in integer seconds. 0 means "full episode / no specific moment". Null when the analyzer could not place it in time.
        end_seconds:
          type:
          - integer
          - 'null'
          description: End position in the video in integer seconds. 0 means "full episode / no specific moment". Null when the analyzer could not place it in time.
        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 (sponsored and organic) for the same entity in the same video.
          required:
          - items
          description: Only present when the request used details=full (requires a Pro+ plan).
      required:
      - id
      - entity
      - media
      - start_seconds
      - end_seconds
      - is_appearance
      - description
      - confidence
      - sentiment_score
      - sentiment
      - referenced_url
      - referenced_platform
      - extracted_content
    MentionListResponse:
      type: object
      properties:
        mentions:
          type: array
          items:
            $ref: '#/components/schemas/Mention'
          description: Newest first.
        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.
        window:
          $ref: '#/components/schemas/PublicationWindow'
        note:
          type: string
          description: 'Present on a free preview page: where the list stops and the plan that lifts it. Say so rather than calling this every mention.'
        unlock:
          type: object
          properties:
            tier:
              type: string
              description: The plan that lifts the preview.
            url:
              type: string
              description: Where to start that plan.
          required:
          - tier
          - url
          description: Present with note on a free preview page.
      required:
      - mentions
      - has_more
      - next_cursor
      - entity
      - window
  headers:
    X-Arcmira-Version:
      description: The API version that answered. Always v1.
      schema:
        type: string
        enum:
        - v1
    RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    RateLimit-Reset:
      description: Unix time in seconds when the current window ends.
      schema:
        type: integer
    RateLimit-Limit:
      description: Requests allowed per 60-second window for this credential, as GET /v1/me rate_limit reports.
      schema:
        type: integer
    Retry-After:
      description: Seconds to wait before retrying. error.retry_after_seconds carries the same value on an error.
      schema:
        type: integer
    X-Request-Id:
      description: The request id, echoed from an X-Request-Id request header or minted as req_<uuid>. error.request_id carries the same value. Quote it when reporting a problem.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: arc_sk_*
externalDocs:
  description: Official Arcmira API documentation
  url: https://arcmira.com/docs