openapi: 3.2.0 info: title: Arcmira Trackers 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: Trackers paths: /v1/trackers: get: tags: - Trackers operationId: list_trackers summary: List trackers description: All trackers for the account, newest first, with per-channel delivery counts for the current billing period. Single page, no pagination. security: - bearerAuth: [] 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/TrackerListResponse' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/AuthenticationError' '403': $ref: '#/components/responses/PermissionError' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' post: tags: - Trackers operationId: create_tracker summary: Create tracker description: Creates a standalone tracker watching one exact name and type, matched case-insensitively against entities in newly analyzed media, so a tracker can exist before the entity is indexed. To follow an entity you already have an id for, use POST /v1/monitors/{id}/entities. A channel is followed by its YouTube channel id (UC plus 22 characters); a channel name answers 400 id_required. Attach it to a monitor afterwards via POST /v1/monitors/{id}/trackers. Creating a duplicate (same entity name + type) returns 409 tracker_already_exists with the existing tracker id in error.details.existing_id. security: - bearerAuth: [] parameters: - schema: type: string required: false name: Idempotency-Key in: header example: 8b2f6c3e-4d1a-4e7b-9c05-2f6a1b7d3e90 description: 'One key per intent, 1 to 255 printable ASCII characters (0x21 to 0x7E); anything else is 400 invalid_idempotency_key. Keys are scoped to the account, credential and resource family. The same key and normalized method, path and body returns the committed response with Idempotency-Replayed: true. A changed intent within the same family returns 409 idempotency_conflict. Monitor and tracker families have independent namespaces. Secret recovery is limited as described by the operation.' requestBody: content: application/json: schema: type: object properties: entity_name: type: string minLength: 1 description: 'The exact name to watch, matched case-insensitively against analyzed media, so a tracker can exist before the entity is indexed. For a channel, the YouTube channel id (UC plus 22 characters), never a name: a channel name answers 400 id_required naming GET /v1/entities/resolve?q=...&type=channel and best.youtube_channel_id. Required on create. Creating a duplicate (same name, compared case-insensitively, and type) returns 409 tracker_already_exists with the existing tracker id in error.details.existing_id.' entity_type: type: string enum: - person - organization - org - product - topic - channel description: Entity type of the tracked entity. Required on create. org is accepted for organization, and the tracker answers organization. display_name: type: string description: Optional label shown in alerts and the dashboard. notify_email: type: boolean description: Per-tracker email delivery. Default true. notify_webhook: type: boolean description: Per-tracker webhook delivery override. Paid plans only. notify_slack: type: boolean description: Per-tracker Slack delivery override. Paid plans only. webhook_url: type: string description: Per-tracker webhook destination override (http/https). slack_channel_id: type: string description: Per-tracker Slack channel override. slack_integration_id: type: string description: Per-tracker Slack integration override. person_match_mode: type: string enum: - mentions - appearances - both description: Person trackers only. Mentions (default) matches others talking about the person; appearances matches the person present as a speaker, host or guest; both accepts either. Non-person trackers reject this field. PATCH changes future and pending delivery eligibility, without backfill. filters: type: object additionalProperties: {} description: Stored filter object. personMatchMode is also accepted here for person trackers. Other filter keys are retained; do not assume they change matching. required: - entity_name - entity_type additionalProperties: false 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' Idempotency-Replayed: $ref: '#/components/headers/Idempotency-Replayed' content: application/json: schema: $ref: '#/components/schemas/TrackerMutationResponse' '201': description: Tracker created 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' Idempotency-Replayed: $ref: '#/components/headers/Idempotency-Replayed' content: application/json: schema: $ref: '#/components/schemas/TrackerMutationResponse' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/AuthenticationError' '403': $ref: '#/components/responses/PermissionError' '404': $ref: '#/components/responses/NotFound' '409': description: Conflict. idempotency_conflict means the Idempotency-Key was finalized with a different request intent. The route also answers 409 for a duplicate or a failed precondition, named in its description. 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' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' /v1/trackers/{id}: patch: tags: - Trackers operationId: update_tracker summary: Update tracker description: 'Partial update: send only the fields to change. The tracked entity itself (entity_name/entity_type) is immutable; delete and recreate to watch a different entity.' security: - bearerAuth: [] parameters: - schema: type: string description: Tracker id, trk_ form. required: true description: Tracker id, trk_ form. name: id in: path - schema: type: string required: false name: Idempotency-Key in: header example: 8b2f6c3e-4d1a-4e7b-9c05-2f6a1b7d3e90 description: 'One key per intent, 1 to 255 printable ASCII characters (0x21 to 0x7E); anything else is 400 invalid_idempotency_key. Keys are scoped to the account, credential and resource family. The same key and normalized method, path and body returns the committed response with Idempotency-Replayed: true. A changed intent within the same family returns 409 idempotency_conflict. Monitor and tracker families have independent namespaces. Secret recovery is limited as described by the operation.' requestBody: content: application/json: schema: type: object properties: display_name: type: string description: Optional label shown in alerts and the dashboard. notify_email: type: boolean description: Per-tracker email delivery. Default true. notify_webhook: type: boolean description: Per-tracker webhook delivery override. Paid plans only. notify_slack: type: boolean description: Per-tracker Slack delivery override. Paid plans only. webhook_url: type: string description: Per-tracker webhook destination override (http/https). slack_channel_id: type: string description: Per-tracker Slack channel override. slack_integration_id: type: string description: Per-tracker Slack integration override. person_match_mode: type: string enum: - mentions - appearances - both description: Person trackers only. Mentions (default) matches others talking about the person; appearances matches the person present as a speaker, host or guest; both accepts either. Non-person trackers reject this field. PATCH changes future and pending delivery eligibility, without backfill. filters: type: object additionalProperties: {} description: Stored filter object. personMatchMode is also accepted here for person trackers. Other filter keys are retained; do not assume they change matching. paused: type: boolean description: Pause or resume the tracker. Paused trackers stop producing alerts; there is no backfill for the paused window. additionalProperties: false 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' Idempotency-Replayed: $ref: '#/components/headers/Idempotency-Replayed' content: application/json: schema: $ref: '#/components/schemas/TrackerMutationResponse' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/AuthenticationError' '403': $ref: '#/components/responses/PermissionError' '404': $ref: '#/components/responses/NotFound' '409': description: Conflict. idempotency_conflict means the Idempotency-Key was finalized with a different request intent. 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' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' delete: tags: - Trackers operationId: delete_tracker summary: Delete tracker description: Deletes the tracker. Cannot be undone. security: - bearerAuth: [] parameters: - schema: type: string description: Tracker id, trk_ form. required: true description: Tracker id, trk_ form. name: id in: path - schema: type: string required: false name: Idempotency-Key in: header example: 8b2f6c3e-4d1a-4e7b-9c05-2f6a1b7d3e90 description: 'One key per intent, 1 to 255 printable ASCII characters (0x21 to 0x7E); anything else is 400 invalid_idempotency_key. Keys are scoped to the account, credential and resource family. The same key and normalized method, path and body returns the committed response with Idempotency-Replayed: true. A changed intent within the same family returns 409 idempotency_conflict. Monitor and tracker families have independent namespaces. Secret recovery is limited as described by the operation.' 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' Idempotency-Replayed: $ref: '#/components/headers/Idempotency-Replayed' content: application/json: schema: $ref: '#/components/schemas/MessageResponse' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/AuthenticationError' '403': $ref: '#/components/responses/PermissionError' '404': $ref: '#/components/responses/NotFound' '409': description: Conflict. idempotency_conflict means the Idempotency-Key was finalized with a different request intent. 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' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' /v1/trackers/{id}/alerts: get: tags: - Trackers operationId: list_tracker_alerts summary: List recent tracker alerts description: The newest limit alert deliveries for the tracker (default 25, at most 100), as a single page. has_more is true when older alerts exist past limit; this endpoint does not paginate, so next_cursor is always null and a larger limit reads further. entity_id ("ent_{n}") and mention_id ("men_{n}") are the ids GET /v1/entities/{id} and GET /v1/mentions use, and video_id is the YouTube video id that GET /v1/transcripts/{video_id} reads. Dispute a fired alert via POST /v1/feedback with type monitor_alert. security: - bearerAuth: [] parameters: - schema: type: string description: Tracker id, trk_ form. required: true description: Tracker id, trk_ form. name: id in: path - schema: type: integer minimum: 1 maximum: 100 description: Alerts to return, newest first, 1 to 100. Default 25. required: false description: Alerts to return, newest first, 1 to 100. Default 25. name: limit 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/AlertListResponse' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/AuthenticationError' '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' 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. AlertListResponse: type: object properties: alerts: type: array items: $ref: '#/components/schemas/Alert' description: Newest alerts first. has_more: type: boolean description: 'True when older alerts exist past limit. The endpoint does not paginate: raise limit, up to 100, to read them.' next_cursor: type: 'null' description: 'Always null: this endpoint does not paginate.' required: - alerts - has_more - next_cursor MessageResponse: type: object properties: message: type: string description: Human-readable confirmation. required: - message TrackerMutationResponse: type: object properties: tracker: $ref: '#/components/schemas/Tracker' message: type: string description: Human-readable confirmation. required: - tracker - message 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. Tracker: type: object properties: id: type: string description: Tracker id in the form "trk_{hex}". entity_name: type: string description: The tracked entity name, as submitted. entity_type: type: string description: 'The tracked entity type. Values: person, organization, product, topic, channel.' display_name: type: string description: User-facing display name. Falls back to entity_name when not customized. notify_email: type: boolean description: True when this tracker delivers by email (default true at creation). notify_webhook: type: boolean description: True when this tracker has a per-tracker webhook override enabled. notify_slack: type: boolean description: True when this tracker has a per-tracker Slack override enabled. webhook_url: type: - string - 'null' description: Per-tracker webhook destination override. Null when the tracker uses its monitor's delivery settings. Absent when the tracker is in a team monitor the caller does not own. slack_channel_id: type: - string - 'null' description: Per-tracker Slack channel override. Null when not set. slack_integration_id: type: - string - 'null' description: Per-tracker Slack integration override. Null when not set. filters: type: - object - 'null' additionalProperties: {} description: Optional matching filters as submitted. Null when none were set. paused: type: boolean description: True when the tracker is paused. paused_at: type: - string - 'null' description: When the tracker was paused. Null unless paused. last_notified_at: type: - string - 'null' description: When the tracker last produced an alert. Null until the first alert. created_at: type: string description: When the tracker was created. updated_at: type: - string - 'null' description: When the tracker was last updated. monitor_id: type: string description: The monitor this tracker belongs to. Absent for standalone trackers. email_delivery_count: type: integer description: Email deliveries in the current billing period. webhook_delivery_count: type: integer description: Webhook deliveries in the current billing period. slack_delivery_count: type: integer description: Slack deliveries in the current billing period. required: - id - entity_name - entity_type - display_name - notify_email - notify_webhook - notify_slack - slack_channel_id - slack_integration_id - filters - paused - paused_at - last_notified_at - created_at - updated_at - email_delivery_count - webhook_delivery_count - slack_delivery_count 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.' Alert: type: object properties: id: type: string description: Alert delivery id. tracker_id: type: - string - 'null' description: Id of the tracker (tracked entity) that produced the alert. monitor_id: type: - string - 'null' description: Id of the monitor the tracker belongs to. Null for trackers outside a monitor. entity_id: type: - string - 'null' description: Public id ("ent_{n}") of the entity that triggered the alert, when recorded. Null on older rows that were written before entity_id was stored on alert_delivery. Resolve the entity through mention_id or the embedded tracker when this is null. mention_id: type: - string - 'null' description: Public id ("men_{n}") of the mention/appearance row that triggered the alert. Joins directly against mention rows (e.g. /v1/mentions). Null when not appearance-scoped. video_id: type: - string - 'null' description: YouTube video id (11 characters) of the video that triggered the alert. Null when not media-scoped. excerpt_id: type: - string - 'null' description: Id of the active mention excerpt used as mention evidence. Null when the alert was sent before evidence was recorded. evidence_kind: type: - string - 'null' enum: - excerpt - null description: Which evidence layer was sent. Null on older rows. channel: type: string description: 'Delivery channel. Values: email (sent by email), webhook (POSTed to the configured webhook URL), slack (sent to Slack).' status: type: string description: 'Delivery status. Values: pending (queued for delivery), sent (delivered), failed (delivery failed; see error_message), skipped (delivery intentionally skipped).' final_status: type: - string - 'null' description: Terminal status after retries. Null while delivery is still in progress. error_message: type: - string - 'null' description: Error details for failed deliveries. Null unless delivery failed. scheduled_at: type: - string - 'null' description: When delivery was scheduled. Null when delivered immediately. sent_at: type: - string - 'null' description: When the alert was actually sent. Null until delivery succeeds. created_at: type: string description: When the alert row was created. tracker: type: object properties: id: type: - string - 'null' description: Tracker id. entity_name: type: - string - 'null' description: Tracked entity name. entity_type: type: - string - 'null' description: Tracked entity type. display_name: type: - string - 'null' description: User-facing display name for the tracker. Null when not customized. required: - id - entity_name - entity_type - display_name description: The tracker the alert belongs to. Fields are null when the tracker row was deleted. monitor: type: - object - 'null' properties: id: type: string description: Monitor id. name: type: - string - 'null' description: Monitor name. required: - id - name description: The monitor the tracker belongs to. Null for trackers outside a monitor. required: - id - tracker_id - monitor_id - entity_id - mention_id - video_id - excerpt_id - evidence_kind - channel - status - final_status - error_message - scheduled_at - sent_at - created_at - tracker - monitor TrackerListResponse: type: object properties: trackers: type: array items: $ref: '#/components/schemas/Tracker' description: All trackers for the account, newest first. count: type: integer description: Number of trackers returned. required: - trackers - count headers: X-Arcmira-Version: description: The API version that answered. Always v1. schema: type: string enum: - v1 Idempotency-Replayed: description: true when this is the stored response to an earlier request with the same Idempotency-Key; the request did not run again. schema: type: string enum: - 'true' 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_. 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