TranscriptSearchResponse
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The q parameter echoed back."
},
"limit": {
"type": "integer",
"description": "The limit applied."
},
"returned": {
"type": "integer",
"description": "Chunks returned."
},
"filters": {
"type": "object",
"properties": {
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Channel ids the search was scoped to, after entity_ids were expanded."
},
"entity_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exact explicit entity_ids accepted for this search. Every id was resolved; an unknown id is refused."
},
"about": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NamedEntityRef"
},
"description": "The about ids, each with its name and type."
},
"by": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NamedEntityRef"
},
"description": "The by ids, each with its name and type."
},
"kind": {
"type": "array",
"items": {
"type": "string",
"enum": [
"sponsored",
"organic",
"mention"
]
},
"description": "The passage classes applied."
}
},
"required": [
"channel_ids",
"entity_ids",
"about",
"by",
"kind"
]
},
"window": {
"$ref": "#/components/schemas/PublicationWindow"
},
"chunks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TranscriptSearchChunk"
},
"description": "Ranked slices. Empty means no hit in the shows we index; say so, never search the open web."
},
"as_of": {
"type": [
"string",
"null"
],
"description": "Newest published_at among the chunks. Null when there are none."
},
"search_index": {
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"live",
"catching_up",
"unknown"
],
"description": "Whether every indexed transcript is searchable. catching_up means older transcripts are still being added; note says so when the asked window reaches them."
},
"missing_before": {
"type": [
"string",
"null"
],
"description": "While catching up, transcripts published before this date may be missing from search."
}
},
"required": [
"state",
"missing_before"
],
"description": "Health of the search index behind these results. Catalog routes are unaffected by it."
},
"access": {
"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"
},
"limit": {
"$ref": "#/components/schemas/Limit"
},
"url": {
"type": "string",
"description": "On terms_acceptance_required: the page where the person accepts the updated Terms of Service. On terms_updated: the Terms of Service page."
}
},
"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"
],
"description": "The gate that reduced this response. Present only when something was withheld; carries the same code, gate, and unlock an outright refusal would."
},
"freshness": {
"allOf": [
{
"$ref": "#/components/schemas/Freshness"
},
{
"description": "Present when your plan's freshness gate cut the window: where results on this plan stop. unlock names the plan that reads past it."
}
]
},
"unlock": {
"type": "object",
"properties": {
"tier": {
"type": "string",
"description": "The plan that lifts the freshness gate."
},
"url": {
"type": "string",
"description": "Where to start that plan."
}
},
"required": [
"tier",
"url"
],
"description": "Present with freshness when your plan's freshness gate cut the window; note says so."
},
"note": {
"type": "string",
"description": "One steering sentence for the agent reading this."
}
},
"required": [
"query",
"limit",
"returned",
"filters",
"window",
"chunks",
"as_of",
"search_index",
"note"
],
"example": {
"query": "Ramp corporate cards",
"limit": 5,
"returned": 1,
"filters": {
"channel_ids": [
"UC-DRzaGnL_vtBUpCFH5M0tg"
],
"entity_ids": [],
"about": [
{
"id": "ent_14",
"name": "Ramp",
"type": "organization"
}
],
"by": [],
"kind": [
"sponsored"
]
},
"window": {
"after": "2026-08-01T00:00:00Z",
"before": null
},
"chunks": [
{
"id": "UC-DRzaGnL_vtBUpCFH5M0tg/2026-08-04/dQw4w9WgXcQ.md#12",
"video_id": "dQw4w9WgXcQ",
"channel_id": "UC-DRzaGnL_vtBUpCFH5M0tg",
"channel_name": "TBPN",
"video_title": "TBPN | Tuesday, August 4",
"speakers": [
"John Coogan"
],
"source": "creator_captions",
"source_label": "3rd Party (Video Creator)",
"published_at": "2026-08-04T17:00:00.000Z",
"text": "Ramp has been on the show for a while now and the pitch is still the same, spend less time on expenses.",
"start_seconds": 4787,
"watch_url": "/watch?v=dQw4w9WgXcQ&t=4787",
"cite_line": "[TBPN | Tuesday, August 4](/watch?v=dQw4w9WgXcQ&t=4787) · @1:19:47 · TBPN · Aug 4, 2026",
"score": 0.71,
"about": [
{
"id": "ent_14",
"name": "Ramp",
"type": "organization"
}
],
"speakers_by": [
{
"id": "ent_27",
"name": "John Coogan",
"type": "person"
}
]
}
],
"as_of": "2026-08-04T17:00:00.000Z",
"search_index": {
"state": "live",
"missing_before": null
},
"note": "Quote text as a spoken beat of a few sentences and cite watch_url with published_at. State the window from window.after when you passed one."
}
}