{
  "openapi": "3.1.0",
  "info": {
    "title": "Podhoc agent API",
    "version": "1.0.1",
    "description": "Owner-scoped Pro API. Agent use requires an owner-approved finite action/credit/expiry grant; MCP enforces it, and grant-bearing REST tokens retain those limits. Rotation preserves spending. Test keys also charge credits: default 2x base; production 3.5x. Read the live quote. Test: 2/min,20/hour,1 concurrent,5 minutes,1 URL,English. Production:30/min,300/hour,5 concurrent. Public HTTPS inputs only; no completion webhooks. Production defaults to public; subscribed owners can request auto_publish=false. Test creation rejects automatic publication; later visibility changes are a separate operation. A test token is not a publication-isolation boundary. Optional max_credits caps a quote; agents must supply it. Idempotency-Key is required for creation and scoped to owner/token. Reuse identical requests after uncertain responses; do not replace keys. Retrying a receipt does not charge again. Poll test at 240s, production at 15s, then retain the ID and resume later."
  },
  "servers": [
    {
      "url": "https://api-ext.podhoc.com"
    },
    {
      "url": "https://api-ext.dev.podhoc.com"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "paths": {
    "/v1/podcasts": {
      "post": {
        "operationId": "create_podcast",
        "description": "Spend the quoted owner credits to create audio. Production defaults public; request auto_publish=false for private subscribed output. Obtain user budget approval first. Reuse the same idempotency_key after an uncertain response; never retry with a new key.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 16,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9_.:-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success or idempotent receipt replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "403": {
            "description": "Plan, delegation, budget or test-token restriction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "404": {
            "description": "Owned resource unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict, quote changed, or podcast not ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "429": {
            "description": "Rate/concurrency limit; resume after the limit window",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "500": {
            "description": "Uncertain server error; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "202": {
            "description": "Durable generation receipt; queue delivery may still be pending",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "urls": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 20,
                    "items": {
                      "type": "string",
                      "minLength": 9,
                      "maxLength": 4096,
                      "pattern": "^https://"
                    }
                  },
                  "language": {
                    "type": "string",
                    "maxLength": 16
                  },
                  "target_duration_minutes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 120
                  },
                  "style": {
                    "type": "string",
                    "default": "deep_dive",
                    "enum": [
                      "deep_dive",
                      "critique",
                      "didactic",
                      "debate",
                      "feynman_technique",
                      "simplified_explanation",
                      "pedagogical_framework",
                      "alchemist_formula",
                      "references_recall"
                    ],
                    "description": "Podcast style. 'references_recall' requires a Creator or Pro plan and returns 403 TIER_FEATURE_BLOCKED otherwise. An unrecognised value returns 400 INVALID_STYLE."
                  },
                  "voice_config": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["voice_count", "voices"],
                    "properties": {
                      "voice_count": {
                        "type": "integer",
                        "enum": [1, 2]
                      },
                      "voices": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": ["speaker1"],
                        "properties": {
                          "speaker1": {
                            "type": "string",
                            "enum": [
                              "Achernar",
                              "Achird",
                              "Algenib",
                              "Algieba",
                              "Alnilam",
                              "Aoede",
                              "Autonoe",
                              "Callirrhoe",
                              "Charon",
                              "Despina",
                              "Enceladus",
                              "Erinome",
                              "Fenrir",
                              "Gacrux",
                              "Iapetus",
                              "Kore",
                              "Laomedeia",
                              "Leda",
                              "Orus",
                              "Puck",
                              "Pulcherrima",
                              "Rasalgethi",
                              "Sadachbia",
                              "Sadaltager",
                              "Schedar",
                              "Sulafat",
                              "Umbriel",
                              "Vindemiatrix",
                              "Zephyr",
                              "Zubenelgenubi"
                            ]
                          },
                          "speaker2": {
                            "type": "string",
                            "enum": [
                              "Achernar",
                              "Achird",
                              "Algenib",
                              "Algieba",
                              "Alnilam",
                              "Aoede",
                              "Autonoe",
                              "Callirrhoe",
                              "Charon",
                              "Despina",
                              "Enceladus",
                              "Erinome",
                              "Fenrir",
                              "Gacrux",
                              "Iapetus",
                              "Kore",
                              "Laomedeia",
                              "Leda",
                              "Orus",
                              "Puck",
                              "Pulcherrima",
                              "Rasalgethi",
                              "Sadachbia",
                              "Sadaltager",
                              "Schedar",
                              "Sulafat",
                              "Umbriel",
                              "Vindemiatrix",
                              "Zephyr",
                              "Zubenelgenubi"
                            ]
                          },
                          "narrator": {
                            "type": "string",
                            "enum": [
                              "Achernar",
                              "Achird",
                              "Algenib",
                              "Algieba",
                              "Alnilam",
                              "Aoede",
                              "Autonoe",
                              "Callirrhoe",
                              "Charon",
                              "Despina",
                              "Enceladus",
                              "Erinome",
                              "Fenrir",
                              "Gacrux",
                              "Iapetus",
                              "Kore",
                              "Laomedeia",
                              "Leda",
                              "Orus",
                              "Puck",
                              "Pulcherrima",
                              "Rasalgethi",
                              "Sadachbia",
                              "Sadaltager",
                              "Schedar",
                              "Sulafat",
                              "Umbriel",
                              "Vindemiatrix",
                              "Zephyr",
                              "Zubenelgenubi"
                            ]
                          }
                        }
                      }
                    }
                  },
                  "tts_model": {
                    "type": "string",
                    "enum": ["gemini-2.5-flash-tts"]
                  },
                  "custom_focus": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "max_credits": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100000
                  },
                  "auto_publish": {
                    "type": "boolean",
                    "default": true,
                    "description": "Production defaults to public. Pro owners may explicitly request false. Test requests remain private; true is rejected."
                  },
                  "source_weights": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    }
                  }
                },
                "required": ["urls"],
                "additionalProperties": false
              }
            }
          }
        }
      },
      "get": {
        "operationId": "list_podcasts",
        "description": "List the agent owner's podcasts (paginated).",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "requested",
                "enqueued",
                "processing",
                "completed",
                "failed"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success or idempotent receipt replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "403": {
            "description": "Plan, delegation, budget or test-token restriction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "404": {
            "description": "Owned resource unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict, quote changed, or podcast not ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "429": {
            "description": "Rate/concurrency limit; resume after the limit window",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "500": {
            "description": "Uncertain server error; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/podcasts/{podcast_id}/status": {
      "get": {
        "operationId": "get_podcast_status",
        "description": "Poll the generation status (and progress %) of a podcast.",
        "parameters": [
          {
            "name": "podcast_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success or idempotent receipt replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "403": {
            "description": "Plan, delegation, budget or test-token restriction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "404": {
            "description": "Owned resource unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict, quote changed, or podcast not ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "429": {
            "description": "Rate/concurrency limit; resume after the limit window",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "500": {
            "description": "Uncertain server error; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/podcasts/{podcast_id}": {
      "get": {
        "operationId": "get_podcast",
        "description": "Get full details for a podcast (status, language, metadata).",
        "parameters": [
          {
            "name": "podcast_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success or idempotent receipt replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "403": {
            "description": "Plan, delegation, budget or test-token restriction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "404": {
            "description": "Owned resource unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict, quote changed, or podcast not ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "429": {
            "description": "Rate/concurrency limit; resume after the limit window",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "500": {
            "description": "Uncertain server error; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "delete_podcast",
        "description": "Delete an owned episode and revoke public access. Only call after explicit user deletion instructions.",
        "parameters": [
          {
            "name": "podcast_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success or idempotent receipt replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "403": {
            "description": "Plan, delegation, budget or test-token restriction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "404": {
            "description": "Owned resource unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict, quote changed, or podcast not ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "429": {
            "description": "Rate/concurrency limit; resume after the limit window",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "500": {
            "description": "Uncertain server error; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/podcasts/{podcast_id}/download": {
      "get": {
        "operationId": "get_podcast_download",
        "description": "Get a presigned download URL for a completed podcast's audio.",
        "parameters": [
          {
            "name": "podcast_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success or idempotent receipt replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "403": {
            "description": "Plan, delegation, budget or test-token restriction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "404": {
            "description": "Owned resource unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict, quote changed, or podcast not ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "429": {
            "description": "Rate/concurrency limit; resume after the limit window",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "500": {
            "description": "Uncertain server error; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/estimate-cost": {
      "get": {
        "operationId": "estimate_credits",
        "description": "Estimate the credit cost of a generation (with the caller's multiplier).",
        "parameters": [
          {
            "name": "duration_minutes",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 120
            }
          },
          {
            "name": "source_count",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20
            }
          },
          {
            "name": "voice_count",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [1, 2]
            }
          },
          {
            "name": "has_custom_weights",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success or idempotent receipt replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "403": {
            "description": "Plan, delegation, budget or test-token restriction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "404": {
            "description": "Owned resource unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict, quote changed, or podcast not ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "429": {
            "description": "Rate/concurrency limit; resume after the limit window",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "500": {
            "description": "Uncertain server error; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/account/credits": {
      "get": {
        "operationId": "get_credit_balance",
        "description": "Get the agent owner's current credit balance and tier.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success or idempotent receipt replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "403": {
            "description": "Plan, delegation, budget or test-token restriction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "404": {
            "description": "Owned resource unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict, quote changed, or podcast not ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "429": {
            "description": "Rate/concurrency limit; resume after the limit window",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "500": {
            "description": "Uncertain server error; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/podcasts/{podcast_id}/visibility": {
      "patch": {
        "operationId": "set_podcast_visibility",
        "description": "Publish or retract an owned completed episode. Publication makes its audio and derived content public and requires separate explicit user intent and rights confirmation. Free output is public; retracting requires an active subscription.",
        "parameters": [
          {
            "name": "podcast_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success or idempotent receipt replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits; no new charge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "403": {
            "description": "Plan, delegation, budget or test-token restriction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "404": {
            "description": "Owned resource unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict, quote changed, or podcast not ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "429": {
            "description": "Rate/concurrency limit; resume after the limit window",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "500": {
            "description": "Uncertain server error; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "503": {
            "description": "Dependency unavailable; preserve creation key and reconcile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["is_public"],
                "properties": {
                  "is_public": {
                    "type": "boolean"
                  },
                  "rights_confirmed": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object"
          },
          "meta": {
            "type": "object"
          },
          "error": {
            "type": "object"
          }
        }
      }
    }
  },
  "x-podhoc-voices": [
    {
      "id": "Achernar",
      "label": "Achernar"
    },
    {
      "id": "Achird",
      "label": "Achird"
    },
    {
      "id": "Algenib",
      "label": "Algenib"
    },
    {
      "id": "Algieba",
      "label": "Algieba"
    },
    {
      "id": "Alnilam",
      "label": "Alnilam"
    },
    {
      "id": "Aoede",
      "label": "Aoede"
    },
    {
      "id": "Autonoe",
      "label": "Autonoe"
    },
    {
      "id": "Callirrhoe",
      "label": "Callirrhoe"
    },
    {
      "id": "Charon",
      "label": "Charon"
    },
    {
      "id": "Despina",
      "label": "Despina"
    },
    {
      "id": "Enceladus",
      "label": "Enceladus"
    },
    {
      "id": "Erinome",
      "label": "Erinome"
    },
    {
      "id": "Fenrir",
      "label": "Fenrir"
    },
    {
      "id": "Gacrux",
      "label": "Gacrux"
    },
    {
      "id": "Iapetus",
      "label": "Iapetus"
    },
    {
      "id": "Kore",
      "label": "Kore"
    },
    {
      "id": "Laomedeia",
      "label": "Laomedeia"
    },
    {
      "id": "Leda",
      "label": "Leda"
    },
    {
      "id": "Orus",
      "label": "Orus"
    },
    {
      "id": "Puck",
      "label": "Puck"
    },
    {
      "id": "Pulcherrima",
      "label": "Pulcherrima"
    },
    {
      "id": "Rasalgethi",
      "label": "Rasalgethi"
    },
    {
      "id": "Sadachbia",
      "label": "Sadachbia"
    },
    {
      "id": "Sadaltager",
      "label": "Sadaltager"
    },
    {
      "id": "Schedar",
      "label": "Schedar"
    },
    {
      "id": "Sulafat",
      "label": "Sulafat"
    },
    {
      "id": "Umbriel",
      "label": "Umbriel"
    },
    {
      "id": "Vindemiatrix",
      "label": "Vindemiatrix"
    },
    {
      "id": "Zephyr",
      "label": "Zephyr"
    },
    {
      "id": "Zubenelgenubi",
      "label": "Zubenelgenubi"
    }
  ]
}