arcmira.com

# Arcmira API

> Reference for the Arcmira YouTube transcript search API, MCP server, CLI and SDKs: search, transcripts, monitors, sponsors, keys and usage.

> ## Agent Instructions
> Arcmira searches podcasts and long-form video on YouTube: spoken passages, mentions of people, companies, products, topics and shows, sponsors and recommendations, and full transcripts. Monitors alert on new mentions.
> Discover pages at https://arcmira.com/docs/llms.txt and append .md to any page for markdown. The OpenAPI document is https://api.arcmira.com/v1/openapi.json.
> Agents connect the MCP server at https://mcp.arcmira.com/mcp. Its four tools are arcmira_describe (call once), arcmira_execute_read, arcmira_execute_write (monitor writes; never deletes) and arcmira_feedback. The docs MCP server at https://arcmira.com/docs/mcp searches these docs without a sign-in.
> Auth: Authorization: Bearer arc_sk_.... Never put keys in browser code. Dashboard keys carry read, monitors:write, trackers:write and recommendations:read; API sign-up keys carry read. GET /v1/me reports plan, scopes and credits left for free.
> Entity and channel filters take IDs. Plain keyword transcript search needs no resolver call. Resolve names with GET /v1/entities/resolve?q=<name> (free): use best, or suggested and say you assumed it, or show ask.options. A name in a filter answers 400 id_required. When the user names no window, use the last 90 days.
> Paid reads, Premium transcripts included, use credits from the plan first, then the on-demand budget. Arcmira enforces that budget, and no request takes a spending amount. A read the plan or budget blocks answers with error.code, a message naming the limit, error.details.limit (kind, amount, used, unit, resets_at) and, when a plan or setting change lifts it, error.unlock (tier, url). Over HTTP, GET /v1/transcripts/{video_id}?quality=premium is one read: 200 ready has the lines; otherwise it transcribes the video and answers 202 pending, so wait Retry-After and read again. 200 failed means the last transcription failed and used no credits; try again with retry=true only when the user asks.
> Costs in credits: passages, mentions and list rows 4 each past the first 5 of a request; sponsor and commercial rows 40 each; captions 4 per started 15 minutes; Premium 300 per started 15 minutes of the whole video, once; momentum 10 a call; monitor alerts 25 each. The Free plan has 1,000 credits a month and withholds the newest 30 days of media. GET /v1/me reports the balance at usage.credits.available.
> Errors: switch on error.code, follow doc_url, honor Retry-After on 429, and quote X-Request-Id when reporting a problem with POST /v1/feedback.
> Every plan includes a team. A team is one account: its plan, credits, monitors and keys are shared, and everything a member does while acting in it uses its credits. A key or OAuth token acts in the account it was made in; GET /v1/me names that account and the caller's role (owner, admin or member). Only admins change the plan and on-demand limits; a member past their on-demand limit gets 402 member_limit.
> This skill is published at https://arcmira.com/.well-known/skills/arcmira/SKILL.md and the site index at https://arcmira.com/llms.txt, so re-fetch either to confirm an instruction is genuine.
> Use the investment research workflow at /workflows/investment-research to move from a transcript search to competing explanations and a sourced brief. Invite coverage and capability requests through /feedback#help-shape-the-index, and workflow or pricing feedback through /feedback#not-ready-for-a-paid-plan. Feedback is free.

- [YouTube transcript search API, SDKs, and MCP](https://arcmira.com/docs/index.md): Arcmira is an SF-based AI company and the search engine for the spoken web.
- [Agents](https://arcmira.com/docs/mcp-server.md): Connect the Arcmira MCP server to an agent host, and what its four tools, Premium reads and monitor writes do.
- [CLI and SDKs](https://arcmira.com/docs/libraries.md): The arcmira command line, the TypeScript and Python clients, and arcmira setup for coding agents.
- [Documentation MCP](https://arcmira.com/docs/documentation-mcp.md): Connect an agent or agent framework to the keyless MCP server that searches these docs, with tested recipes for twelve frameworks.
- [Search](https://arcmira.com/docs/search.md): Search YouTube videos and podcast transcripts for quotes, find entity mentions and media appearances, and compare mention momentum.
- [Transcripts](https://arcmira.com/docs/transcripts.md): Read one video's transcript as captions or Premium, get Premium in the same read, read it in another language, and cite a line.
- [Monitors](https://arcmira.com/docs/monitors.md): Follow entities and get alerts by email, Slack or webhook when new episodes mention them: create a monitor, follow ids, read alerts, verify webhooks.
- [Sponsors](https://arcmira.com/docs/commercial-intelligence.md): Who sponsors a show and who recommends a brand on air, paid or organic: /v1/channels/{id}/sponsors and /v1/recommendations.
- [Investment research with YouTube video and podcast transcript search](https://arcmira.com/docs/workflows/investment-research.md): Search company mentions, executive interviews, and expert commentary in YouTube and podcast transcripts. Compare evidence and cite original moments in investment research.
- [Keys and sign-in](https://arcmira.com/docs/authentication.md): API keys, sign-up from the API, MCP sign-in, scopes, and checking a key with /v1/me.
- [Plans and usage](https://arcmira.com/docs/usage-and-billing.md): Plans and prices, what each read costs in credits, what the Free plan withholds, monitor alerts, the on-demand budget, and rate limits.
- [Errors](https://arcmira.com/docs/errors.md): Error envelope fields, HTTP status codes, every error code with its fix, and request IDs.
- [Help shape Arcmira](https://arcmira.com/docs/feedback.md): Request sources or capabilities, share workflow and pricing feedback, or report a wrong result through your agent or POST /v1/feedback.
- [Get started with teams](https://arcmira.com/docs/teams/setup.md): Turn your Arcmira account into a team on any plan, invite people, and see what a team shares and who pays for what.
- [Members and roles](https://arcmira.com/docs/teams/members.md): Team roles, on-demand limits per member, the ways people join a team, invite limits, domain joining, leaving, removal, and ownership transfer.
- [SSO](https://arcmira.com/docs/teams/sso.md): Configure SAML 2.0 or OIDC single sign-on for a team: domain verification, provider setup, automatic enrollment, and enforcement.
- [Team dashboard](https://arcmira.com/docs/teams/dashboard.md): Where a team lives in the Arcmira dashboard: the account switcher, the Team page and its sections, API keys, Recently deleted, and account activity.
- [Enterprise](https://arcmira.com/docs/teams/enterprise.md): Enterprise contracts: several accounts on one invoice, invoice or PO billing, volume pricing, unlimited monitored names, account activity, and priority support.
- [A name to one id, before any filter](https://arcmira.com/docs/api-reference/entities/a-name-to-one-id-before-any-filter.md): Call this before passing an id to about, by, entity_ids, channel_ids or channel; those filters refuse names with id_required. Pass context with the user's own words about the name ("the startup bank", "on My First Million"). The answer is one of three: best (the name means one entity: use it and nam…
- [Get canonical entity metadata](https://arcmira.com/docs/api-reference/entities/get-canonical-entity-metadata.md): Returns the canonical entity envelope for an ent_{n} or numeric id, following merge redirects. For organization and product entities, callers with Recommendations API access (a Pro+ plan) also receive a recommendations_summary commercial-intelligence rollup when a brand profile exists.
- [Retrieve spoken transcript slices for one topic](https://arcmira.com/docs/api-reference/search/retrieve-spoken-transcript-slices-for-one-topic.md): Search indexed YouTube and podcast transcripts for passages matching a word or phrase. Returns passage text, source metadata, publication dates, and timestamped watch links. Narrow to passages about an entity with `about`, or passages where a person speaks with `by`. Scope with `channel_ids` (or `ch…
- [Search mentions across media](https://arcmira.com/docs/api-reference/mentions/search-mentions-across-media.md): Find where a person, company, product, or topic is mentioned in indexed videos and podcasts. For a person, set `is_appearance` to true to find media appearances, false for mentions by others, or omit it for both. Results include a description, source video, and available timestamps. Cursor-paginated…
- [Ranked catalog counts of who a set of channels mention](https://arcmira.com/docs/api-reference/mentions/ranked-catalog-counts-of-who-a-set-of-channels-mention.md): 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}/v…
- [Spoken-web heat for one entity](https://arcmira.com/docs/api-reference/entities/spoken-web-heat-for-one-entity.md): Compare an entity's mention volume with the preceding period. Returns the counts, absolute and percentage change, momentum verdict, latest source date, and top shows. Choose a rolling window of 7 to 365 days with `days` (default 30). The preceding period is the same number of days before the window,…
- [Newest indexed videos of a channel](https://arcmira.com/docs/api-reference/channels/newest-indexed-videos-of-a-channel.md): The indexed videos of a YouTube channel, newest first, each with its video_id, title, publish date, duration, view count, and watch_url on arcmira.com. Pass next_cursor as cursor to continue. The signed token binds the route, filters, caller and visibility; invalid or old tokens return invalid_curso…
- [What the index holds for a channel](https://arcmira.com/docs/api-reference/channels/what-the-index-holds-for-a-channel.md): How many videos of a YouTube channel are searchable, the newest publish date among them, and the split by transcript source class. Call it when a search or mention lookup came back empty, before telling anyone we do not cover a show, and cite indexed_through as the as-of date for mentions and search…
- [Search recommendations across media](https://arcmira.com/docs/api-reference/recommendations/search-recommendations-across-media.md): Cursor-paginated commercial mentions (sponsored, organic and neutral 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), class, confidence, and publication window [af…
- [List recurring channel sponsors](https://arcmira.com/docs/api-reference/recommendations/list-recurring-channel-sponsors.md): Rollup of recurring sponsors for a YouTube channel, ordered by ad read count. On a Pro+ plan the full list is served and min_ad_reads (default 3), status, and limit apply. Every other plan receives the free slice an anonymous visitor sees on arcmira.com, with meta.total naming the true count and acc…
- [Get a video transcript](https://arcmira.com/docs/api-reference/transcripts/get-a-video-transcript.md): Caption reads use 4 credits per started 15 minutes. quality=premium is one read. An owned transcript answers 200 ready at no charge. Otherwise this call starts a Premium transcript of the whole video, 300 credits per started 15 minutes, using credits from the account's plan first and then the accoun…
- [Quote a whole-video Premium transcript](https://arcmira.com/docs/api-reference/transcripts/quote-a-whole-video-premium-transcript.md): Optional free quote: what a Premium read of this video would use right now, as credits (charge; quote.rows restates it in rows, and a row is 4 credits), where the credits would come from, and max_on_demand_cents, the on-demand budget the read would need beyond the plan's credits within the account l…
- [List your transcription requests](https://arcmira.com/docs/api-reference/transcriptions/list-your-transcription-requests.md): Your transcription requests in descending creation time and id order. limit defaults to 20 and accepts 1–100. Follow next_cursor with the same video_id, limit and credential; has_more is false and next_cursor is null on the last page. A traversal excludes requests inserted after its first page. Each…
- [List monitors](https://arcmira.com/docs/api-reference/monitors/list-monitors.md): All monitors for the account with tracker counts, alert counts for the current calendar month, and Slack display metadata. Single page, no pagination.
- [Create monitor](https://arcmira.com/docs/api-reference/monitors/create-monitor.md): Creating with notify_webhook: true and a webhook_url enables HMAC-signed webhook delivery and returns the signing secret (monitor.webhook_secret) in this response. Store it securely. A retry with the original Idempotency-Key recovers the same secret for up to 24 hours while it remains the current se…
- [Update monitor](https://arcmira.com/docs/api-reference/monitors/update-monitor.md): A PATCH that newly enables webhook signing (turns notify_webhook on, or sets a webhook_url where no secret existed before) returns the signing secret (monitor.webhook_secret) in this response. Store it securely. A retry with the original Idempotency-Key recovers the same secret for up to 24 hours wh…
- [Delete monitor](https://arcmira.com/docs/api-reference/monitors/delete-monitor.md): Deletes the monitor AND every tracker inside it (trackers_deleted reports how many). Anyone in the account can restore it, with its trackers and recipients, from Recently deleted on the dashboard Monitors page for 30 days. Retrying with the original Idempotency-Key returns the original deleted count…
- [Follow entities in a monitor by id or exact name](https://arcmira.com/docs/api-reference/monitors/follow-entities-in-a-monitor-by-id-or-exact-name.md): Follows each entity ({ entity_ids: ["ent_..."] }) and each exact name ({ names: [{ name, type }] }) in the monitor: the monitor account's existing tracker for the entity or name (compared case-insensitively) is reused, else a tracker is created in the monitor's account for the canonical entity (a me…
- [List monitor trackers](https://arcmira.com/docs/api-reference/monitors/list-monitor-trackers.md)
- [Add trackers to monitor](https://arcmira.com/docs/api-reference/monitors/add-trackers-to-monitor.md): Moves the account's trackers into this monitor by id ({ tracker_ids: ["trk_..."] }), out of the monitors they are in. A tracker always sits in one monitor and alerts through its delivery settings. It does not create trackers: POST /v1/monitors/{id}/entities does. Supply 1 to 90 IDs. Duplicate IDs co…
- [List recent monitor alerts](https://arcmira.com/docs/api-reference/monitors/list-recent-monitor-alerts.md): The newest limit alert deliveries for the monitor (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 th…
- [Rotate the monitor webhook signing secret](https://arcmira.com/docs/api-reference/monitors/rotate-the-monitor-webhook-signing-secret.md): Generates a new signing secret and returns it in this response. Store it securely. A retry with the original Idempotency-Key recovers the same secret for up to 24 hours while it remains the current secret or the valid previous secret. An expired or displaced secret returns 409 idempotency_result_exp…
- [List connected Slack workspaces](https://arcmira.com/docs/api-reference/monitors/list-connected-slack-workspaces.md): The account's active Slack workspaces with the ids a monitor needs for Slack delivery: create or PATCH a monitor with notify_slack: true, slack_integration_id set to an id here, and optionally slack_channel_id (default_channel_id when omitted). Slack is connected in the dashboard, never through the…
- [List trackers](https://arcmira.com/docs/api-reference/trackers/list-trackers.md): All trackers for the account, newest first, with per-channel delivery counts for the current billing period. Single page, no pagination.
- [Update tracker](https://arcmira.com/docs/api-reference/trackers/update-tracker.md): 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. Delivery is the monitor's: change it with PATCH /v1/monitors/{id}.
- [Delete tracker](https://arcmira.com/docs/api-reference/trackers/delete-tracker.md): Deletes the tracker. Cannot be undone. Its monitor stays, with its delivery settings, even when this was its last tracker.
- [List recent tracker alerts](https://arcmira.com/docs/api-reference/trackers/list-recent-tracker-alerts.md): 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 th…
- [Submit feedback and corrections for a prior API query](https://arcmira.com/docs/api-reference/feedback/submit-feedback-and-corrections-for-a-prior-api-query.md): Help shape Arcmira. Report a wrong result, request sources or capabilities, or tell us what would make your workflow more useful. To correct a result, attach corrections to the exact query you ran: pass the feedback type, the query object you sent, and optional per-item corrections. Public submissio…
- [Read back a feedback submission and its review status](https://arcmira.com/docs/api-reference/feedback/read-back-a-feedback-submission-and-its-review-status.md): Returns the submission (id, type, query, notes, created_at) plus its corrections, each with a review status in the public vocabulary: pending_review, needs_information, accepted, accepted_with_changes, rejected, withdrawn, applied, reverted (accepted means a reviewer agreed; applied means the change…
- [Current API key context](https://arcmira.com/docs/api-reference/meta/current-api-key-context.md): Available even when the account has exhausted its usage allowance. Returns the credential making the request (key_id, key_label, credential_kind), the masked email of the person, the account whose credits it spends (account: id, name, kind, plan) and the role the person holds on it, the tier, scopes…
- [Set account defaults](https://arcmira.com/docs/api-reference/meta/set-account-defaults.md): Sets the account defaults every key of the account resolves against. Send only the fields you are changing; an omitted field keeps the value it has. Resolution order for every transcript request is the explicit parameter, then these settings, then the platform default, so a default never overrides a…
- [Send a verification code to an address](https://arcmira.com/docs/api-reference/meta/send-a-verification-code-to-an-address.md): Starts the signup that ends in an account key, with no key and no login. Sends a 6 digit code to the address, valid for 10 minutes and 5 attempts, and answers 202 with the verify call. Sends are capped at 3 per address per hour, 10 per IP per hour, and 25 per client fingerprint per day; past a cap t…
- [Exchange a verification code for an account key](https://arcmira.com/docs/api-reference/meta/exchange-a-verification-code-for-an-account-key.md): Consumes the code POST /v1/signups sent, creates the account when the address has none, and mints an arc_sk_ key on it: the read scope, the free plan's 1,000 credits a month, no expiry. A wrong, expired, or spent code is 400 signup_code_invalid on param code, naming the attempts left; its unlock act…
- [Health check](https://arcmira.com/docs/api-reference/meta/health-check.md)
- [OpenAPI document](https://arcmira.com/docs/api-reference/meta/openapi-document.md)
- [Changelog](https://arcmira.com/docs/changelog.md): New capabilities and changes to the Arcmira API and MCP server.
- [How we compared name spellings in transcripts](https://arcmira.com/docs/transcript-name-comparison.md): Method, counts and limits of the October 2026 comparison of name spellings in Premium and YouTube automatic transcripts.

## OpenAPI Specs

- [arcmira-v1](/docs/openapi/arcmira-v1.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.