{"openapi":"3.1.0","info":{"title":"Neurvona API","version":"2.0.0","description":"Generate private X drafts and manage your own autopilot. No free AI allowance. $0.20 per writing attempt from API credits. Autopilot uses the same prepaid service credits. Research, transcription, LiveKit media, and promotion controls are included. Human OAuth and payment remain required. The shared credit balance also funds approved X promotion: 2 credits per USD of media, plus 0.40 credits per AI selection. X Money is unnecessary; advertising waits for settled cash backing. MCP: https://neurvona.ai/api/mcp. Quickstart: https://neurvona.ai/developers/docs.","contact":{"url":"https://neurvona.ai/developers/docs","email":"brett@neurvona.com"}},"servers":[{"url":"https://neurvona.ai/api/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"Account"},{"name":"Posts"},{"name":"Autopilot"},{"name":"Boosts"},{"name":"Persona"},{"name":"Email"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An nv_live_ or nv_test_ API key created in the developer console."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Credits":{"type":"object","properties":{"balanceCents":{"type":"integer","description":"Hundredths of a service credit, including purchased pack bonuses. 100 = 1 credit; not a cash balance."},"packs":{"type":"array","items":{"type":"object","properties":{"amountCents":{"type":"integer","description":"Price charged in USD cents."},"creditCents":{"type":"integer","description":"Total credit quantity in hundredths, including bonuses."},"name":{"type":"string"}},"required":["amountCents","creditCents","name"]}},"freeLimit":{"type":"integer"},"freeRemaining":{"type":"integer"},"month":{"type":"string","example":"2026-09"},"postsThisMonth":{"type":"integer"},"chargedCentsThisMonth":{"type":"integer"},"pricePerPostCents":{"type":"integer"}},"required":["balanceCents","packs","freeLimit","freeRemaining","month","postsThisMonth","chargedCentsThisMonth","pricePerPostCents"]},"Account":{"type":"object","properties":{"account":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"xHandle":{"type":["string","null"]},"signInMethods":{"type":"array","items":{"type":"string"}},"autopilotAvailable":{"type":"boolean"}},"required":["id","name","xHandle","signInMethods","autopilotAvailable"]},"credits":{"$ref":"#/components/schemas/Credits"},"keyId":{"type":"string"}},"required":["account","credits","keyId"]},"Autopilot":{"type":"object","properties":{"twinMission":{"type":"object","properties":{"goal":{"type":"string"},"category":{"type":"string","enum":["job","clients","product","funding","reputation","sales","dating","community","custom"]},"revision":{"type":"integer"},"updatedAt":{"type":"integer","description":"Unix milliseconds."}},"required":["goal","category","revision","updatedAt"]},"enabled":{"type":"boolean"},"available":{"type":"boolean"},"connected":{"type":"boolean"},"hasPlan":{"type":"boolean"},"emailVerified":{"type":"boolean"},"timezone":{"type":"string"},"setupUrl":{"type":"string","format":"uri"},"requirements":{"type":"array","items":{"type":"string","enum":["connect_x","verify_email","choose_plan","save_goal"]}},"creditDailyLimitCents":{"type":"integer"},"pricePerCheckCents":{"type":"integer"},"balanceCents":{"type":"integer"},"goal":{"type":["object","null"],"properties":{"mission":{"type":"string"},"brief":{"type":"string"},"facts":{"type":"string"},"topics":{"type":"array","items":{"type":"string"}}},"required":["mission","brief","facts","topics"]},"postsPerDay":{"type":"integer"},"headsUpEmail":{"type":"boolean"},"nextCheckAt":{"type":["string","null"],"format":"date-time"},"postsThisPeriod":{"type":"integer"},"periodLimit":{"type":"integer"},"note":{"type":"string"}},"required":["twinMission","enabled","available","connected","hasPlan","emailVerified","timezone","setupUrl","requirements","creditDailyLimitCents","pricePerCheckCents","balanceCents","goal","postsPerDay","headsUpEmail","nextCheckAt","postsThisPeriod","periodLimit","note"]},"Posts":{"type":"object","properties":{"id":{"type":"string"},"posts":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}},"usage":{"type":"object","properties":{"posts":{"type":"integer"},"freePosts":{"type":"integer"},"chargedCents":{"type":"integer"}},"required":["posts","freePosts","chargedCents"]},"replayed":{"type":"boolean"},"credits":{"type":"object","properties":{"balanceCents":{"type":"integer"},"freeRemaining":{"type":"integer"}},"required":["balanceCents","freeRemaining"]}},"required":["id","posts","usage","replayed","credits"]},"Activity":{"type":"object","properties":{"activity":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"text":{"type":"string"},"url":{"type":["string","null"]},"reason":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","type","text","url","reason","createdAt"]}}},"required":["activity"]},"Boosts":{"type":"object","properties":{"boosts":{"type":"object","properties":{"revision":{"type":"integer"},"settings":{"type":"object","properties":{"mode":{"type":"string","enum":["automatic","review"]},"totalCents":{"type":"integer","minimum":1000,"maximum":100000},"dailyCents":{"type":"integer","minimum":500,"maximum":100000},"perPostCents":{"type":"integer","minimum":500,"maximum":100000},"minAgeHours":{"type":"integer","minimum":1,"maximum":48},"minImpressions":{"type":"integer","minimum":50,"maximum":100000},"minLiftPercent":{"type":"integer","minimum":0,"maximum":500},"scope":{"type":"string","enum":["twin","all"]},"country":{"type":"string","enum":["US","CA","GB","AU","NZ"]},"audience":{"type":"string","maxLength":500},"excludeWords":{"type":"string","maxLength":500},"excludedPostIds":{"type":"array","maxItems":50,"items":{"type":"string","pattern":"^[0-9]{1,25}$"}}},"required":["mode","totalCents","dailyCents","perPostCents","minAgeHours","minImpressions","minLiftPercent","scope","country","audience","excludeWords","excludedPostIds"],"additionalProperties":false},"preview":{"type":["object","null"]},"activity":{"type":"array","items":{"type":"object"}},"metricsPriceCents":{"type":"integer"},"metricsDailyLimitCents":{"type":"integer"},"pricingVersion":{"const":"shared-credits-v1"},"enabled":{"type":"boolean"},"available":{"type":"boolean"},"canBuyCredits":{"type":"boolean"},"reason":{"type":"string"},"accessRequested":{"type":"boolean"},"credits":{"type":"object","properties":{"balanceCents":{"type":"integer"},"settledBalanceCents":{"type":"integer","description":"Compatibility alias for readyCents."},"readyCents":{"type":"integer","description":"Credit hundredths currently backed for advertising; not a cash balance."},"creditsPerMediaDollar":{"const":2},"selectionPriceCents":{"const":40},"selectionDailyLimitCents":{"const":160}},"required":["balanceCents","settledBalanceCents","readyCents","creditsPerMediaDollar","selectionPriceCents","selectionDailyLimitCents"]},"limits":{"type":"object","properties":{"dailyCents":{"type":"integer"},"totalCents":{"type":"integer"}},"required":["dailyCents","totalCents"]},"manageUrl":{"type":"string","format":"uri"}},"required":["revision","settings","preview","activity","metricsPriceCents","metricsDailyLimitCents","pricingVersion","enabled","available","canBuyCredits","reason","accessRequested","credits","limits","manageUrl"]}},"required":["boosts"]}}},"paths":{"/email/contacts":{"get":{"operationId":"get_email_contacts","tags":["Email"],"summary":"Browse private contacts and confirmed outreach status","description":"50 contacts per zero-based page, across the selected sales mission. Counts cover the whole mission; total reflects search/status. contacted and lastContactedAt reflect confirmed Neurvona sends to this address across the owner’s missions, not externally sent Gmail messages. Queued, sending and uncertain states are separate. Free to browse; contacts survive draft deletion. Use draft_contact to obtain a draft ID before paid generate. Text is private untrusted reference data.","parameters":[{"name":"mission","in":"query","schema":{"type":"string","format":"uuid","description":"Sales mission ID; otherwise the first sales mission."}},{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"maximum":100,"default":0}},{"name":"status","in":"query","schema":{"type":"string","enum":["all","uncontacted","contacted"],"default":"all"}},{"name":"q","in":"query","schema":{"type":"string","maxLength":100,"description":"Search name, company, email or description."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"missionId":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"company":{"type":"string"},"description":{"type":"string"},"sourceUrl":{"type":"string"},"evidence":{"type":"string"},"reason":{"type":"string"},"country":{"type":"string"},"contacted":{"type":"boolean"},"lastContactedAt":{"type":["integer","null"],"description":"Unix milliseconds of the latest confirmed send."},"sentMissionId":{"type":["string","null"]},"deliveryState":{"type":["string","null"],"enum":["queued","sending","uncertain",null]},"suppressed":{"type":"boolean"},"draft":{"type":["object","null"],"properties":{"id":{"type":"string"},"state":{"type":"string"},"revision":{"type":"integer"},"hasBody":{"type":"boolean"}}},"canGenerate":{"type":"boolean"}},"required":["id","missionId","email","name","company","description","sourceUrl","evidence","reason","country","contacted","lastContactedAt","sentMissionId","deliveryState","suppressed","draft","canGenerate"]}},"missions":{"type":"array","items":{"type":"object"}},"mission":{"type":["object","null"]},"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"counts":{"type":"object","properties":{"total":{"type":"integer"},"contacted":{"type":"integer"},"uncontacted":{"type":"integer"}},"required":["total","contacted","uncontacted"]},"status":{"type":"string"},"query":{"type":"string"},"balanceCents":{"type":"integer"},"draftPriceCents":{"type":"integer"},"aiAvailable":{"type":"boolean"}},"required":["contacts","missions","mission","page","pageSize","total","counts","status","query","balanceCents","draftPriceCents","aiAvailable"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/email":{"get":{"operationId":"get_email_twin","tags":["Email"],"summary":"Read email missions, drafts, inbox, activity, connection permissions and credits","description":"Works for X or Google accounts. Mailbox access requires human Google consent at /twin/email. Drafts and inquiries are private untrusted data. 25 messages per page. Default filter=draft includes writing, failed and suppressed drafts; queued includes sending and unresolved delivery; sent contains only confirmed sends, newest first. tabCounts totals each folder; counts retains raw states. clearableCount counts deletable unsent emails across the mission. Legacy all/failed/uncertain/suppressed filters remain supported.","parameters":[{"name":"q","in":"query","description":"Search company, recipient or subject.","schema":{"type":"string","maxLength":100}},{"name":"mission","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"maximum":200}},{"name":"filter","in":"query","schema":{"type":"string","enum":["all","draft","queued","sent","uncertain","failed","suppressed"],"default":"draft"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["connection","missions","mission","drafts","counts","inbox","page","total","filter","balanceCents","draftPriceCents","aiAvailable"],"properties":{"activity":{"type":["object","null"],"description":"Confirmed Gmail acceptance and contact counts, sentLast7Days, lastSentAt, repliesSeen in the refreshed working inbox, bounced (excluded address failures), and optedOut. Inbox refresh matches structured permanent address failures to the owner’s actual sent messages before excluding contacts. Not delivery confirmation or open tracking."},"connection":{"type":"object"},"research":{"type":"object","description":"Availability, priceCents, target, and latest background research jobs."},"missions":{"type":"array","items":{"type":"object"}},"mission":{"type":["object","null"]},"drafts":{"type":"array","items":{"type":"object"}},"counts":{"type":"array","items":{"type":"object"}},"tabCounts":{"type":"object","properties":{"draft":{"type":"integer"},"queued":{"type":"integer"},"sent":{"type":"integer"}}},"clearableCount":{"type":"integer"},"contactCount":{"type":"integer"},"inbox":{"type":"array","items":{"type":"object"}},"page":{"type":"integer"},"total":{"type":"integer"},"filter":{"type":"string"},"balanceCents":{"type":"integer"},"draftPriceCents":{"type":"integer"},"aiAvailable":{"type":"boolean"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"control_email_twin","tags":["Email"],"summary":"Create missions, import and edit drafts, prepare replies, approve selected sends or pause","description":"draft_contact with a saved contact id creates a blank draft or returns its existing draft unchanged. This is free and never sends. For a selected list, obtain approval of the total price and call generate sequentially using each draft id/revision with its own stable key. followup takes a confirmed sales draft id and data {revision,afterDays:7|14|30}, prepares one blank threaded follow-up for free, and requires explicit inbox permission. Write/review/approve it separately. Sending cannot precede its date and stops if the thread changes. Free manual drafting and Gmail operations; generate costs 20 prepaid credit cents per attempt and requires a stable Idempotency-Key. Read status first. queue requires explicit owner authorization for exact draft IDs, draft revisions and current mission revision, plus verified Gmail sender and a postal address for sales. Up to 25 contacts/import or individually selected approvals/request; prepare_all creates an expiring revision snapshot of up to 5,000 ready drafts, and queue_all consumes its reviewId after owner confirmation; REST bodies up to 350 KB. prepare_clear snapshots deletable unsent emails across the mission; after owner approval, clear_drafts consumes its reviewId with consent:true, permanently deletes those emails, pauses sending and stops research. No undo. Sent, sending and uncertain messages are protected; contacts and billing metadata remain. cancel requires id and data {revision,consent:true} and permanently deletes one unsent email. Saving a mission pauses its queue. Sending is paced at least 60 seconds apart, at most 50/account/day, and never repeats an uncertain Gmail submission. generate_batch reserves 2,500 credit cents for a background research run targeting 100 sourced emails; the count can be lower if contacts cannot be verified. Started research uses the quoted credits. stop_generation cancels remaining work; unstarted runs are refunded. Never guess addresses or auto-send generated drafts. Approval is not OAuth consent. See /developers/docs#email for the complete action contract.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Required for generate and generate_batch; 8–64 characters and stable across retries.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","oneOf":[{"type":"object","properties":{"action":{"const":"save_mission"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revision":{"type":"integer","minimum":0},"name":{"type":"string","minLength":1,"maxLength":200},"kind":{"enum":["sales","inbox"]},"goal":{"type":"string","maxLength":4000},"fromEmail":{"type":"string","maxLength":254},"senderName":{"type":"string","minLength":1,"maxLength":200},"postalAddress":{"type":"string","maxLength":500},"dailyLimit":{"type":"integer","minimum":1,"maximum":50}},"required":["id","name","kind","goal","fromEmail","senderName","postalAddress","dailyLimit"],"additionalProperties":false}},"required":["action","data"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"import"},"missionId":{"type":"string","format":"uuid"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email","maxLength":254},"name":{"type":"string","maxLength":120},"company":{"type":"string","maxLength":160},"description":{"type":"string","maxLength":240,"description":"Brief factual description of this person or business."},"sourceUrl":{"type":"string","format":"uri","maxLength":1000},"evidence":{"type":"string","minLength":5,"maxLength":2000},"reason":{"type":"string","minLength":5,"maxLength":1200},"country":{"type":"string","maxLength":80},"subject":{"type":"string","minLength":1,"maxLength":200},"body":{"type":"string","minLength":1,"maxLength":10000}},"required":["id","email","sourceUrl","evidence","reason"],"additionalProperties":false},"minItems":1,"maxItems":25}},"required":["action","missionId","data"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"draft_contact"},"id":{"type":"string","format":"uuid"}},"required":["action","id"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"followup"},"id":{"type":"string","format":"uuid"},"data":{"type":"object","properties":{"revision":{"type":"integer","minimum":0},"afterDays":{"type":"integer","enum":[7,14,30],"description":"Prepare one reviewed follow-up at least this many days after the confirmed introduction. Requires inbox access. Does not send or generate text."}},"required":["revision","afterDays"],"additionalProperties":false}},"required":["action","id","data"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"edit"},"id":{"type":"string","format":"uuid"},"data":{"type":"object","properties":{"revision":{"type":"integer","minimum":0},"subject":{"type":"string","minLength":1,"maxLength":200},"body":{"type":"string","minLength":1,"maxLength":10000}},"required":["revision","subject","body"],"additionalProperties":false}},"required":["action","id","data"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"generate"},"id":{"type":"string","format":"uuid"},"data":{"type":"object","properties":{"revision":{"type":"integer","minimum":0},"consent":{"const":true},"maxChargeCents":{"type":"integer","minimum":20}},"required":["revision","consent","maxChargeCents"],"additionalProperties":false}},"required":["action","id","data"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"queue"},"missionId":{"type":"string","format":"uuid"},"data":{"type":"object","properties":{"revision":{"type":"integer","minimum":0},"consent":{"const":true},"selected":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revision":{"type":"integer","minimum":0}},"required":["id","revision"],"additionalProperties":false}}},"required":["revision","consent","selected"],"additionalProperties":false}},"required":["action","missionId","data"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"pause"},"missionId":{"type":"string","format":"uuid"}},"required":["action","missionId"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"cancel"},"id":{"type":"string","format":"uuid"},"data":{"type":"object","properties":{"revision":{"type":"integer","minimum":0},"consent":{"const":true}},"required":["revision","consent"],"additionalProperties":false}},"required":["action","id","data"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"suppress"},"email":{"type":"string","format":"email","maxLength":254}},"required":["action","email"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"sync"}},"required":["action"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"reply"},"missionId":{"type":"string","format":"uuid"},"inboxId":{"type":"string","maxLength":100}},"required":["action","missionId","inboxId"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"check"},"id":{"type":"string","format":"uuid"}},"required":["action","id"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"prepare_all"},"missionId":{"type":"string","format":"uuid"}},"required":["action","missionId"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"prepare_clear"},"missionId":{"type":"string","format":"uuid"}},"required":["action","missionId"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"clear_drafts"},"missionId":{"type":"string","format":"uuid"},"data":{"type":"object","properties":{"reviewId":{"type":"string","format":"uuid"},"consent":{"const":true}},"required":["reviewId","consent"],"additionalProperties":false}},"required":["action","missionId","data"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"queue_all"},"missionId":{"type":"string","format":"uuid"},"data":{"type":"object","properties":{"reviewId":{"type":"string","format":"uuid"},"consent":{"const":true}},"required":["reviewId","consent"],"additionalProperties":false}},"required":["action","missionId","data"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"generate_batch"},"missionId":{"type":"string","format":"uuid"},"data":{"type":"object","properties":{"revision":{"type":"integer","minimum":0},"audience":{"type":"string","minLength":10,"maxLength":500},"count":{"type":"integer","minimum":1,"maximum":100,"default":100,"description":"Number of contacts and tailored emails to target. Costs 25 hundredths of a credit per target, with a 500-hundredth minimum."},"consent":{"const":true},"maxChargeCents":{"type":"integer","minimum":500}},"required":["revision","audience","consent","maxChargeCents"],"additionalProperties":false}},"required":["action","missionId","data"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"stop_generation"},"id":{"type":"string","pattern":"^paid_[a-f0-9]{40}$"}},"required":["action","id"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/token":{"get":{"operationId":"get_token_market","tags":["Account"],"security":[],"summary":"Read NEURVONA price, exact mint, bonus and checkout availability","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"mint":{"type":"string"},"symbol":{"type":"string"},"priceUsd":{"type":["string","null"]},"checkedAt":{"type":["integer","null"]},"source":{"type":"string"},"marketUrl":{"type":"string"},"tokenUrl":{"type":"string"},"available":{"type":"boolean"},"reason":{"type":"string"},"bonusPercent":{"type":"integer"},"liquidityUsd":{"type":"number"}},"required":["mint","symbol","priceUsd","checkedAt","source","marketUrl","tokenUrl","available","reason","bonusPercent","liquidityUsd"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits/token":{"post":{"operationId":"create_token_checkout","tags":["Account"],"summary":"Quote a prepaid NEURVONA credit purchase","description":"COMING SOON: new quotes are disabled (503 token_unavailable). When enabled, creates an owner-scoped quote; does not send funds. 20% extra service credits on top of pack bonuses. Price locked for 5 minutes. Same key/input returns the saved quote, even after expiry. Require approval of the exact token amount before signing. Wallet network/creation fees are separate. Limits: 20 quotes/account/hour, $100/account and $500/global per rolling day, including unexpired quotes. Quotes pause below $5,000 pool liquidity or above 2% of liquidity per payment.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountCents":{"type":"integer","enum":[1000,2500,5000,10000]}},"required":["amountCents"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payment":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["pending","paid","expired"]},"amountCents":{"type":"integer"},"creditCents":{"type":"integer"},"tokenAmount":{"type":"string","description":"Decimal token quantity, never a floating-point amount."},"tokenUnits":{"type":"string","description":"Integer base units (6 decimals)."},"priceUsd":{"type":"string"},"recipient":{"type":"string"},"destination":{"type":"string"},"reference":{"type":"string"},"mint":{"type":"string"},"decimals":{"type":"integer"},"expiresAt":{"type":"integer"},"createdAt":{"type":"integer"},"signature":{"type":["string","null"]},"checkoutUrl":{"type":"string"},"payUrl":{"type":"string"}},"required":["id","state","amountCents","creditCents","tokenAmount","tokenUnits","priceUsd","recipient","destination","reference","mint","decimals","expiresAt","createdAt","signature","checkoutUrl","payUrl"]}},"required":["payment"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits/token/{id}":{"get":{"operationId":"get_token_checkout","tags":["Account"],"summary":"Read your saved token quote and confirmation state","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^ntp_[a-f0-9]{32}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payment":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["pending","paid","expired"]},"amountCents":{"type":"integer"},"creditCents":{"type":"integer"},"tokenAmount":{"type":"string","description":"Decimal token quantity, never a floating-point amount."},"tokenUnits":{"type":"string","description":"Integer base units (6 decimals)."},"priceUsd":{"type":"string"},"recipient":{"type":"string"},"destination":{"type":"string"},"reference":{"type":"string"},"mint":{"type":"string"},"decimals":{"type":"integer"},"expiresAt":{"type":"integer"},"createdAt":{"type":"integer"},"signature":{"type":["string","null"]},"checkoutUrl":{"type":"string"},"payUrl":{"type":"string"}},"required":["id","state","amountCents","creditCents","tokenAmount","tokenUnits","priceUsd","recipient","destination","reference","mint","decimals","expiresAt","createdAt","signature","checkoutUrl","payUrl"]}},"required":["payment"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits/token/{id}/transaction":{"post":{"operationId":"build_token_transaction","tags":["Account"],"summary":"Build an unsigned Solana mainnet Token-2022 transaction","description":"COMING SOON: transaction creation is disabled (503 token_unavailable). When enabled, returns base64 transaction bytes. Never send private keys to Neurvona. Requires owner approval and a funded wallet to sign/send externally. Sender pays all network and associated-account creation fees. Forbids the receiving wallet paying itself. Quotes with fewer than 30 seconds remaining cannot build another transaction.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^ntp_[a-f0-9]{32}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"}},"required":["account"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"transaction":{"type":"string"},"message":{"type":"string"},"expiresAt":{"type":"integer"}},"required":["transaction","message","expiresAt"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits/token/{id}/verify":{"post":{"operationId":"verify_token_checkout","tags":["Account"],"summary":"Verify a finalized payment and issue credits exactly once","description":"Send {} to find payment by reference, or an optional signature. Never trusts the caller’s claimed payment status. Checks mainnet, finalized execution, exact mint, program, transfer amount, recipient, net amount received, reference, and quote deadline. Pending means not verified, not necessarily unpaid. Poll at most every 15 seconds. A timely payment can be fulfilled after quote expiry. Old late/wrong transfers require support; no automatic refunds or repeat payments.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^ntp_[a-f0-9]{32}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"signature":{"type":"string","pattern":"^[1-9A-HJ-NP-Za-km-z]{80,90}$"}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payment":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["pending","paid","expired"]},"amountCents":{"type":"integer"},"creditCents":{"type":"integer"},"tokenAmount":{"type":"string","description":"Decimal token quantity, never a floating-point amount."},"tokenUnits":{"type":"string","description":"Integer base units (6 decimals)."},"priceUsd":{"type":"string"},"recipient":{"type":"string"},"destination":{"type":"string"},"reference":{"type":"string"},"mint":{"type":"string"},"decimals":{"type":"integer"},"expiresAt":{"type":"integer"},"createdAt":{"type":"integer"},"signature":{"type":["string","null"]},"checkoutUrl":{"type":"string"},"payUrl":{"type":"string"}},"required":["id","state","amountCents","creditCents","tokenAmount","tokenUnits","priceUsd","recipient","destination","reference","mint","decimals","expiresAt","createdAt","signature","checkoutUrl","payUrl"]}},"required":["payment"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"operationId":"get_account","tags":["Account"],"summary":"Read your account and API credit balance","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/posts":{"post":{"operationId":"generate_posts","tags":["Posts"],"summary":"Generate private X drafts","description":"Nothing is published. Credits are reserved before provider dispatch. Unusable output or provider failures can still consume credits. An Idempotency-Key is strongly recommended. Replaying the same key and normalized input returns the saved result without a new charge.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"goal":{"type":"string","minLength":3,"maxLength":500},"topic":{"type":"string","maxLength":500,"description":"Optional focus for this draft. Does not verify personal claims or change the shared mission."},"voice":{"type":"string","maxLength":500},"topics":{"type":"array","maxItems":5,"items":{"type":"string","minLength":1,"maxLength":60}},"facts":{"type":"string","maxLength":2000},"count":{"type":"integer","minimum":1,"maximum":5,"default":1},"useMyProfile":{"type":"boolean"}},"required":["goal"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Posts"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mission":{"get":{"operationId":"get_twin_mission","tags":["Twin"],"summary":"Read the owner’s shared twin mission","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"mission":{"type":"object","properties":{"goal":{"type":"string"},"category":{"type":"string","enum":["job","clients","product","funding","reputation","sales","dating","community","custom"]},"revision":{"type":"integer"},"updatedAt":{"type":"integer","description":"Unix milliseconds."}},"required":["goal","category","revision","updatedAt"]}},"required":["mission"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update_twin_mission","tags":["Twin"],"summary":"Save one mission across all enabled services","description":"Free. Works before any service is connected. Read the revision first; zero creates a first mission. Changing the mission pauses accounts, invalidates queued approvals, and preserves per-service limits. Work already dispatched may finish. Never connects accounts, enables autopilot, starts providers, or spends credits.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"goal":{"type":"string","minLength":3,"maxLength":2000},"category":{"type":"string","enum":["job","clients","product","funding","reputation","sales","dating","community","custom"],"default":"custom"},"revision":{"type":"integer","minimum":0}},"required":["goal","revision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"mission":{"type":"object","properties":{"goal":{"type":"string"},"category":{"type":"string","enum":["job","clients","product","funding","reputation","sales","dating","community","custom"]},"revision":{"type":"integer"},"updatedAt":{"type":"integer","description":"Unix milliseconds."}},"required":["goal","category","revision","updatedAt"]}},"required":["mission"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/autopilot":{"get":{"operationId":"get_autopilot","tags":["Autopilot"],"summary":"Read autopilot status and setup requirements","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"autopilot":{"$ref":"#/components/schemas/Autopilot"}},"required":["autopilot"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update_autopilot","tags":["Autopilot"],"summary":"Update X writing notes, topics, pace, or timezone","description":"The owner’s shared mission is read from /mission. Once set, conflicting mission/brief fields return 409; update /mission to change the shared goal. If already running, keeps autopilot running under its existing consent. A paused autopilot stays paused. Send topics: [] to disable reposts and quote comments.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mission":{"type":"string","enum":["job","clients","product","funding","reputation","sales","dating","community","custom"]},"brief":{"type":"string","maxLength":2000},"facts":{"type":"string","maxLength":3000},"topics":{"type":"array","maxItems":5,"items":{"type":"string","minLength":1,"maxLength":60}},"postsPerDay":{"type":"integer","minimum":1,"maximum":3},"creditDailyLimitCents":{"type":"integer","minimum":0,"maximum":10000,"description":"Maximum service-credit spend in a rolling 24 hours. Each check costs 60 cents."},"headsUpEmail":{"type":"boolean"},"timezone":{"type":"string","maxLength":80,"description":"IANA timezone, for example America/Los_Angeles."}},"required":[],"additionalProperties":false,"minProperties":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"autopilot":{"$ref":"#/components/schemas/Autopilot"}},"required":["autopilot"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/autopilot/pause":{"post":{"operationId":"pause_autopilot","tags":["Autopilot"],"summary":"Pause new autopilot posts","description":"An action already sent to X may finish. Does not cancel the subscription or pause boosts.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"autopilot":{"$ref":"#/components/schemas/Autopilot"}},"required":["autopilot"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/autopilot/resume":{"post":{"operationId":"resume_autopilot","tags":["Autopilot"],"summary":"Resume automatic posting with consent","description":"Requires X posting access, funded service credits, and saved settings. Email is required only when the optional review email is enabled. Only call with the account owner’s explicit authorization to publish.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"consent":{"type":"boolean","const":true}},"required":["consent"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"autopilot":{"$ref":"#/components/schemas/Autopilot"}},"required":["autopilot"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/activity":{"get":{"operationId":"get_activity","tags":["Autopilot"],"summary":"Read recent autopilot activity","description":"Newest first, up to 30 recent items. No pagination.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":30,"default":20}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Activity"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/persona/photo":{"get":{"operationId":"get_persona_photo","tags":["Persona"],"summary":"Read your private twin photo or its metadata","description":"Returns JPEG bytes by default, or metadata with format=json. No custom image returns 404 for bytes and a null URL for metadata.","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json"]}}],"responses":{"200":{"description":"Photo bytes or metadata","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"object","properties":{"url":{"type":["string","null"],"description":"Private photo URL, requiring the same API key. Null when using the X/default photo."},"revision":{"type":["string","null"]},"available":{"type":"boolean"}},"required":["url","revision","available"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No custom photo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Image exceeds 256 KB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send image/jpeg","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"set_persona_photo","tags":["Persona"],"summary":"Set your twin’s profile photo","description":"Raw square JPEG, 32–512 pixels per side, up to 256 KB. Metadata is stripped. No multipart or base64 JSON. No credits charged. Does not change your X profile. Up to 30 photo mutations/account/hour. Read metadata after an uncertain response.","parameters":[{"name":"If-Match","in":"header","required":false,"description":"Revision from photo metadata, or none before the first upload. Stale revisions return 409.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":["string","null"],"description":"Private photo URL, requiring the same API key. Null when using the X/default photo."},"revision":{"type":["string","null"]},"available":{"type":"boolean"}},"required":["url","revision","available"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No custom photo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Image exceeds 256 KB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send image/jpeg","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"remove_persona_photo","tags":["Persona"],"summary":"Return to your X/default profile photo","parameters":[{"name":"If-Match","in":"header","required":false,"description":"Revision from photo metadata, or none before the first upload. Stale revisions return 409.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":["string","null"],"description":"Private photo URL, requiring the same API key. Null when using the X/default photo."},"revision":{"type":["string","null"]},"available":{"type":"boolean"}},"required":["url","revision","available"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No custom photo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Image exceeds 256 KB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send image/jpeg","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/persona/sources":{"get":{"operationId":"get_persona_sources","tags":["Persona"],"summary":"Read your private persona sources","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":120},"kind":{"type":"string","enum":["note","file","linkedin","facebook","instagram","gmail","google","drive","calendar","contacts","youtube","tasks","research","transcript"]},"url":{"type":"string","maxLength":500,"default":""},"content":{"type":"string","minLength":1,"maxLength":12000},"enabled":{"type":"boolean","default":false,"description":"Explicit approval to use the text in writing. Gmail is style only."},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"}},"required":["id","title","kind","url","content","enabled","createdAt","updatedAt"]}}},"required":["sources"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"save_persona_source","tags":["Persona"],"summary":"Create or update a source","description":"An owner-scoped UUID makes retries safe. Up to 20 sources. New sources are disabled by default. Approved sources inform future writing; Gmail samples provide style only. Original files are not stored: send extracted text.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":120},"kind":{"type":"string","enum":["note","file","linkedin","facebook","instagram","gmail","google","drive","calendar","contacts","youtube","tasks","research","transcript"]},"url":{"type":"string","maxLength":500,"default":""},"content":{"type":"string","minLength":1,"maxLength":12000},"enabled":{"type":"boolean","default":false,"description":"Explicit approval to use the text in writing. Gmail is style only."}},"required":["id","title","kind","content"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":120},"kind":{"type":"string","enum":["note","file","linkedin","facebook","instagram","gmail","google","drive","calendar","contacts","youtube","tasks","research","transcript"]},"url":{"type":"string","maxLength":500,"default":""},"content":{"type":"string","minLength":1,"maxLength":12000},"enabled":{"type":"boolean","default":false,"description":"Explicit approval to use the text in writing. Gmail is style only."},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"}},"required":["id","title","kind","url","content","enabled","createdAt","updatedAt"]}},"required":["source"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"remove_persona_source","tags":["Persona"],"summary":"Remove a source from future writing","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean"}},"required":["removed"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/persona/connections":{"get":{"operationId":"get_persona_connections","tags":["Persona"],"summary":"List imported service connections and available scopes","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"connections":{"type":"array","items":{"type":"object"}},"connectUrl":{"type":"string"}},"required":["connections","connectUrl"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"update_persona_connection","tags":["Persona"],"summary":"Refresh an authorized import or disconnect a service","description":"OAuth consent must be completed by the owner in the console. Refreshed imports start disabled.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["google","linkedin","facebook","instagram"]},"action":{"type":"string","enum":["refresh","disconnect"]}},"required":["provider","action"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"connections":{"type":"array","items":{"type":"object"}},"connectUrl":{"type":"string"}},"required":["connections","connectUrl"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/persona/capabilities":{"get":{"operationId":"get_persona_capabilities","tags":["Persona"],"summary":"Read availability, current prepaid prices, and limits","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"label":{"type":"string"},"limit":{"type":"string"},"available":{"type":"boolean"},"priceCents":{"type":["integer","null"]},"maxSeconds":{"type":"integer"},"inputFormat":{"type":["string","null"],"description":"pcm16-wav means mono 16 kHz, 16-bit PCM WAV, at most 600 seconds, for transcription."},"reason":{"type":"string"},"provider":{"type":"string"},"voice":{"type":["string","null"],"description":"Speech voice ID; defaults to eve (Grok Eve)."},"representation":{"type":["string","null"]}},"required":["kind","label","limit","available","priceCents","maxSeconds","inputFormat","reason","provider","voice","representation"]}}},"required":["services"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/persona/voice":{"get":{"operationId":"get_persona_voice","tags":["Persona"],"summary":"Read your saved voice and setup price","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"voice":{"type":["object","null"],"properties":{"id":{"type":"string"},"state":{"type":"string","enum":["creating","ready","uncertain","failed","deleting","deleted"]},"chargedCents":{"type":"integer"},"durationSeconds":{"type":"number"},"note":{"type":"string"},"createdAt":{"type":"integer"}}},"setup":{"type":"object","properties":{"available":{"type":"boolean"},"priceCents":{"type":["integer","null"]},"minSeconds":{"type":"integer"},"maxSeconds":{"type":"integer"},"consentVersion":{"type":"string"}},"required":["available","priceCents","minSeconds","maxSeconds","consentVersion"]}},"required":["voice","setup"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_persona_voice","tags":["Persona"],"summary":"Create your personal voice from your own recording","description":"Send canonical 44-byte-header mono 24 kHz 16-bit PCM WAV, 10–60 seconds, at most 2,880,044 bytes. Explicit owner consent required. This prepaid setup is separate from call charges. Audio goes to Cartesia; Neurvona stores metadata only. Inspect voice.state; do not repeat uncertain setup with a new key. One saved voice per account.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}},{"name":"voiceConsent","in":"query","required":true,"schema":{"type":"boolean","const":true}},{"name":"maxChargeCents","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":100000}}],"requestBody":{"required":true,"content":{"audio/wav":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"voice":{"type":"object"},"replayed":{"type":"boolean"}},"required":["voice","replayed"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"remove_persona_voice","tags":["Persona"],"summary":"Remove your saved voice from future calls and request provider deletion","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","pattern":"^paid_[a-f0-9]{40}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/persona/jobs":{"get":{"operationId":"list_persona_jobs","tags":["Persona"],"summary":"List the 30 newest owner-scoped requests","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"jobs":{"type":"array","items":{"type":"object","properties":{"broadcast":{"type":"object","properties":{"state":{"type":"string","enum":["connecting","sending","ended","failed"]},"updatedAt":{"type":"integer","description":"Unix milliseconds. Sending confirms RTMPS delivery, not a public X broadcast."}},"required":["state","updatedAt"]},"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string","enum":["starting","running","complete","failed","uncertain","stopping","expired"]},"chargedCents":{"type":"integer"},"note":{"type":"string"},"expiresAt":{"type":"integer","description":"Unix milliseconds."},"createdAt":{"type":"integer"}},"required":["id","kind","state","chargedCents","note","expiresAt","createdAt"]}}},"required":["jobs"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_persona_job","tags":["Persona"],"summary":"Research the owner or start prepaid LiveKit media","description":"Read capabilities first. No provider starts without credits and an approved price. consent:true authorizes the shown charge. Return may be running or uncertain: inspect state. Reuse the same key and exact input after a lost response. Research results start disabled. Only one live call per owner; another new request returns 409 active_call without charging. Retrieve the active job to rejoin with a fresh token. Get microphone permission before creating a paid call. Video kinds require useXPhoto:true and a connected X profile photo. First-time avatar creation is included in the quoted price and precedes the conversation timer. Each owner uses their own saved avatar; no stock-avatar fallback. A rejected avatar setup can return a failed job with chargedCents:0; inspect state and note. Shared capacity is reserved before charging. A 409 capacity_unavailable means busy; 503 capacity_unavailable means the provider capacity check failed. Neither response creates a job or charges credits. Retry the same key and input later, or offer voice without automatically purchasing it. x_live requires an X Producer RTMPS URL with its secret key and broadcastConsent:true. The owner must create the broadcast in X; Neurvona does not publish it via ordinary X OAuth. The owner microphone is included. Poll job.broadcast.state for delivery status; sending does not confirm a public broadcast. Optional script is an opening line. Stream failures stop the paid room; X comments are not read automatically. Offline voice/video needs a script of 1–1000 characters and no owner connection or microphone. Poll until complete with downloadPath, then authenticate the binary download. Video is 720p H.264/AAC MP4; voice is MP3. Files expire after 30 days and are never posted automatically.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["research","voice","video","live_voice","live_video","x_live"]},"maxChargeCents":{"type":"integer","minimum":1,"maximum":100000},"consent":{"type":"boolean","const":true},"useXPhoto":{"type":"boolean","const":true,"description":"Required for video, live_video, and x_live: owner permission to send their connected X profile photo to Anam and create/reuse their personal avatar."},"voiceMode":{"type":"string","enum":["personal","default"],"description":"Personal requires your saved voice. Video always requires personal. Default selects Grok Eve for audio only. Omitted uses your saved voice if available, otherwise Eve for audio only."},"script":{"type":"string","maxLength":1000,"description":"Required for voice and video recordings. Optional spoken opening for x_live, after the AI disclosure."},"identityHint":{"type":"string","maxLength":200},"streamUrl":{"type":"string","maxLength":1400,"description":"x_live only: X Producer RTMPS URL including stream key. Treat as a secret."},"broadcastConsent":{"type":"boolean","const":true,"description":"Required for x_live: owner authorizes their AI video and microphone audio to be streamed to X."}},"required":["kind","maxChargeCents","consent"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"broadcast":{"type":"object","properties":{"state":{"type":"string","enum":["connecting","sending","ended","failed"]},"updatedAt":{"type":"integer","description":"Unix milliseconds. Sending confirms RTMPS delivery, not a public X broadcast."}},"required":["state","updatedAt"]},"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string","enum":["starting","running","complete","failed","uncertain","stopping","expired"]},"chargedCents":{"type":"integer"},"note":{"type":"string"},"expiresAt":{"type":"integer","description":"Unix milliseconds."},"createdAt":{"type":"integer"},"result":{"type":["object","null"],"properties":{"sourceId":{"type":"string","format":"uuid"},"text":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"}},"required":["title","url"]}},"truncated":{"type":"boolean"}}},"connection":{"type":"object","properties":{"serverUrl":{"type":"string"},"token":{"type":"string"},"expiresAt":{"type":"integer"},"room":{"type":"string"}},"required":["serverUrl","token","expiresAt","room"]},"downloadPath":{"type":"string","description":"Authenticated download path, present only while a completed recording is retained."},"downloadExpiresAt":{"type":"integer","description":"Download deadline in Unix milliseconds; 30 days after creation."}},"required":["id","kind","state","chargedCents","note","expiresAt","createdAt"]},"replayed":{"type":"boolean"}},"required":["job","replayed"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/persona/jobs/{id}":{"get":{"operationId":"get_persona_job","tags":["Persona"],"summary":"Read a result or get a short-lived owner LiveKit token","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^paid_[a-f0-9]{40}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"broadcast":{"type":"object","properties":{"state":{"type":"string","enum":["connecting","sending","ended","failed"]},"updatedAt":{"type":"integer","description":"Unix milliseconds. Sending confirms RTMPS delivery, not a public X broadcast."}},"required":["state","updatedAt"]},"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string","enum":["starting","running","complete","failed","uncertain","stopping","expired"]},"chargedCents":{"type":"integer"},"note":{"type":"string"},"expiresAt":{"type":"integer","description":"Unix milliseconds."},"createdAt":{"type":"integer"},"result":{"type":["object","null"],"properties":{"sourceId":{"type":"string","format":"uuid"},"text":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"}},"required":["title","url"]}},"truncated":{"type":"boolean"}}},"connection":{"type":"object","properties":{"serverUrl":{"type":"string"},"token":{"type":"string"},"expiresAt":{"type":"integer"},"room":{"type":"string"}},"required":["serverUrl","token","expiresAt","room"]},"downloadPath":{"type":"string","description":"Authenticated download path, present only while a completed recording is retained."},"downloadExpiresAt":{"type":"integer","description":"Download deadline in Unix milliseconds; 30 days after creation."}},"required":["id","kind","state","chargedCents","note","expiresAt","createdAt"]}},"required":["job"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"stop_persona_job","tags":["Persona"],"summary":"Stop a live session or recording","description":"Does not refund work already started. Transcription and research cannot be canceled after submission.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^paid_[a-f0-9]{40}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"broadcast":{"type":"object","properties":{"state":{"type":"string","enum":["connecting","sending","ended","failed"]},"updatedAt":{"type":"integer","description":"Unix milliseconds. Sending confirms RTMPS delivery, not a public X broadcast."}},"required":["state","updatedAt"]},"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string","enum":["starting","running","complete","failed","uncertain","stopping","expired"]},"chargedCents":{"type":"integer"},"note":{"type":"string"},"expiresAt":{"type":"integer","description":"Unix milliseconds."},"createdAt":{"type":"integer"},"result":{"type":["object","null"],"properties":{"sourceId":{"type":"string","format":"uuid"},"text":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"}},"required":["title","url"]}},"truncated":{"type":"boolean"}}},"connection":{"type":"object","properties":{"serverUrl":{"type":"string"},"token":{"type":"string"},"expiresAt":{"type":"integer"},"room":{"type":"string"}},"required":["serverUrl","token","expiresAt","room"]},"downloadPath":{"type":"string","description":"Authenticated download path, present only while a completed recording is retained."},"downloadExpiresAt":{"type":"integer","description":"Download deadline in Unix milliseconds; 30 days after creation."}},"required":["id","kind","state","chargedCents","note","expiresAt","createdAt"]}},"required":["job"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/persona/jobs/{id}/file":{"get":{"operationId":"download_persona_recording","tags":["Persona"],"summary":"Download or preview your private completed MP3 or MP4","description":"Recordings expire 30 days after job creation. Owner API key required on every request. No public URLs. Only complete jobs expose downloadPath. Supports one byte range for playback and resume.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^paid_[a-f0-9]{40}$"}},{"name":"inline","in":"query","schema":{"type":"string","enum":["1"]},"description":"Use inline Content-Disposition for playback. Authentication still required."},{"name":"Range","in":"header","schema":{"type":"string"},"description":"A single byte range, e.g. bytes=0-1023 or bytes=-1024."}],"responses":{"200":{"description":"Recording bytes","content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"video/mp4":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"Partial recording bytes; Content-Range and Content-Length describe the response."},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not owned, not ready, missing, or expired."},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"416":{"description":"Invalid or unsatisfiable byte range; Content-Range includes the full size."},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"head":{"operationId":"head_persona_recording","tags":["Persona"],"summary":"Read private recording type and size without downloading","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^paid_[a-f0-9]{40}$"}}],"responses":{"200":{"description":"Content-Type, Content-Length, Content-Disposition, and Accept-Ranges headers; no body."},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not owned, not ready, missing, or expired."},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/persona/transcriptions":{"post":{"operationId":"transcribe_persona_media","tags":["Persona"],"summary":"Upload raw audio/video bytes and save a reviewable transcript","description":"Read capabilities inputFormat first: pcm16-wav requires mono 16 kHz, 16-bit PCM WAV, at most 600 seconds. The Neurvona browser clips and prepares audio locally; raw clients must prepare it themselves. Invalid audio fails before charging. Up to 25 MB. The optional AssemblyAI adapter accepts other listed audio/video formats and clips the first ten minutes. Send bytes directly, not multipart or JSON. Reuse the same key and bytes after a lost response; uncertain provider work never resends automatically. Poll the returned job. Transcripts start disabled.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}},{"name":"maxChargeCents","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":100000}},{"name":"consent","in":"query","required":true,"schema":{"type":"boolean","const":true}},{"name":"title","in":"query","schema":{"type":"string","maxLength":120}}],"requestBody":{"required":true,"content":{"video/mp4":{"schema":{"type":"string","format":"binary"}},"video/quicktime":{"schema":{"type":"string","format":"binary"}},"video/webm":{"schema":{"type":"string","format":"binary"}},"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/mp4":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}},"audio/x-wav":{"schema":{"type":"string","format":"binary"}},"audio/webm":{"schema":{"type":"string","format":"binary"}},"audio/ogg":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"broadcast":{"type":"object","properties":{"state":{"type":"string","enum":["connecting","sending","ended","failed"]},"updatedAt":{"type":"integer","description":"Unix milliseconds. Sending confirms RTMPS delivery, not a public X broadcast."}},"required":["state","updatedAt"]},"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string","enum":["starting","running","complete","failed","uncertain","stopping","expired"]},"chargedCents":{"type":"integer"},"note":{"type":"string"},"expiresAt":{"type":"integer","description":"Unix milliseconds."},"createdAt":{"type":"integer"},"result":{"type":["object","null"],"properties":{"sourceId":{"type":"string","format":"uuid"},"text":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"}},"required":["title","url"]}},"truncated":{"type":"boolean"}}},"connection":{"type":"object","properties":{"serverUrl":{"type":"string"},"token":{"type":"string"},"expiresAt":{"type":"integer"},"room":{"type":"string"}},"required":["serverUrl","token","expiresAt","room"]},"downloadPath":{"type":"string","description":"Authenticated download path, present only while a completed recording is retained."},"downloadExpiresAt":{"type":"integer","description":"Download deadline in Unix milliseconds; 30 days after creation."}},"required":["id","kind","state","chargedCents","note","expiresAt","createdAt"]},"replayed":{"type":"boolean"}},"required":["job","replayed"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/boosts":{"get":{"operationId":"get_boosts","tags":["Boosts"],"summary":"Read boost access, credits, and spending limits","description":"Read settings, preview, activity, revision, approval, and shared Neurvona credits. Limits are hundredths of credits, including AI checks. Send pricingVersion:shared-credits-v1 with each preview, enable or approve action.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Boosts"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"control_boosts","tags":["Boosts"],"summary":"Save limits, preview, enable, approve, pause, or request access","description":"Explicit consent required for paid actions. AI selection costs 40 credit cents, capped at 160 per rolling 24 hours. Media costs 2 credits per USD, including management. Both use the shared balance and saved credit limits. Paid actions require pricingVersion:shared-credits-v1. X approval and settled USD backing are required for advertising. A saved revision fences concurrent changes. Provider connections and purchases stay in the console.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"action":{"const":"save"},"settings":{"type":"object","properties":{"mode":{"type":"string","enum":["automatic","review"]},"totalCents":{"type":"integer","minimum":1000,"maximum":100000},"dailyCents":{"type":"integer","minimum":500,"maximum":100000},"perPostCents":{"type":"integer","minimum":500,"maximum":100000},"minAgeHours":{"type":"integer","minimum":1,"maximum":48},"minImpressions":{"type":"integer","minimum":50,"maximum":100000},"minLiftPercent":{"type":"integer","minimum":0,"maximum":500},"scope":{"type":"string","enum":["twin","all"]},"country":{"type":"string","enum":["US","CA","GB","AU","NZ"]},"audience":{"type":"string","maxLength":500},"excludeWords":{"type":"string","maxLength":500},"excludedPostIds":{"type":"array","maxItems":50,"items":{"type":"string","pattern":"^[0-9]{1,25}$"}}},"required":["mode","totalCents","dailyCents","perPostCents","minAgeHours","minImpressions","minLiftPercent","scope","country","audience","excludeWords","excludedPostIds"],"additionalProperties":false},"revision":{"type":"integer","minimum":0}},"required":["action","settings","revision"],"additionalProperties":false},{"type":"object","properties":{"action":{"enum":["preview","enable"]},"revision":{"type":"integer","minimum":1},"consent":{"const":true},"pricingVersion":{"const":"shared-credits-v1"}},"required":["action","revision","consent","pricingVersion"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"approve"},"revision":{"type":"integer","minimum":1},"postId":{"type":"string","pattern":"^[0-9]{1,25}$"},"consent":{"const":true},"pricingVersion":{"const":"shared-credits-v1"}},"required":["action","revision","postId","consent","pricingVersion"],"additionalProperties":false},{"type":"object","properties":{"action":{"const":"request_access"},"consent":{"const":true}},"required":["action","consent"],"additionalProperties":false},{"type":"object","properties":{"action":{"enum":["pause","withdraw_access"]}},"required":["action"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Boosts"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or no active plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict or setup required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until a retry is appropriate.","schema":{"type":"integer"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider work failed; the paid reservation may remain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}