{ "openapi": "3.1.0", "info": { "title": "PodMule API", "version": "2026-04", "description": "Capability-style REST API. Each path is `POST /api/v1/{capability}`; the request body is the capability's input, and the response is `{ data: }`. Auth is OAuth 2.1 Bearer JWT with audience `https://app.podmule.com/api`." }, "servers": [ { "url": "https://app.podmule.com/api/v1" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth 2.1 Bearer token. Issuer: https://app.podmule.com. Audience: https://app.podmule.com/api. Discover endpoints at /.well-known/oauth-authorization-server." } }, "schemas": { "CapabilityError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable error code. Same vocabulary across REST + MCP." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "request_id": { "type": "string", "format": "uuid" } } } } } } }, "security": [ { "BearerAuth": [] } ], "paths": { "/list_workspaces": { "post": { "operationId": "list_workspaces", "summary": "list_workspaces", "description": "List the workspaces (organizations) the authenticated user is a member of. Returns each workspace with the user's role and a flag indicating which one is currently active for this session.", "tags": [ "workspaces" ], "security": [ { "BearerAuth": [ "mcp:tools", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/set_active_workspace": { "post": { "operationId": "set_active_workspace", "summary": "set_active_workspace", "description": "Set the active workspace for this session. The chosen workspace becomes the org context for subsequent capability calls until the next switch. The user must be a member of the target workspace.", "tags": [ "active_workspace" ], "security": [ { "BearerAuth": [ "mcp:tools", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/switch_workspace": { "post": { "operationId": "switch_workspace", "summary": "switch_workspace", "description": "Switch to a different workspace. Subsequent capability calls operate in the new workspace until the next switch. Requires the user to be a member of the target workspace; otherwise returns NOT_FOUND.", "tags": [ "workspace" ], "security": [ { "BearerAuth": [ "mcp:tools", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/search_episodes": { "post": { "operationId": "search_episodes", "summary": "search_episodes", "description": "Search episodes in the active workspace by show, status, free-text query (title, show notes, OR guest_name), season + episode number, season/episode presence, or published date range. When the user names a guest (e.g., \"Orlagh Reynolds\", \"Reynolds\"), use `query` — it ILIKE-matches against guest_name as well as title/notes, so partial spellings hit. Each item includes primary_contacts from episode_contacts, so compare episodes to interview bookings by contact_id instead of free-text guest_name when answering coverage questions. When the user gives season + episode coordinates (\"S4 E13\", \"season 4, episode 13\"), pass both as `season` and `episode` integer filters. For RSS-import cleanup/enrichment questions about MISSING fields (\"episodes with no season\", \"no season but has an episode number\", \"episodes missing an episode number\"), use the boolean presence filters `has_season` and `has_episode` (false = field IS NULL, true = field IS NOT NULL) — never pass a season/episode number to mean \"unset\". Read `total` for the exact count. For Planned Episodes, use status=planned; these have null season/episode until activate_planned_episode is called. For \"latest\", \"current\", \"recent\", or \"what episodes are published\", use status=published and a small limit; results sort by published_date newest first, then created_at. The `total` field is the exact count across all pages — use it for \"how many episodes\" answers, never items.length when has_more is true.", "tags": [ "episodes" ], "security": [ { "BearerAuth": [ "episodes:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_episode": { "post": { "operationId": "get_episode", "summary": "get_episode", "description": "Get a single episode by id with full detail: status, show notes, summary, themes, hashtags, chapters, and primary contacts (guests).", "tags": [ "episode" ], "security": [ { "BearerAuth": [ "episodes:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/search_transcripts": { "post": { "operationId": "search_transcripts", "summary": "search_transcripts", "description": "Semantic search across episode transcripts using vector similarity. Use this for topic/back-catalogue questions like \"which episodes discuss cancer\", \"episodes about sudden death\", \"what did we say about X\", or quote/passages search. It also performs intelligent exact search across stored transcripts, summaries, show notes, titles, guest names, themes, hashtags, and chapters; compound asks such as \"partner died from cancer\" require the cancer concept plus death/loss language rather than matching any single token. When the user asks which episodes discuss a topic, search transcripts with the topic phrase, pass show_id when a show is known, use limit=50 for all/broad lists, and answer from matched_episodes rather than claiming no episodes from search_episodes alone. Make ONE search_transcripts call for a topic or quote pack. Do not re-issue near-duplicate searches for the same topic, and do not loop per episode, unless the user changes the ask. The capability internally searches a wider chunk set than the requested episode limit so matched_episodes is not limited to the first few chunk-heavy episodes. For an exact passage, the full surrounding section, or a reliable timestamp (\"give me the full section and the timestamp\", \"where exactly does X say Y\"), do NOT re-search — call get_transcript_window once with the matching item's chunk_index (or a quote) to expand and timestamp it.", "tags": [ "transcripts" ], "security": [ { "BearerAuth": [ "transcripts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_transcript_window": { "post": { "operationId": "get_transcript_window", "summary": "get_transcript_window", "description": "Return the surrounding transcript section for a quote or chunk index, with start/end timestamps. Use this to answer \"give me the full section and the timestamp\" or \"where exactly does X say Y\" in one call: run search_transcripts first to locate the passage, then pass its chunk_index (or a quote) here to expand it and get the timestamp. Avoids re-running semantic search to pin a passage. Note: episodes embedded before timestamps were captured return text with null timestamps until the embedding backfill runs.", "tags": [ "transcript_window" ], "security": [ { "BearerAuth": [ "transcripts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/create_episode": { "post": { "operationId": "create_episode", "summary": "create_episode", "description": "Create a new episode under a show in the active workspace. Use status=planned for an unnumbered Planned Episode. Provide either a title, or both season and episode numbers for numbered production episodes. Returns the new episode id.", "tags": [ "episode" ], "security": [ { "BearerAuth": [ "episodes:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/update_episode": { "post": { "operationId": "update_episode", "summary": "update_episode", "description": "Update mutable fields on an existing episode. Pass only the fields you want to change. Pass null to explicitly clear a field; omit a field to leave it unchanged. Use change_episode_status for status changes that need transition validation.", "tags": [ "episode" ], "security": [ { "BearerAuth": [ "episodes:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/change_episode_status": { "post": { "operationId": "change_episode_status", "summary": "change_episode_status", "description": "Change an episode's status with lifecycle validation: planned, draft, authorised, scheduled, published. Planned Episodes must be moved to draft with activate_planned_episode so numbering is assigned safely.", "tags": [ "episode_status" ], "security": [ { "BearerAuth": [ "episodes:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/activate_planned_episode": { "post": { "operationId": "activate_planned_episode", "summary": "activate_planned_episode", "description": "Activate a Planned Episode. Moves status from planned to draft and assigns the next season/episode number, unless both season and episode are provided as a manual override.", "tags": [ "planned_episode" ], "security": [ { "BearerAuth": [ "episodes:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/delete_episode": { "post": { "operationId": "delete_episode", "summary": "delete_episode", "description": "Delete an episode permanently. Cascades to chapters, themes, hashtags, contact links, and transcript embeddings. For titled episodes the caller must pass confirm_title matching the episode's current title. Episodes do not have an archived state.", "tags": [ "episode" ], "security": [ { "BearerAuth": [ "episodes:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/generate_show_notes_preview": { "post": { "operationId": "generate_show_notes_preview", "summary": "generate_show_notes_preview", "description": "Generate show notes for an episode INLINE and return the result WITHOUT writing to episodes.show_notes. Use when the user asks 'preview', 'show me what they would be', 'what would the show notes look like'. Returns the LLM output PLUS the resolved prompt template (key + scope: organization/global/code_default + interpolated body) so the user can verify which prompt was actually applied. For the persist-and-write flow use enqueue_show_notes_generation. For both, the prompt-resolution chain is identical (org override > global > code default), so the preview matches what the job would produce.", "tags": [ "show_notes_preview" ], "security": [ { "BearerAuth": [ "episodes:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/match_episode_guests_to_contacts": { "post": { "operationId": "match_episode_guests_to_contacts", "summary": "match_episode_guests_to_contacts", "description": "Sweep episodes that have a guest name but no linked guest contact, and match each guest name against the workspace's contacts using trigram name similarity. Returns each episode pre-classified as matched (one confident candidate, ready to link), ambiguous (multiple/uncertain candidates, needs a human pick), or no_match (create a new contact). Runs the whole sweep server-side in one call per batch — page through large sets with limit/offset using total_candidate_episodes. Apply the proposed links with link_contact_to_episode (single) or link_episode_contacts (batch) after confirming with the user.", "tags": [ "episode_guests_to_contacts" ], "security": [ { "BearerAuth": [ "episodes:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/link_contact_to_episode": { "post": { "operationId": "link_contact_to_episode", "summary": "link_contact_to_episode", "description": "Link one contact to one episode with a role (default \"Guest\"). Use after match_episode_guests_to_contacts confirms a single match, or whenever a user asks to attach a contact to an episode. Idempotent: re-linking the same contact+role is a no-op; a different role updates the link. For applying many matches at once, prefer link_episode_contacts.", "tags": [ "contact_to_episode" ], "security": [ { "BearerAuth": [ "episodes:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/link_episode_contacts": { "post": { "operationId": "link_episode_contacts", "summary": "link_episode_contacts", "description": "Apply a batch of episode↔contact links in one atomic call. Use to apply confirmed matches from match_episode_guests_to_contacts without a write per episode. Idempotent: already-linked pairs are reported already_linked, role changes are reported updated; pairs referencing entities outside the workspace are skipped and reported as invalid. Requires expected_affected_count = links.length. For a single link use link_contact_to_episode.", "tags": [ "episode_contacts" ], "security": [ { "BearerAuth": [ "episodes:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_episode_speakers": { "post": { "operationId": "list_episode_speakers", "summary": "list_episode_speakers", "description": "List the diarized transcript speakers in an episode that can still be assigned to a contact: unresolved \"Speaker N\" placeholders and speakers a prior step named but did not link. Use the returned key with relabel_episode_speaker.", "tags": [ "episode_speakers" ], "security": [ { "BearerAuth": [ "episodes:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/relabel_episode_speaker": { "post": { "operationId": "relabel_episode_speaker", "summary": "relabel_episode_speaker", "description": "Assign a contact to an unnamed \"Speaker N\" placeholder in an episode transcript. Rewrites the transcript + SRT (label-anchored), persists the speaker map, links the contact as a guest, and re-embeds in the background. Use list_episode_speakers first to get the speaker_key.", "tags": [ "episode_speaker" ], "security": [ { "BearerAuth": [ "episodes:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/run_decide": { "post": { "operationId": "run_decide", "summary": "run_decide", "description": "Judge a publishing proposal against the Show voice. Returns Choice / Score / Noul answers plus a continue or human_work outcome. Does not rewrite the proposal.", "tags": [ "decide" ], "security": [ { "BearerAuth": [ "episodes:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/search_knowledge": { "post": { "operationId": "search_knowledge", "summary": "search_knowledge", "description": "Search the Show's durable Knowledge Base (brain), synthesised across every Feeder — episodes, articles, and captured sources: per-source intelligence pages (overview, takeaways, cited quotes), cross-feeder TOPIC pages (how a theme is treated across many sources), and PERSON/GUEST pages (appearances + their quotes). Prefer this over search_transcripts for cross-source synthesis questions — \"what does the show know about X\", \"which themes keep recurring\", \"what has guest X said across appearances\", \"give me a briefing on topic X\". Use search_transcripts instead for exact quotes, timestamped evidence, or single-passage lookup; knowledge pages cite episodes, so verify details against transcripts via get_knowledge_page citations when precision matters.", "tags": [ "knowledge" ], "security": [ { "BearerAuth": [ "transcripts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_knowledge_page": { "post": { "operationId": "get_knowledge_page", "summary": "get_knowledge_page", "description": "Fetch one knowledge page in full: complete markdown body, every citation grounding its claims in source episodes/quotes, and links to related knowledge pages. Use after search_knowledge to read a topic/guest/episode page, and use the citations to point the user at the underlying episodes or to verify a claim against the transcript.", "tags": [ "knowledge_page" ], "security": [ { "BearerAuth": [ "transcripts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_knowledge_sources": { "post": { "operationId": "list_knowledge_sources", "summary": "list_knowledge_sources", "description": "List captured Knowledge Sources (web pages, videos, posts, notes) for the workspace, optionally filtered by show or ingestion status.", "tags": [ "knowledge_sources" ], "security": [ { "BearerAuth": [ "knowledge:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_knowledge_source": { "post": { "operationId": "get_knowledge_source", "summary": "get_knowledge_source", "description": "Fetch one Knowledge Source — its type, URL, title, and ingestion status.", "tags": [ "knowledge_source" ], "security": [ { "BearerAuth": [ "knowledge:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/create_knowledge_source": { "post": { "operationId": "create_knowledge_source", "summary": "create_knowledge_source", "description": "Capture an external source (web page, YouTube/TikTok/Instagram/X post, or pasted note) into a Show's brain. Spends credits to extract and analyse, so confirm with the user first. Returns the created source with its ingestion status.", "tags": [ "knowledge_source" ], "security": [ { "BearerAuth": [ "knowledge:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/reingest_knowledge_source": { "post": { "operationId": "reingest_knowledge_source", "summary": "reingest_knowledge_source", "description": "Re-extract and re-analyse a Knowledge Source, refreshing its contribution to the brain. Spends credits, so confirm with the user first.", "tags": [ "knowledge_source" ], "security": [ { "BearerAuth": [ "knowledge:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/delete_knowledge_source": { "post": { "operationId": "delete_knowledge_source", "summary": "delete_knowledge_source", "description": "Delete a Knowledge Source and retract its contribution to the Show's brain. The Captured Media Copy (if any) remains in the Media Library.", "tags": [ "knowledge_source" ], "security": [ { "BearerAuth": [ "knowledge:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/import_episode_media_from_url": { "post": { "operationId": "import_episode_media_from_url", "summary": "import_episode_media_from_url", "description": "Queue a background import from a direct download URL or Descript share URL into an episode. Use target=new_episode when the user says \"create a new episode with this link\"; call list_shows/search_episodes first if you need show_id or episode_id. Descript links also import transcript/subtitles and start episode processing when transcript text is available.", "tags": [ "episode_media_from_url" ], "security": [ { "BearerAuth": [ "episodes:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/import_social_media_from_url": { "post": { "operationId": "import_social_media_from_url", "summary": "import_social_media_from_url", "description": "Create or update a clip and queue a background video import from a direct URL or Descript share URL. For requests like \"add this link to episode 2 social\", first find the episode with search_episodes, then call target=new_clip with episode_id. Descript links save transcript text and start clip drafting/processing even while video render is not ready.", "tags": [ "social_media_from_url" ], "security": [ { "BearerAuth": [ "clips:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_shows": { "post": { "operationId": "list_shows", "summary": "list_shows", "description": "List all shows in the active workspace, ordered by most recently created. Returns each show's name, slug, host, description, feed URLs, and timezone.", "tags": [ "shows" ], "security": [ { "BearerAuth": [ "shows:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_show": { "post": { "operationId": "get_show", "summary": "get_show", "description": "Get a single show by id or slug. Accepts the prefixed form (sh_) or the human-readable slug. Returns the show's display fields, feed URLs, brand voice, and timezone. Settings rows flagged as protected (e.g. S3 keys) are not returned.", "tags": [ "show" ], "security": [ { "BearerAuth": [ "shows:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_show_availability": { "post": { "operationId": "get_show_availability", "summary": "get_show_availability", "description": "Get a show's booking availability: weekly recurring time windows (weekday + start/end times), blackout date ranges where the show is unavailable, and per-day interview limits. Optional since/until filters narrow blackouts to a date range.", "tags": [ "show_availability" ], "security": [ { "BearerAuth": [ "shows:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/update_show_settings": { "post": { "operationId": "update_show_settings", "summary": "update_show_settings", "description": "Update mutable show settings: name, description, brand voice, host, show email, timezone. Excludes slug / RSS / YouTube / cover URLs (those require admin or file-upload flows).", "tags": [ "show_settings" ], "security": [ { "BearerAuth": [ "shows:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/update_show_daily_limits": { "post": { "operationId": "update_show_daily_limits", "summary": "update_show_daily_limits", "description": "Update or create the daily booking limits for a show: max_bookings (per-day ceiling, 0 disables booking) and interview_length (standard slot duration in minutes).", "tags": [ "show_daily_limits" ], "security": [ { "BearerAuth": [ "shows:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/update_show_availability": { "post": { "operationId": "update_show_availability", "summary": "update_show_availability", "description": "Full-replace the weekly availability windows for a show. Pass the complete set of windows; existing windows for the show are deleted and replaced. Validates per-window start).", "tags": [ "show_blackout" ], "security": [ { "BearerAuth": [ "shows:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/search_contacts": { "post": { "operationId": "search_contacts", "summary": "search_contacts", "description": "Search contacts in the active workspace by show, group, free-text query (first/last name, email, or company), country, or city. Country uses UK/US alias expansion without substring accidents (Ukraine ≠ UK). country_not excludes that country but never treats blank country as a match — read missing_country_total and say so. Use this (then search_episodes primary_contacts) for guest-geography questions; do not start with search_transcripts. Returns paginated results.", "tags": [ "contacts" ], "security": [ { "BearerAuth": [ "contacts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_contact": { "post": { "operationId": "get_contact", "summary": "get_contact", "description": "Get a single contact by id, including their groups, social profiles, country/city, and metadata. Returns NOT_FOUND for malformed ids and contacts in other workspaces.", "tags": [ "contact" ], "security": [ { "BearerAuth": [ "contacts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_contact_notes": { "post": { "operationId": "list_contact_notes", "summary": "list_contact_notes", "description": "List the FULL note history of ONE contact, newest first, paginated — use this (not get_contact, which previews only 5) whenever the user asks to review all of a contact's notes. For several contacts at once, use list_contacts_notes; for everyone in a group, use list_group_notes. Returns NOT_FOUND for malformed ids and contacts in other workspaces.", "tags": [ "contact_notes" ], "security": [ { "BearerAuth": [ "contacts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_contacts_notes": { "post": { "operationId": "list_contacts_notes", "summary": "list_contacts_notes", "description": "Read the notes of many contacts in one call. The low-cost path for reviewing notes across a set of contacts (e.g. flagging which members of a group are widows): returns each contact's notes (newest first, capped per contact) plus the full total. Prefer this over calling get_contact / list_contact_notes per contact.", "tags": [ "contacts_notes" ], "security": [ { "BearerAuth": [ "contacts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_groups": { "post": { "operationId": "list_groups", "summary": "list_groups", "description": "List contact groups in the active workspace, optionally filtered by show. Each group includes its member_count so the agent can choose meaningful groups without a follow-up call.", "tags": [ "groups" ], "security": [ { "BearerAuth": [ "contacts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_group_members": { "post": { "operationId": "list_group_members", "summary": "list_group_members", "description": "Return the full roster of a contact group (no pagination, capped at 1000). Use this when you need the contact_ids of every member of a group — typically as input to another capability's contact_ids array filter (e.g., list_interviews, search_clips). Returns each member's prefixed contact_id plus name + email for inline rendering.", "tags": [ "group_members" ], "security": [ { "BearerAuth": [ "contacts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_group_notes": { "post": { "operationId": "list_group_notes", "summary": "list_group_notes", "description": "Return every member of a contact group together with their notes, in a single call. This is the lowest-cost path for \"review/flag the notes of everyone in group X\" (e.g. widow verification): it replaces a list_group_members call followed by one note lookup per member. Each member carries their notes (newest first, capped) plus the full total.", "tags": [ "group_notes" ], "security": [ { "BearerAuth": [ "contacts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/find_contacts": { "post": { "operationId": "find_contacts", "summary": "find_contacts", "description": "Composite query: find contacts in a group that match optional booking criteria, with per-status booking counts attached. One server-side JOIN replaces the \"list_group_members → list_interviews(contact_ids: [...])\" stitch. Use this for questions like \"how many contacts in New Applications have a booking past + future\" — the answer comes back as a single count plus per-contact summary rows. Pass has_booking: {} to mean \"any booking at all\". Omit has_booking to get every group member with their (possibly empty) booking summary. Returns aggregate booking counts only — for full booking detail, follow up with list_interviews on the contacts of interest.", "tags": [ "contacts" ], "security": [ { "BearerAuth": [ "contacts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/create_contact": { "post": { "operationId": "create_contact", "summary": "create_contact", "description": "Create a new contact in the active workspace. Required: email + at least one of first_name or last_name. Email must be unique within the workspace; duplicates surface as INVALID_INPUT. Pass `note` to attach a freeform note (e.g. a webform message) to the new contact.", "tags": [ "contact" ], "security": [ { "BearerAuth": [ "contacts:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/update_contact": { "post": { "operationId": "update_contact", "summary": "update_contact", "description": "Update mutable fields on an existing contact. Stripe-style partial: omit fields to leave unchanged, pass null to clear nullable fields. Pass `note` to append a freeform note to the contact (appended unless an identical note already exists); a note-only call is valid.", "tags": [ "contact" ], "security": [ { "BearerAuth": [ "contacts:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/delete_contact": { "post": { "operationId": "delete_contact", "summary": "delete_contact", "description": "Delete a contact permanently, including its group memberships and notes. Caller must pass confirm_email matching the contact's current email (case-insensitive).", "tags": [ "contact" ], "security": [ { "BearerAuth": [ "contacts:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/add_contact_note": { "post": { "operationId": "add_contact_note", "summary": "add_contact_note", "description": "Add a freeform note to an existing contact. Appended unless an identical note already exists (then the existing note is returned with deduped: true).", "tags": [ "contact_note" ], "security": [ { "BearerAuth": [ "contacts:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/create_group": { "post": { "operationId": "create_group", "summary": "create_group", "description": "Create a new contact group bound to a show. Pass show_id to choose which show the group belongs to. When omitted the workspace must have exactly one show — otherwise the call returns INVALID_INPUT. Groups are uniquely named per (workspace, show); duplicate names within the same show return INVALID_INPUT.", "tags": [ "group" ], "security": [ { "BearerAuth": [ "contacts:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/update_group": { "post": { "operationId": "update_group", "summary": "update_group", "description": "Update name and/or description on an existing contact group.", "tags": [ "group" ], "security": [ { "BearerAuth": [ "contacts:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/delete_group": { "post": { "operationId": "delete_group", "summary": "delete_group", "description": "Delete a contact group permanently. Empty groups delete without ceremony; groups with members require confirm: true and the membership rows are removed (contacts themselves remain).", "tags": [ "group" ], "security": [ { "BearerAuth": [ "contacts:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/add_contact_to_group": { "post": { "operationId": "add_contact_to_group", "summary": "add_contact_to_group", "description": "Add a contact to a group. Idempotent — calling on an existing membership returns already_member: true without an error.", "tags": [ "contact_to_group" ], "security": [ { "BearerAuth": [ "contacts:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/remove_contact_from_group": { "post": { "operationId": "remove_contact_from_group", "summary": "remove_contact_from_group", "description": "Remove a contact from a group. Idempotent — calling on a non-member returns not_a_member: true without an error. The contact itself is untouched.", "tags": [ "contact_from_group" ], "security": [ { "BearerAuth": [ "contacts:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/move_contacts_between_groups": { "post": { "operationId": "move_contacts_between_groups", "summary": "move_contacts_between_groups", "description": "Atomically move a set of contacts from one group to another. For \"move from X to Y\" workflows: PREFER this over add_contact_to_group + remove_contact_from_group pairs — one capability call expresses the user intent, the saved workflow gets a single composite step instead of 2N primitives, and the agent can't accidentally do half the operation. Idempotent: already_in_target and not_in_source counters are returned for resumed runs. For \"copy without removing\", use add_contact_to_group on its own; for \"remove without moving\", use remove_contact_from_group.", "tags": [ "contacts_between_groups" ], "security": [ { "BearerAuth": [ "contacts:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/upsert_contact_to_group": { "post": { "operationId": "upsert_contact_to_group", "summary": "upsert_contact_to_group", "description": "Automation-friendly action for website forms and tools like n8n, Zapier, and Make. Finds or creates a contact by email, optionally updates existing contacts when update_existing is true, finds a group by group_id or finds/creates a show-scoped group by grouping key, and ensures the contact is a member. Pass `note` to append a freeform message (e.g. from the form) to the contact, deduped against an identical existing note.", "tags": [ "contact_to_group" ], "security": [ { "BearerAuth": [ "contacts:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_interviews": { "post": { "operationId": "list_interviews", "summary": "list_interviews", "description": "List interview bookings in the active workspace, sorted by scheduled start time. Filter by show, contact, list of contact_ids, status, or date range. IMPORTANT status semantics: \"confirmed\" stays confirmed regardless of whether the date is in the past — it does NOT auto-transition to \"completed\" once the scheduled time passes. Use status=\"confirmed\" without a date filter when the user wants past+future confirmed bookings. Use the contact_ids array filter (not the single contact_id) when you have a set of contacts (e.g., from search_contacts with a group filter) and want to find their bookings — one call instead of N.", "tags": [ "interviews" ], "security": [ { "BearerAuth": [ "interviews:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_interview": { "post": { "operationId": "get_interview", "summary": "get_interview", "description": "Get a single interview booking by id with full contact and show details, scheduled times, status, timezones, and notes.", "tags": [ "interview" ], "security": [ { "BearerAuth": [ "interviews:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/create_interview_booking": { "post": { "operationId": "create_interview_booking", "summary": "create_interview_booking", "description": "Create a new interview booking in pending status. Validates contact + show ownership, future scheduled_start, and overlap against confirmed bookings. Daily-limit + availability-window checks live on the public /book flow; this capability is for staff-driven booking via the agent.", "tags": [ "interview_booking" ], "security": [ { "BearerAuth": [ "interviews:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/update_interview_booking": { "post": { "operationId": "update_interview_booking", "summary": "update_interview_booking", "description": "Update notes and/or status on an existing interview booking. For time changes use reschedule_interview_booking instead.", "tags": [ "interview_booking" ], "security": [ { "BearerAuth": [ "interviews:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/reschedule_interview_booking": { "post": { "operationId": "reschedule_interview_booking", "summary": "reschedule_interview_booking", "description": "Change the time of an existing interview booking. Re-validates future-time and overlap against other confirmed bookings (excludes self). If duration_minutes is omitted, the existing duration is preserved.", "tags": [ "interview_booking" ], "security": [ { "BearerAuth": [ "interviews:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/cancel_interview_booking": { "post": { "operationId": "cancel_interview_booking", "summary": "cancel_interview_booking", "description": "Cancel an interview booking. Sets status to cancelled and (optionally) appends a reason to the notes field. Already-cancelled bookings are no-ops; already-completed bookings are rejected.", "tags": [ "interview_booking" ], "security": [ { "BearerAuth": [ "interviews:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/search_clips": { "post": { "operationId": "search_clips", "summary": "search_clips", "description": "Search clips in the active workspace, optionally filtered by episode, status (draft/authorised/published), or free-text query (matches title or description). Cursor-paginated, most recently created first.", "tags": [ "clips" ], "security": [ { "BearerAuth": [ "clips:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_clip": { "post": { "operationId": "get_clip", "summary": "get_clip", "description": "Get a single clip by id with full detail: title, description, status, tags, external link, media URL, and transcript snippet.", "tags": [ "clip" ], "security": [ { "BearerAuth": [ "clips:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/create_clip": { "post": { "operationId": "create_clip", "summary": "create_clip", "description": "Create a draft clip under an episode in the active workspace. Required: episode_id, title. Optional: description, tags, external_link, media_url, approach. Returns the new post id.", "tags": [ "clip" ], "security": [ { "BearerAuth": [ "clips:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/update_clip": { "post": { "operationId": "update_clip", "summary": "update_clip", "description": "Update mutable fields on an existing clip. Pass only fields you want to change; null explicitly clears, omitted leaves unchanged. Use schedule_clip for the schedule + status combination.", "tags": [ "clip" ], "security": [ { "BearerAuth": [ "clips:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/schedule_clip": { "post": { "operationId": "schedule_clip", "summary": "schedule_clip", "description": "Schedule a clip to publish at a future timestamp. Sets status to authorised and date_published. The post must currently be in draft or authorised state; published posts must be unpublished via update_clip first.", "tags": [ "clip" ], "security": [ { "BearerAuth": [ "clips:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/delete_clip": { "post": { "operationId": "delete_clip", "summary": "delete_clip", "description": "Delete a clip permanently. Caller must pass confirm: true. Use update_clip with status changes if you want to retract a post without losing the draft.", "tags": [ "clip" ], "security": [ { "BearerAuth": [ "clips:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_email_templates": { "post": { "operationId": "list_email_templates", "summary": "list_email_templates", "description": "List email templates for a show. Use this before creating campaigns so the agent can choose a fixed email template or campaign layout template.", "tags": [ "email_templates" ], "security": [ { "BearerAuth": [ "emails:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_email_template": { "post": { "operationId": "get_email_template", "summary": "get_email_template", "description": "Get a show email template, including its HTML. Use this when the agent needs to understand a template before creating a campaign.", "tags": [ "email_template" ], "security": [ { "BearerAuth": [ "emails:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/create_email_template": { "post": { "operationId": "create_email_template", "summary": "create_email_template", "description": "Create a show email template. Use template_mode=\"campaign_layout\" when the template wraps custom campaign/newsletter content via one or more named user content slots.", "tags": [ "email_template" ], "security": [ { "BearerAuth": [ "emails:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_email_campaigns": { "post": { "operationId": "list_email_campaigns", "summary": "list_email_campaigns", "description": "List email campaigns for a show, including one-off emails and newsletters with their draft/sent status.", "tags": [ "email_campaigns" ], "security": [ { "BearerAuth": [ "emails:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_email_campaign": { "post": { "operationId": "get_email_campaign", "summary": "get_email_campaign", "description": "Get one email campaign for a show. Set include_recipients to inspect recipient send statuses after a send.", "tags": [ "email_campaign" ], "security": [ { "BearerAuth": [ "emails:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/create_email_campaign": { "post": { "operationId": "create_email_campaign", "summary": "create_email_campaign", "description": "Create a draft one-off email or newsletter campaign for a show. Use content for a single user content slot, or content_slots keyed by template slot keys for campaign layout templates. The campaign can target one contact or contact groups; newsletters must target groups.", "tags": [ "email_campaign" ], "security": [ { "BearerAuth": [ "emails:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/update_email_campaign": { "post": { "operationId": "update_email_campaign", "summary": "update_email_campaign", "description": "Update an existing draft email campaign. Use this for \"update the newsletter\", \"update the MainBody/main content\", \"replace the newsletter article\", subject/preheader tweaks, template changes, or audience changes. If the selected template has multiple user content slots and the user did not name the target section, ask which section to update and list the content_slots before calling this tool. Only draft campaigns can be updated.", "tags": [ "email_campaign" ], "security": [ { "BearerAuth": [ "emails:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/send_email_campaign_now": { "post": { "operationId": "send_email_campaign_now", "summary": "send_email_campaign_now", "description": "Send a draft email campaign immediately. This resolves the selected contact/group audience, writes recipient tracking rows, and sends email via the configured provider.", "tags": [ "email_campaign_now" ], "security": [ { "BearerAuth": [ "emails:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_articles": { "post": { "operationId": "list_articles", "summary": "list_articles", "description": "List show-scoped Markdown articles in the active workspace, newest first. Optionally filter by show_id or episode_id. Returns summaries (no body); use get_article for the full Markdown.", "tags": [ "articles" ], "security": [ { "BearerAuth": [ "articles:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_article": { "post": { "operationId": "get_article", "summary": "get_article", "description": "Get a single show-scoped article by id, including its full Markdown body.", "tags": [ "article" ], "security": [ { "BearerAuth": [ "articles:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/create_article": { "post": { "operationId": "create_article", "summary": "create_article", "description": "Create a show-scoped Markdown article in the active workspace. Required: show_id. Optional: title, body (Markdown), episode_id. Returns the new article.", "tags": [ "article" ], "security": [ { "BearerAuth": [ "articles:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/update_article": { "post": { "operationId": "update_article", "summary": "update_article", "description": "Update a show-scoped article in the active workspace. Set title, body (Markdown), or episode_id (null to unlink). Only provided fields change. Returns the updated article.", "tags": [ "article" ], "security": [ { "BearerAuth": [ "articles:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_media_assets": { "post": { "operationId": "list_media_assets", "summary": "list_media_assets", "description": "List image media assets in the workspace media library (uploads and AI-generated), newest first. Use the source field to tell them apart; get the full asset with get_media_asset.", "tags": [ "media_assets" ], "security": [ { "BearerAuth": [ "media:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_entity_media": { "post": { "operationId": "list_entity_media", "summary": "list_entity_media", "description": "List the media attached to a show, episode, or contact (e.g. host/guest photos, a logo) so the user can pick references for generate_image. Returns med_ ids to pass as reference_media_ids.", "tags": [ "entity_media" ], "security": [ { "BearerAuth": [ "media:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_media_asset": { "post": { "operationId": "get_media_asset", "summary": "get_media_asset", "description": "Get a single media asset by its prefixed id (med_), including its public URL and generation prompt/model.", "tags": [ "media_asset" ], "security": [ { "BearerAuth": [ "media:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/generate_image": { "post": { "operationId": "generate_image", "summary": "generate_image", "description": "Generate an AI image for a show (use this for any thumbnail / cover art / artwork / image request — NOT the writing/article path). Runs in the background and saves the image to the workspace media library, attached to the entity in context so it appears on that entity's media: pass attach_to_type + attach_to_id (show | episode | social | contact | group | interview) — e.g. an episode thumbnail attaches to that episode; defaults to the show. **Aspect ratio is controlled ONLY by the aspect_ratio parameter (1:1 | 16:9 | 9:16 | 4:5) — never by words in the prompt; the output is guaranteed to be exactly that ratio. Pick it from intent (YouTube thumbnail → 16:9, Short/Reel → 9:16) without asking.** Optionally pass reference_media_ids (med_ from list_entity_media / list_media_assets) to edit/composite against real workspace images (host/guest photos, a logo); with no references it is pure text-to-image and cannot retain a supplied image. Returns a job_id — the image appears when the job completes; then apply_media_asset can set it as a cover/social image. Required: show_id, prompt. Billed in credits.", "tags": [ "image" ], "security": [ { "BearerAuth": [ "media:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/apply_media_asset": { "post": { "operationId": "apply_media_asset", "summary": "apply_media_asset", "description": "Apply a media asset as a cover or social image. Match the slot to the asset: a 16:9 YouTube thumbnail → episode_youtube_cover / show_youtube_cover; the square (1:1) podcast cover → episode_cover / show_cover; a clip image → clip. Never put a YouTube thumbnail in episode_cover/show_cover (it overwrites the podcast cover). Required: media_id, target (episode_cover|episode_youtube_cover|show_cover|show_youtube_cover|clip), target_id.", "tags": [ "media_asset" ], "security": [ { "BearerAuth": [ "media:write", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/enqueue_transcript_processing": { "post": { "operationId": "enqueue_transcript_processing", "summary": "enqueue_transcript_processing", "description": "Kick off transcript processing for an episode. Reads the episode's audio_url, transcribes it, and writes the transcript + SRT back to the episode. Long-running (minutes); the agent gets back a job_id and should not block on the result.", "tags": [ "transcript_processing" ], "security": [ { "BearerAuth": [ "jobs:trigger", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/enqueue_title_generation": { "post": { "operationId": "enqueue_title_generation", "summary": "enqueue_title_generation", "description": "Kick off LLM-driven episode title generation. The handler reads the episode's transcript / show notes / brand voice and writes suggested titles to episode_titles. Returns a job_id; not blocking.", "tags": [ "title_generation" ], "security": [ { "BearerAuth": [ "jobs:trigger", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/enqueue_chapter_generation": { "post": { "operationId": "enqueue_chapter_generation", "summary": "enqueue_chapter_generation", "description": "Kick off LLM-driven chapter generation for an episode. The handler reads the transcript and writes structured chapter rows to episode_chapters. Returns a job_id; not blocking.", "tags": [ "chapter_generation" ], "security": [ { "BearerAuth": [ "jobs:trigger", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/enqueue_show_notes_generation": { "post": { "operationId": "enqueue_show_notes_generation", "summary": "enqueue_show_notes_generation", "description": "Kick off LLM-driven show notes generation for an episode. The job runs the workspace's stored `show_notes` system-prompt template through `resolvePrompt`, threading the show's `brand_voice` and the episode's transcript into the prompt, and writes the resulting markdown back to `episodes.show_notes`. Use this whenever the user asks to generate, regenerate, or rewrite show notes — DO NOT hand-write the notes from chat context: the user expects the workspace's actual stored show_notes prompt to be applied, not the LLM's improvised version. Returns a job_id; not blocking.", "tags": [ "show_notes_generation" ], "security": [ { "BearerAuth": [ "jobs:trigger", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/enqueue_full_episode_pipeline": { "post": { "operationId": "enqueue_full_episode_pipeline", "summary": "enqueue_full_episode_pipeline", "description": "Kick off the end-to-end episode processing pipeline (transcribe → chunk → notes → titles → chapters → metadata). Pass skip_show_notes: true to run the variant that omits LLM show-notes generation. Returns a job_id; not blocking.", "tags": [ "full_episode_pipeline" ], "security": [ { "BearerAuth": [ "jobs:trigger", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_job_status": { "post": { "operationId": "get_job_status", "summary": "get_job_status", "description": "Look up the current state of a background job by its job_id (the uuid returned by an enqueue_* capability). Use this when the user asks 'is it done?' / 'is the show notes job ready?' / 'what's the status?' after an earlier enqueue. Returns lifecycle status (pending / running / completed / failed) plus optional progress notes the handler surfaces. If you don't have the job_id from an earlier turn in the same conversation, call get_recent_intent first to recover it.", "tags": [ "job_status" ], "security": [ { "BearerAuth": [ "mcp:tools", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_credit_balance": { "post": { "operationId": "get_credit_balance", "summary": "get_credit_balance", "description": "Get the current credit balance for the active workspace.", "tags": [ "credit_balance" ], "security": [ { "BearerAuth": [ "analytics:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_billing_summary": { "post": { "operationId": "get_billing_summary", "summary": "get_billing_summary", "description": "Get a read-only billing summary for the active workspace: credit balance, 30-day grants/charges/expiry, current plan + subscription status, 30-day usage rollups, storage totals, and recent usage. Excludes payment/Stripe details.", "tags": [ "billing_summary" ], "security": [ { "BearerAuth": [ "analytics:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/describe_domain": { "post": { "operationId": "describe_domain", "summary": "describe_domain", "description": "Return the PodMule operating ontology: entity catalog (workspace, show, episode, contact, contact_group, interview_booking, clip, email_template, email_campaign, article, knowledge_page, media_asset, prompt, workflow), relationships, id prefixes, status machines, read/write capability contracts, context-record compatibility, operation context requirements, affordances, common intents, the global (routing/meta/analytics) capability list, and the bulk-capability list. Every callable capability is either mapped to an entity or listed in global_capabilities. Call this once at session start so you can pick the right capability for a question without trial and error. Public metadata — no tenant data, no PII; safe to cache.", "tags": [ "domain" ], "security": [ { "BearerAuth": [ "mcp:tools", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/convert_session_to_workflow": { "post": { "operationId": "convert_session_to_workflow", "summary": "convert_session_to_workflow", "description": "Convert a chat session into a saved workflow. Reads recent successful capability calls for the conversation, emits them as call_capability action steps, and saves the workflow with disabled: true so the user reviews + enables in the workflow editor. Do not call this as the first response to \"make this a workflow\": first review the chat transcript/tool sequence, ask any missing questions, and confirm the reusable workflow definition (trigger/context, runtime inputs, reusable read/search steps, generation contract, writes, and review state). By default only mutating calls (writes) become workflow steps — discovery reads (list_*, search_*, get_*) are filtered as exploration scaffolding (set mutates_only: false to include them). Detects runs of N consecutive same-capability calls (a strong \"for-each\" signal) and surfaces them as loop_candidates so the user can consolidate by hand; native for_each step kind ships in v3. Use parameterise=[\"key1\", \"key2\"] to lift specific argument keys into runtime inputs (replacing the captured value with {{input.key}}). Output flags truncated/reads_excluded/loop_candidates so the caller knows what got dropped or batched. Use this only when the confirmed plan is faithfully represented by the captured trace; otherwise create or edit the workflow from the plan. If compression fails and the saved literal trace would omit required read/generation steps, tell the user and ask whether they accept a literal disabled draft before treating it as the reusable workflow.", "tags": [ "session_to_workflow" ], "security": [ { "BearerAuth": [ "mcp:tools", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/prepare_workflow_definition": { "post": { "operationId": "prepare_workflow_definition", "summary": "prepare_workflow_definition", "description": "Generic Workflow Builder lifecycle step 1: after the user has confirmed any reusable workflow definition, save it as a disabled prepared workflow, run a real dry run using dry_run_inputs, and return proof for user review. Do not call this before the user has confirmed the reusable definition. After this succeeds, show the dry-run output and ask the user to authorize it with authorize_prepared_workflow.", "tags": [ "workflow_definition" ], "security": [ { "BearerAuth": [ "mcp:tools", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/authorize_prepared_workflow": { "post": { "operationId": "authorize_prepared_workflow", "summary": "authorize_prepared_workflow", "description": "Workflow-builder lifecycle step 2: after the user explicitly approves the dry-run output, authorize the prepared disabled workflow for use. Requires workflow_key and the content_hash returned by prepare_workflow_definition. Do not call this until the user has signed off the dry run.", "tags": [ "prepared_workflow" ], "security": [ { "BearerAuth": [ "mcp:tools", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_system_prompts": { "post": { "operationId": "list_system_prompts", "summary": "list_system_prompts", "description": "Return the workspace's stored prompt-template catalog (system_prompts table) — the LLM templates used by generate_show_notes, generate_show_titles, etc. Each row resolves with workspace override > global default. Pass `key` to fetch a single prompt; omit for the full list. These are user-editable generation templates: share, discuss, and refine them freely. Pair with create_system_prompt / update_system_prompt when the user wants to save or change one. NOTE: distinct from the Prompt Library — for reusable, free-form Saved Prompts a user keeps for reuse, use list_prompt_library / get_saved_prompt instead.", "tags": [ "system_prompts" ], "security": [ { "BearerAuth": [ "mcp:tools", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/create_system_prompt": { "post": { "operationId": "create_system_prompt", "summary": "create_system_prompt", "description": "Save a new workspace prompt template under a given key. Use when the user says 'save this as a prompt', 'remember this template', 'make this our default '. The new template is org-scoped — it shadows any global default with the same key. Confirm the key with the user before saving (avoid creating multiple lookalike keys like show_notes_v2_final). Rejects if the key already exists; use update_system_prompt instead.", "tags": [ "system_prompt" ], "security": [ { "BearerAuth": [ "mcp:tools", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/update_system_prompt": { "post": { "operationId": "update_system_prompt", "summary": "update_system_prompt", "description": "Replace the value of an existing workspace prompt template (or shadow a global default by creating the org-scoped row for the first time). Use when the user iterates: 'tighten this prompt', 'rewrite our show_notes template', 'drop the last paragraph'. Confirm the new value with the user before saving — every subsequent generation job will pick it up. Rejects if the key has no existing row (org or global); use create_system_prompt for genuinely new keys. Some keys are RESERVED and cannot be overridden — the agent's integrity-level rules (anti-fabrication; see RULES with overridable: false in src/lib/agents/runtime/rules.ts). Attempting to update those returns INVALID_INPUT.", "tags": [ "system_prompt" ], "security": [ { "BearerAuth": [ "mcp:tools", "mcp:tools" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stripe-style idempotency key. When present, repeat invocations within 24h with the same body return the original response; same key + different body returns 409 IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "X-PodMule-Dry-Run", "in": "header", "required": false, "description": "When set to \"true\", routes the call to the capability's dryRun() method — same scope/precondition checks fire as the real handler, but persistence is skipped. The audit row is tagged result_status=dry_run.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — same Idempotency-Key was used previously with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/list_prompt_library": { "post": { "operationId": "list_prompt_library", "summary": "list_prompt_library", "description": "List the reusable Saved Prompts available to the active workspace from the Prompt Library: PodMule-wide (global) prompts plus this workspace's own. Returns names + descriptions only — call get_saved_prompt for a prompt's full text. These are user-curated reusable prompts, distinct from list_system_prompts (the workspace's generation-template defaults). Personal user-scope prompts are intentionally never returned here.", "tags": [ "prompt_library" ], "security": [ { "BearerAuth": [ "mcp:tools", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/get_saved_prompt": { "post": { "operationId": "get_saved_prompt", "summary": "get_saved_prompt", "description": "Fetch one Saved Prompt from the Prompt Library in full, including its complete prompt text. Use after list_prompt_library to read a prompt you want to reuse. Resolves only prompts the active workspace may use (global or this workspace's own); personal user-scope prompts are not accessible here.", "tags": [ "saved_prompt" ], "security": [ { "BearerAuth": [ "mcp:tools", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/match_contacts": { "post": { "operationId": "match_contacts", "summary": "match_contacts", "description": "Bulk-resolve many contacts in ONE call by a known set of values — instead of looping get_contact N times. Supply filters of {field, values[], mode}: exact (IN, case-sensitive — for ids/emails) or contains (case-insensitive literal substring — for names/company; LIKE metacharacters are treated as literal text). Contains-eligible fields: email, first_name, last_name, company, job_title. Guest-geography filters with UK/US alias expansion belong on search_contacts (country / country_not / city), not here. Combine filters with 'any' (OR, default) or 'all' (AND). detail:'full' adds socials/phone plus batched recent notes (capped at 5/contact) and attached media for every match in one query-set (no N+1). Returns matches (each with matched_by reporting which supplied value hit it), unmatched (supplied values that hit nothing), and truncated. Caps: ≤50 values/filter, ≤5 filters, ≤200 summary rows / ≤50 full rows. Use this for reconciliation against a caller-supplied set — not for large scans (use search_contacts to browse/relevance-rank).", "tags": [ "contacts" ], "security": [ { "BearerAuth": [ "contacts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/match_episodes": { "post": { "operationId": "match_episodes", "summary": "match_episodes", "description": "Bulk-resolve many episodes in ONE call by a known set of values — instead of looping get_episode N times. Supply filters of {field, values[], mode}: exact (IN — for prefixed ids ep_/sh_, status, season, episode) or contains (case-insensitive literal substring — for title, guest_name). Contains-eligible fields: title, guest_name. Combine filters with 'any' (OR, default) or 'all' (AND). Returns matches (with matched_by), unmatched, and truncated. Each row includes guest_contacts — the AUTHORITATIVE contacts linked to the episode (id + name + role). When guest_contacts is non-empty, use those contact ids for any contact/interview lookup (e.g. list_interviews) — do NOT name-match on guest_name, which is only a transcript guess. detail:'full' equals summary (no transcript fan-out) — use get_episode for transcripts/chapters. Caps: ≤50 values/filter, ≤5 filters, ≤200 rows. For reconciliation against a caller-supplied set, not large scans (use search_episodes to browse).", "tags": [ "episodes" ], "security": [ { "BearerAuth": [ "episodes:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/match_articles": { "post": { "operationId": "match_articles", "summary": "match_articles", "description": "Bulk-resolve many articles in ONE call by a known set of values — instead of looping get_article N times. Supply filters of {field, values[], mode}: exact (IN — for prefixed ids art_/sh_/ep_) or contains (case-insensitive literal substring — for title). Contains-eligible fields: title. Combine filters with 'any' (OR, default) or 'all' (AND). detail:'full' returns the article body for every match in one call (no N+1). Returns matches (with matched_by), unmatched, and truncated. Caps: ≤50 values/filter, ≤5 filters, ≤200 summary rows / ≤50 full rows.", "tags": [ "articles" ], "security": [ { "BearerAuth": [ "articles:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/match_clips": { "post": { "operationId": "match_clips", "summary": "match_clips", "description": "Bulk-resolve many clips in ONE call by a known set of values — instead of looping get_clip N times. Supply filters of {field, values[], mode}: exact (IN — for prefixed ids sp_/ep_, status) or contains (case-insensitive literal substring — for title, description). Contains-eligible fields: title, description. Combine filters with 'any' (OR, default) or 'all' (AND). detail:'full' returns tags/external_link/media_url/transcript for every match in one call (no N+1). Returns matches (with matched_by), unmatched, and truncated. Caps: ≤50 values/filter, ≤5 filters, ≤200 summary rows / ≤50 full rows.", "tags": [ "clips" ], "security": [ { "BearerAuth": [ "clips:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/match_interviews": { "post": { "operationId": "match_interviews", "summary": "match_interviews", "description": "Bulk-resolve many interview bookings in ONE call by a known set of values — instead of looping get_interview N times. Supply filters of {field, values[], mode}: exact (IN — for prefixed ids int_/con_/sh_, status). No contains-eligible fields (resolve guest names via match_contacts on the returned contact_id). Combine filters with 'any' (OR, default) or 'all' (AND). Single-table projection — contact/show names are NOT joined; use get_interview or match_contacts/match_shows for names. detail:'full' adds notes + created_at (no N+1). Returns matches (with matched_by), unmatched, and truncated. Caps: ≤50 values/filter, ≤5 filters, ≤200 summary rows / ≤50 full rows.", "tags": [ "interviews" ], "security": [ { "BearerAuth": [ "interviews:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/match_email_campaigns": { "post": { "operationId": "match_email_campaigns", "summary": "match_email_campaigns", "description": "Bulk-resolve many email campaigns in ONE call by a known set of values — instead of looping get_email_campaign N times. Supply filters of {field, values[], mode}: exact (IN — for prefixed ids ec_/sh_/et_, type, status) or contains (case-insensitive literal substring — for title, subject, from_address). Contains-eligible fields: title, subject, from_address. Combine filters with 'any' (OR, default) or 'all' (AND). detail:'full' adds delivery/open/click/unsubscribe counts and tracking flags (no N+1; email bodies are NOT returned — use get_email_campaign). Returns matches (with matched_by), unmatched, and truncated. Caps: ≤50 values/filter, ≤5 filters, ≤200 summary rows / ≤50 full rows.", "tags": [ "email_campaigns" ], "security": [ { "BearerAuth": [ "emails:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/match_knowledge_pages": { "post": { "operationId": "match_knowledge_pages", "summary": "match_knowledge_pages", "description": "Bulk-resolve many Episode Intelligence knowledge pages in ONE call by a known set of values — instead of looping get_knowledge_page N times. Supply filters of {field, values[], mode}: exact (IN — for prefixed ids kp_/sh_/ep_/con_, page_type, status) or contains (case-insensitive literal substring — for title, slug). Contains-eligible fields: title, slug. Combine filters with 'any' (OR, default) or 'all' (AND). detail:'full' is accepted for contract uniformity but equals summary (no body/citation fan-out) — use get_knowledge_page for the full body. Returns matches (with matched_by), unmatched, and truncated. Caps: ≤50 values/filter, ≤5 filters, ≤200 rows. For cross-episode synthesis use search_knowledge.", "tags": [ "knowledge_pages" ], "security": [ { "BearerAuth": [ "transcripts:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } }, "/match_shows": { "post": { "operationId": "match_shows", "summary": "match_shows", "description": "Bulk-resolve many shows in ONE call by a known set of values — instead of looping get_show N times. Supply filters of {field, values[], mode}: exact (IN — for prefixed id sh_ or slug) or contains (case-insensitive literal substring — for name, slug). Contains-eligible fields: name, slug. Combine filters with 'any' (OR, default) or 'all' (AND). detail:'full' adds brand_voice + youtube_cover (no N+1). Returns matches (with matched_by), unmatched, and truncated. Caps: ≤50 values/filter, ≤5 filters, ≤200 summary rows / ≤50 full rows.", "tags": [ "shows" ], "security": [ { "BearerAuth": [ "shows:read", "mcp:tools" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Capability output wrapped in `{ data }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } }, "400": { "description": "Invalid input — Zod validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "401": { "description": "Missing, malformed, or audience-mismatched bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "403": { "description": "Token is valid but lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "404": { "description": "Capability not registered, or referenced resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "429": { "description": "Rate limit exceeded. Retry after the period in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityError" } } } } } } } } }