{"openapi":"3.1.0","info":{"title":"WTFLOW API","version":"1.0.0","description":"Create motion-graphics videos for businesses from code: research a business, pick a creative direction, write and approve the script, build the scenes, and edit them by chat. MP4 export runs in the WTFLOW editor in the browser.","contact":{"url":"https://www.wtflow-studio.com/docs"}},"servers":[{"url":"https://www.wtflow-studio.com/api/v1","description":"Production"}],"tags":[{"name":"Account","description":"Your account, balance and gift codes.","x-he":"חשבון","x-he-description":"החשבון, היתרה וקודי מתנה."},{"name":"Projects","description":"Create, read and delete projects.","x-he":"פרויקטים","x-he-description":"יצירה, קריאה ומחיקה של פרויקטים."},{"name":"Pipeline","description":"Research, directions, script and the built composition.","x-he":"שלבי ההפקה","x-he-description":"מחקר, כיוונים, תסריט והקומפוזיציה הבנויה."},{"name":"Chat & edits","description":"Chat with the project, apply proposed edits, follow jobs.","x-he":"צ׳אט ועריכות","x-he-description":"צ׳אט עם הפרויקט, אישור עריכות מוצעות ומעקב אחרי עבודות."},{"name":"Assets","description":"Files in your library.","x-he":"קבצים","x-he-description":"הקבצים בספרייה שלכם."},{"name":"Skills","description":"House rules the model applies, including imports from GitHub.","x-he":"סקילים","x-he-description":"כללי הבית שהמודל מיישם, כולל ייבוא מ-GitHub."},{"name":"Stock library","description":"Licensed music and sound effects.","x-he":"ספריית סטוק","x-he-description":"מוזיקה ואפקטים מורשים."},{"name":"Meta","description":"About the API itself.","x-he":"מטא","x-he-description":"על ה-API עצמו."}],"security":[{"bearerAuth":[]}],"paths":{"/me":{"get":{"operationId":"getMe","tags":["Account"],"summary":"Your account, plan and balance","description":"Who the key belongs to, the plan, and how many credits are left.","x-he-summary":"החשבון, החבילה והיתרה","x-he-description":"למי שייך המפתח, איזו חבילה פעילה וכמה קרדיטים נשארו.","x-credits":"free","x-mcp-tool":"get_balance","responses":{"200":{"description":"The account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"},"example":{"id":"k17c3e8w2m5p9x4d6f1h0b7q3t8n2r5a","email":"dana@brightdesk.example","name":"Dana","balance":4120,"admin":false,"plan":{"id":"pro","name":"Pro","status":"active","interval":"month","creditsPerMonth":5000,"periodEnd":"2026-10-29T08:00:00.000Z","cancelAtPeriodEnd":false},"key":{"scope":"user","rateLimitPerMinute":60}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/gifts/redeem":{"post":{"operationId":"redeemGiftCode","tags":["Account"],"summary":"Redeem a gift code","description":"Adds the code's credits to your balance. Each code works once per account.","x-he-summary":"מימוש קוד מתנה","x-he-description":"מוסיף את הקרדיטים של הקוד ליתרה. כל קוד עובד פעם אחת לכל חשבון.","x-credits":"free","x-mcp-tool":"redeem_gift_code","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The gift code, e.g. WTF-7K2MQ-X9P4R.","x-he":"קוד המתנה."}},"required":["code"]},"example":{"code":"WTF-7K2MQ-X9P4R"}}}},"responses":{"200":{"description":"Redeemed.","content":{"application/json":{"schema":{"type":"object","properties":{"credits":{"type":"number","description":"Credits added."},"balance":{"type":"number","description":"New balance."}}},"example":{"credits":500,"balance":4620}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects":{"get":{"operationId":"listProjects","tags":["Projects"],"summary":"List projects","description":"Your projects, newest first. Pass `nextCursor` back as `cursor` for the next page.","x-he-summary":"רשימת פרויקטים","x-he-description":"הפרויקטים שלכם, מהחדש לישן. כדי לקבל עמוד נוסף שולחים את nextCursor בפרמטר cursor.","x-credits":"free","x-mcp-tool":"list_projects","parameters":[{"name":"limit","in":"query","description":"How many to return (1-100, default 20).","x-he":"כמה להחזיר (1 עד 100, ברירת מחדל 20).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","x-he":"ה-nextCursor מהעמוד הקודם.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of projects.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSummary"}},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page; null on the last page."}}},"example":{"data":[{"id":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","name":"brightdesk.example","stage":"research","aspect":"16:9","language":"en","duration":null,"status":{"busy":false,"step":null,"error":null,"since":null},"reviewStatus":"draft","createdAt":"2026-09-29T09:41:00.000Z","updatedAt":"2026-09-29T09:41:00.000Z","editorUrl":"https://www.wtflow-studio.com/p/j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"}],"nextCursor":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createProject","tags":["Projects"],"summary":"Create a project","description":"Creates a project from a brief. Nothing is charged unless `runResearch` is true. Research can also be started later with POST /projects/{projectId}/research.","x-he-summary":"יצירת פרויקט","x-he-description":"יוצר פרויקט מבריף. שום דבר לא מחויב, אלא אם runResearch הוא true. אפשר להתחיל את המחקר גם אחר כך.","x-credits":"free","x-mcp-tool":"create_project","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The business website. The research step reads it.","format":"uri","x-he":"אתר העסק. שלב המחקר קורא אותו."},"prompt":{"type":"string","description":"What the video should do, in your words (up to 4,000 characters). Give a url, a prompt, or both.","x-he":"מה הסרטון צריך לעשות, במילים שלכם (עד 4,000 תווים). צריך url, prompt או את שניהם."},"name":{"type":"string","description":"Project name. Defaults to the site's domain or the prompt's first words.","x-he":"שם הפרויקט. ברירת המחדל: הדומיין של האתר או תחילת הבריף."},"videoType":{"type":"string","description":"Kind of video, e.g. Product video, Feature launch, Service explainer.","default":"Product video","x-he":"סוג הסרטון, למשל סרטון מוצר או השקת פיצ׳ר."},"goal":{"type":"string","description":"What the video should achieve.","x-he":"מה הסרטון צריך להשיג."},"audience":{"type":"string","description":"Who it is for.","x-he":"למי הוא מיועד."},"language":{"type":"string","description":"Video language.","enum":["he","en"],"default":"he","x-he":"שפת הסרטון."},"duration":{"type":"integer","description":"Target length in seconds (6-180).","minimum":6,"maximum":180,"default":30,"x-he":"אורך מבוקש בשניות (6 עד 180)."},"aspect":{"type":"string","description":"Frame format.","enum":["16:9","9:16","1:1"],"default":"16:9","x-he":"פורמט הפריים."},"narration":{"type":"string","description":"auto lets the model decide; none = on-screen text only; voice = a voice-over.","enum":["auto","none","voice"],"default":"auto","x-he":"auto: המודל מחליט. none: טקסט על המסך בלבד. voice: קריינות."},"assetIds":{"type":"array","items":{"type":"string","description":"Asset id."},"description":"Files you already have in the library (asset ids) to add to the project.","x-he":"קבצים שכבר העליתם (מזהי asset) שיצורפו לפרויקט."},"runResearch":{"type":"boolean","description":"Start the research right away. Costs credits. Default false.","default":false,"x-he":"להתחיל את המחקר מיד. עולה קרדיטים. ברירת המחדל false."}}},"example":{"url":"https://brightdesk.example","prompt":"A 30-second launch video for small support teams. Calm, confident, no hype.","language":"en","duration":30,"aspect":"16:9"}}}},"responses":{"201":{"description":"The new project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"},"example":{"id":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","name":"brightdesk.example","stage":"research","aspect":"16:9","language":"en","duration":null,"status":{"busy":false,"step":null,"error":null,"since":null},"reviewStatus":"draft","createdAt":"2026-09-29T09:41:00.000Z","updatedAt":"2026-09-29T09:41:00.000Z","editorUrl":"https://www.wtflow-studio.com/p/j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","next":"run_research","hasComposition":false,"brief":{"url":"https://brightdesk.example","prompt":"A 30-second launch video for small support teams. Calm, confident, no hype.","videoType":"Product video","goal":"Sign-ups for the free plan","audience":"Support leads at companies of 5 to 50 people","language":"en","duration":30,"aspect":"16:9","narration":"auto"},"research":null,"researchApproved":false,"sources":[],"directions":[],"chosenDirection":null,"script":null,"scriptApproved":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{projectId}":{"get":{"operationId":"getProject","tags":["Projects"],"summary":"Get a project","description":"The whole project: brief, research, directions, script, status and `next`, the call to make next. Poll this while `status.busy` is true (every 3-5 seconds is plenty).","x-he-summary":"פרטי פרויקט","x-he-description":"הפרויקט כולו: בריף, מחקר, כיוונים, תסריט, סטטוס, ו-next שאומר מה הקריאה הבאה. בזמן ש-status.busy הוא true בודקים שוב כל 3 עד 5 שניות.","x-credits":"free","x-mcp-tool":"get_project","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"}],"responses":{"200":{"description":"The project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"},"example":{"id":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","name":"brightdesk.example","stage":"script","aspect":"16:9","language":"en","duration":null,"status":{"busy":false,"step":null,"error":null,"since":null},"reviewStatus":"draft","createdAt":"2026-09-29T09:41:00.000Z","updatedAt":"2026-09-29T09:41:00.000Z","editorUrl":"https://www.wtflow-studio.com/p/j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","next":"choose_direction","hasComposition":false,"brief":{"url":"https://brightdesk.example","prompt":"A 30-second launch video for small support teams. Calm, confident, no hype.","videoType":"Product video","goal":"Sign-ups for the free plan","audience":"Support leads at companies of 5 to 50 people","language":"en","duration":30,"aspect":"16:9","narration":"auto"},"research":{"company":{"name":"Brightdesk","oneLiner":"A shared inbox for small support teams","category":"saas"},"whatItDoes":"Brightdesk puts email, chat and WhatsApp conversations in one inbox, with assignment, saved replies and response-time timers.","audience":["Support leads at 5 to 50 person companies","Founders who still answer support themselves"],"problem":"Requests arrive in five places, and some are never answered.","benefits":[{"text":"Every channel lands in one inbox","source":"https://brightdesk.example/features","kind":"fact"}],"messages":["One inbox for every customer conversation"],"tone":{"words":["calm","direct","practical"],"description":"Plain words, short sentences."},"facts":[{"text":"Free plan for up to 2 agents","source":"https://brightdesk.example/pricing","kind":"fact"}],"assumptions":[{"text":"Most customers sell online","source":"","kind":"assumption"}],"brand":{"colors":["#0F172A","#22C55E"],"fonts":["Inter"],"notes":"Dark navy with a green accent"},"productDetails":["Shared inbox","Saved replies","Response-time timers"],"questions":[{"question":"Should the video mention the free plan?","impact":"It changes the call to action"}],"summary":"Brightdesk is a shared inbox for small support teams. The site stresses one inbox for every channel and a free plan for two agents."},"researchApproved":true,"sources":[],"directions":[{"id":"d1","title":"Five inboxes, one team","promise":"Nothing gets lost again","hook":"Five notification sounds at once, then silence","tone":"Calm and exact","motion":"Cards fly in from five edges and stack into one list","cta":"Start free with two agents","why":"The site's main message is one inbox for every channel"},{"id":"d2","title":"The 9:02 rush","promise":"Monday morning without the panic","hook":"A clock hits 9:02 and the queue explodes","tone":"Light, a little funny","motion":"Counters roll down as tickets get assigned","cta":"Try Brightdesk free","why":"Support leads remember the Monday spike"}],"chosenDirection":null,"script":null,"scriptApproved":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"deleteProject","tags":["Projects"],"summary":"Delete a project","description":"Deletes the project with its composition, versions, messages and exports. Its assets stay in your library.","x-he-summary":"מחיקת פרויקט","x-he-description":"מוחק את הפרויקט עם הקומפוזיציה, הגרסאות, ההודעות והייצואים. הקבצים נשארים בספרייה שלכם.","x-credits":"free","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Project id."},"deleted":{"type":"boolean","description":"Always true."}}},"example":{"id":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","deleted":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{projectId}/research":{"post":{"operationId":"startResearch","tags":["Pipeline"],"summary":"Run research","description":"Crawls the website's internal pages with real page screenshots and brand images, then the model writes the business brief. Takes about one to three minutes on a small site, longer on a large one. Poll GET /projects/{projectId} until `status.busy` is false, then read `research`. Running it again replaces the brief.","x-he-summary":"הרצת מחקר","x-he-description":"סורק את הדפים הפנימיים של האתר עם צילומי מסך אמיתיים ותמונות מותג, ואז המודל כותב את הבריף העסקי. לוקח בערך דקה עד שלוש באתר קטן, ויותר באתר גדול. בודקים את הפרויקט עד ש-status.busy הוא false, ואז קוראים את research. הרצה נוספת מחליפה את הבריף.","x-credits":"charged","x-mcp-tool":"run_research","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"}],"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"},"example":{"id":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","name":"brightdesk.example","stage":"research","aspect":"16:9","language":"en","duration":null,"status":{"busy":true,"step":"Reading the website","error":null,"since":"2026-09-29T09:41:00.000Z"},"reviewStatus":"draft","createdAt":"2026-09-29T09:41:00.000Z","updatedAt":"2026-09-29T09:41:00.000Z","editorUrl":"https://www.wtflow-studio.com/p/j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","next":"wait","hasComposition":false,"brief":{"url":"https://brightdesk.example","prompt":"A 30-second launch video for small support teams. Calm, confident, no hype.","videoType":"Product video","goal":"Sign-ups for the free plan","audience":"Support leads at companies of 5 to 50 people","language":"en","duration":30,"aspect":"16:9","narration":"auto"},"research":null,"researchApproved":false,"sources":[],"directions":[],"chosenDirection":null,"script":null,"scriptApproved":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updateResearch","tags":["Pipeline"],"summary":"Edit the research","description":"Changes the brief before you approve it. Top-level fields you send replace the current ones; the rest stay. You can also write the whole brief yourself and skip the research call.","x-he-summary":"עריכת המחקר","x-he-description":"משנה את הבריף לפני האישור. שדות שנשלחים מחליפים את הקיימים, והשאר נשאר. אפשר גם לכתוב את כל הבריף בעצמכם ולוותר על קריאת המחקר.","x-credits":"free","x-mcp-tool":"update_research","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"research":{"$ref":"#/components/schemas/Research","x-he":"שדות הבריף לעדכון. כל שדה עליון שנשלח מחליף את הקיים."}},"required":["research"]},"example":{"research":{"messages":["One inbox for every customer conversation","Free for two agents"],"tone":{"words":["calm","direct"],"description":"Plain words."}}}}}},"responses":{"200":{"description":"The updated research.","content":{"application/json":{"schema":{"type":"object","properties":{"research":{"$ref":"#/components/schemas/Research"},"researchApproved":{"type":"boolean","description":"Approval state."}}},"example":{"research":{"company":{"name":"Brightdesk","oneLiner":"A shared inbox for small support teams","category":"saas"},"whatItDoes":"Brightdesk puts email, chat and WhatsApp conversations in one inbox, with assignment, saved replies and response-time timers.","audience":["Support leads at 5 to 50 person companies","Founders who still answer support themselves"],"problem":"Requests arrive in five places, and some are never answered.","benefits":[{"text":"Every channel lands in one inbox","source":"https://brightdesk.example/features","kind":"fact"}],"messages":["One inbox for every customer conversation"],"tone":{"words":["calm","direct","practical"],"description":"Plain words, short sentences."},"facts":[{"text":"Free plan for up to 2 agents","source":"https://brightdesk.example/pricing","kind":"fact"}],"assumptions":[{"text":"Most customers sell online","source":"","kind":"assumption"}],"brand":{"colors":["#0F172A","#22C55E"],"fonts":["Inter"],"notes":"Dark navy with a green accent"},"productDetails":["Shared inbox","Saved replies","Response-time timers"],"questions":[{"question":"Should the video mention the free plan?","impact":"It changes the call to action"}],"summary":"Brightdesk is a shared inbox for small support teams. The site stresses one inbox for every channel and a free plan for two agents."},"researchApproved":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{projectId}/research/approve":{"post":{"operationId":"approveResearch","tags":["Pipeline"],"summary":"Approve the research","description":"Locks the brief and asks the model for creative directions (usually three). Poll the project until `status.busy` is false, then GET /projects/{projectId}/directions.","x-he-summary":"אישור המחקר","x-he-description":"נועל את הבריף ומבקש מהמודל כיוונים קריאייטיביים (בדרך כלל שלושה). בודקים את הפרויקט עד ש-status.busy הוא false, ואז קוראים את הכיוונים.","x-credits":"charged","x-mcp-tool":"approve_research","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"}],"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"},"example":{"id":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","name":"brightdesk.example","stage":"script","aspect":"16:9","language":"en","duration":null,"status":{"busy":true,"step":"Creative directions","error":null,"since":"2026-09-29T09:41:00.000Z"},"reviewStatus":"draft","createdAt":"2026-09-29T09:41:00.000Z","updatedAt":"2026-09-29T09:41:00.000Z","editorUrl":"https://www.wtflow-studio.com/p/j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","next":"wait","hasComposition":false,"brief":{"url":"https://brightdesk.example","prompt":"A 30-second launch video for small support teams. Calm, confident, no hype.","videoType":"Product video","goal":"Sign-ups for the free plan","audience":"Support leads at companies of 5 to 50 people","language":"en","duration":30,"aspect":"16:9","narration":"auto"},"research":{"company":{"name":"Brightdesk","oneLiner":"A shared inbox for small support teams","category":"saas"},"whatItDoes":"Brightdesk puts email, chat and WhatsApp conversations in one inbox, with assignment, saved replies and response-time timers.","audience":["Support leads at 5 to 50 person companies","Founders who still answer support themselves"],"problem":"Requests arrive in five places, and some are never answered.","benefits":[{"text":"Every channel lands in one inbox","source":"https://brightdesk.example/features","kind":"fact"}],"messages":["One inbox for every customer conversation"],"tone":{"words":["calm","direct","practical"],"description":"Plain words, short sentences."},"facts":[{"text":"Free plan for up to 2 agents","source":"https://brightdesk.example/pricing","kind":"fact"}],"assumptions":[{"text":"Most customers sell online","source":"","kind":"assumption"}],"brand":{"colors":["#0F172A","#22C55E"],"fonts":["Inter"],"notes":"Dark navy with a green accent"},"productDetails":["Shared inbox","Saved replies","Response-time timers"],"questions":[{"question":"Should the video mention the free plan?","impact":"It changes the call to action"}],"summary":"Brightdesk is a shared inbox for small support teams. The site stresses one inbox for every channel and a free plan for two agents."},"researchApproved":true,"sources":[],"directions":[],"chosenDirection":null,"script":null,"scriptApproved":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{projectId}/directions":{"get":{"operationId":"listDirections","tags":["Pipeline"],"summary":"List creative directions","description":"The directions written after the research was approved, and the chosen one.","x-he-summary":"הכיוונים הקריאייטיביים","x-he-description":"הכיוונים שנכתבו אחרי אישור המחקר, והכיוון שנבחר.","x-credits":"free","x-mcp-tool":"list_directions","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"}],"responses":{"200":{"description":"Directions.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Direction"}},"chosenDirection":{"type":["string","null"],"description":"Chosen id."},"status":{"$ref":"#/components/schemas/Status"}}},"example":{"data":[{"id":"d1","title":"Five inboxes, one team","promise":"Nothing gets lost again","hook":"Five notification sounds at once, then silence","tone":"Calm and exact","motion":"Cards fly in from five edges and stack into one list","cta":"Start free with two agents","why":"The site's main message is one inbox for every channel"},{"id":"d2","title":"The 9:02 rush","promise":"Monday morning without the panic","hook":"A clock hits 9:02 and the queue explodes","tone":"Light, a little funny","motion":"Counters roll down as tickets get assigned","cta":"Try Brightdesk free","why":"Support leads remember the Monday spike"}],"chosenDirection":null,"status":{"busy":false,"step":null,"error":null,"since":null}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{projectId}/directions/{directionId}/choose":{"post":{"operationId":"chooseDirection","tags":["Pipeline"],"summary":"Choose a direction","description":"Picks a direction and writes the scene-by-scene script for it. Poll the project, then GET /projects/{projectId}/script.","x-he-summary":"בחירת כיוון","x-he-description":"בוחר כיוון וכותב לפיו תסריט סצנה אחר סצנה. בודקים את הפרויקט, ואז קוראים את התסריט.","x-credits":"charged","x-mcp-tool":"choose_direction","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"},{"name":"directionId","in":"path","required":true,"description":"A direction id from GET /projects/{projectId}/directions (d1, d2, …).","x-he":"מזהה כיוון מתוך רשימת הכיוונים (d1, d2…).","schema":{"type":"string"},"example":"d1"}],"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"},"example":{"id":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","name":"brightdesk.example","stage":"script","aspect":"16:9","language":"en","duration":null,"status":{"busy":true,"step":"Writing the script","error":null,"since":"2026-09-29T09:41:00.000Z"},"reviewStatus":"draft","createdAt":"2026-09-29T09:41:00.000Z","updatedAt":"2026-09-29T09:41:00.000Z","editorUrl":"https://www.wtflow-studio.com/p/j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","next":"wait","hasComposition":false,"brief":{"url":"https://brightdesk.example","prompt":"A 30-second launch video for small support teams. Calm, confident, no hype.","videoType":"Product video","goal":"Sign-ups for the free plan","audience":"Support leads at companies of 5 to 50 people","language":"en","duration":30,"aspect":"16:9","narration":"auto"},"research":{"company":{"name":"Brightdesk","oneLiner":"A shared inbox for small support teams","category":"saas"},"whatItDoes":"Brightdesk puts email, chat and WhatsApp conversations in one inbox, with assignment, saved replies and response-time timers.","audience":["Support leads at 5 to 50 person companies","Founders who still answer support themselves"],"problem":"Requests arrive in five places, and some are never answered.","benefits":[{"text":"Every channel lands in one inbox","source":"https://brightdesk.example/features","kind":"fact"}],"messages":["One inbox for every customer conversation"],"tone":{"words":["calm","direct","practical"],"description":"Plain words, short sentences."},"facts":[{"text":"Free plan for up to 2 agents","source":"https://brightdesk.example/pricing","kind":"fact"}],"assumptions":[{"text":"Most customers sell online","source":"","kind":"assumption"}],"brand":{"colors":["#0F172A","#22C55E"],"fonts":["Inter"],"notes":"Dark navy with a green accent"},"productDetails":["Shared inbox","Saved replies","Response-time timers"],"questions":[{"question":"Should the video mention the free plan?","impact":"It changes the call to action"}],"summary":"Brightdesk is a shared inbox for small support teams. The site stresses one inbox for every channel and a free plan for two agents."},"researchApproved":true,"sources":[],"directions":[{"id":"d1","title":"Five inboxes, one team","promise":"Nothing gets lost again","hook":"Five notification sounds at once, then silence","tone":"Calm and exact","motion":"Cards fly in from five edges and stack into one list","cta":"Start free with two agents","why":"The site's main message is one inbox for every channel"},{"id":"d2","title":"The 9:02 rush","promise":"Monday morning without the panic","hook":"A clock hits 9:02 and the queue explodes","tone":"Light, a little funny","motion":"Counters roll down as tickets get assigned","cta":"Try Brightdesk free","why":"Support leads remember the Monday spike"}],"chosenDirection":"d1","script":null,"scriptApproved":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{projectId}/script":{"get":{"operationId":"getScript","tags":["Pipeline"],"summary":"Get the script","description":"The script, whether it is approved, and the project's status.","x-he-summary":"קריאת התסריט","x-he-description":"התסריט, האם אושר, והסטטוס של הפרויקט.","x-credits":"free","x-mcp-tool":"get_script","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"}],"responses":{"200":{"description":"The script.","content":{"application/json":{"schema":{"type":"object","properties":{"script":{"anyOf":[{"$ref":"#/components/schemas/Script"},{"type":"null"}]},"approved":{"type":"boolean","description":"Approved."},"directionId":{"type":["string","null"],"description":"Direction."},"status":{"$ref":"#/components/schemas/Status"}}},"example":{"script":{"directionId":"d1","title":"Five inboxes, one team","narration":{"use":false,"why":"On-screen text carries a 30-second product video better than a voice"},"scenes":[{"id":"sc1","role":"hook","name":"Five pings","duration":4,"voiceover":"","onScreenText":"5 inboxes. 1 team.","visual":"Five app icons pulse on a navy background","motion":"Icons pop in on each ping","assets":[]},{"id":"sc2","role":"solution","name":"One list","duration":6,"voiceover":"","onScreenText":"Everything lands in one place","visual":"The five streams merge into one clean list","motion":"Cards slide into a single column","assets":["kg2m4p6r8t0v1x3z5b7d9f1h3k5m7p9q"]},{"id":"sc3","role":"cta","name":"Start free","duration":4,"voiceover":"","onScreenText":"Free for 2 agents","visual":"Logo and the button","motion":"Logo settles, button pulses once","assets":[]}],"musicPrompt":"calm modern electronic, 100 bpm, instrumental"},"approved":false,"directionId":"d1","status":{"busy":false,"step":null,"error":null,"since":null}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"operationId":"updateScript","tags":["Pipeline"],"summary":"Replace the script","description":"Saves your version of the script (the whole object). It is cleaned the same way as a model-written one: at most 16 scenes, 1-30 seconds each.","x-he-summary":"החלפת התסריט","x-he-description":"שומר גרסה שלכם של התסריט (האובייקט כולו). הוא מנוקה כמו תסריט שהמודל כתב: עד 16 סצנות, 1 עד 30 שניות כל אחת.","x-credits":"free","x-mcp-tool":"update_script","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"script":{"$ref":"#/components/schemas/Script","x-he":"התסריט המלא."}},"required":["script"]},"example":{"script":{"directionId":"d1","title":"Five inboxes, one team","narration":{"use":false,"why":"On-screen text carries a 30-second product video better than a voice"},"scenes":[{"id":"sc1","role":"hook","name":"Five pings","duration":4,"voiceover":"","onScreenText":"5 inboxes. 1 team.","visual":"Five app icons pulse on a navy background","motion":"Icons pop in on each ping","assets":[]},{"id":"sc2","role":"solution","name":"One list","duration":6,"voiceover":"","onScreenText":"Everything lands in one place","visual":"The five streams merge into one clean list","motion":"Cards slide into a single column","assets":["kg2m4p6r8t0v1x3z5b7d9f1h3k5m7p9q"]},{"id":"sc3","role":"cta","name":"Start free","duration":4,"voiceover":"","onScreenText":"Free for 2 agents","visual":"Logo and the button","motion":"Logo settles, button pulses once","assets":[]}],"musicPrompt":"calm modern electronic, 100 bpm, instrumental"}}}}},"responses":{"200":{"description":"The saved script.","content":{"application/json":{"schema":{"type":"object","properties":{"script":{"$ref":"#/components/schemas/Script"},"approved":{"type":"boolean","description":"Approved."},"directionId":{"type":["string","null"],"description":"Direction."},"status":{"$ref":"#/components/schemas/Status"}}},"example":{"script":{"directionId":"d1","title":"Five inboxes, one team","narration":{"use":false,"why":"On-screen text carries a 30-second product video better than a voice"},"scenes":[{"id":"sc1","role":"hook","name":"Five pings","duration":4,"voiceover":"","onScreenText":"5 inboxes. 1 team.","visual":"Five app icons pulse on a navy background","motion":"Icons pop in on each ping","assets":[]},{"id":"sc2","role":"solution","name":"One list","duration":6,"voiceover":"","onScreenText":"Everything lands in one place","visual":"The five streams merge into one clean list","motion":"Cards slide into a single column","assets":["kg2m4p6r8t0v1x3z5b7d9f1h3k5m7p9q"]},{"id":"sc3","role":"cta","name":"Start free","duration":4,"voiceover":"","onScreenText":"Free for 2 agents","visual":"Logo and the button","motion":"Logo settles, button pulses once","assets":[]}],"musicPrompt":"calm modern electronic, 100 bpm, instrumental"},"approved":false,"directionId":"d1","status":{"busy":false,"step":null,"error":null,"since":null}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{projectId}/script/approve":{"post":{"operationId":"approveScript","tags":["Pipeline"],"summary":"Approve the script","description":"Builds the scenes (the composition) from the script. With `withMotion` (default true) the model also writes animated motion layers for every scene the storyboard planned one for; the first draft's layers are part of the production price. Music and sound effects are picked from the stock library at no charge.","x-he-summary":"אישור התסריט","x-he-description":"בונה את הסצנות (הקומפוזיציה) מהתסריט. עם withMotion (ברירת מחדל true) המודל כותב גם שכבות מושן לכל סצנה שהסטוריבורד תכנן לה; שכבות הטיוטה הראשונה כלולות במחיר ההפקה. מוזיקה ואפקטים נבחרים מספריית הסטוק בלי חיוב.","x-credits":"charged","x-mcp-tool":"approve_script","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"withMotion":{"type":"boolean","description":"Also write motion layers for the scenes the storyboard planned them for.","default":true,"x-he":"לכתוב גם שכבות מושן לסצנות שהסטוריבורד תכנן להן."}}},"example":{"withMotion":true}}}},"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"},"example":{"id":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","name":"brightdesk.example","stage":"storyboard","aspect":"16:9","language":"en","duration":null,"status":{"busy":true,"step":"Building the scenes","error":null,"since":"2026-09-29T09:41:00.000Z"},"reviewStatus":"draft","createdAt":"2026-09-29T09:41:00.000Z","updatedAt":"2026-09-29T09:41:00.000Z","editorUrl":"https://www.wtflow-studio.com/p/j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","next":"wait","hasComposition":false,"brief":{"url":"https://brightdesk.example","prompt":"A 30-second launch video for small support teams. Calm, confident, no hype.","videoType":"Product video","goal":"Sign-ups for the free plan","audience":"Support leads at companies of 5 to 50 people","language":"en","duration":30,"aspect":"16:9","narration":"auto"},"research":{"company":{"name":"Brightdesk","oneLiner":"A shared inbox for small support teams","category":"saas"},"whatItDoes":"Brightdesk puts email, chat and WhatsApp conversations in one inbox, with assignment, saved replies and response-time timers.","audience":["Support leads at 5 to 50 person companies","Founders who still answer support themselves"],"problem":"Requests arrive in five places, and some are never answered.","benefits":[{"text":"Every channel lands in one inbox","source":"https://brightdesk.example/features","kind":"fact"}],"messages":["One inbox for every customer conversation"],"tone":{"words":["calm","direct","practical"],"description":"Plain words, short sentences."},"facts":[{"text":"Free plan for up to 2 agents","source":"https://brightdesk.example/pricing","kind":"fact"}],"assumptions":[{"text":"Most customers sell online","source":"","kind":"assumption"}],"brand":{"colors":["#0F172A","#22C55E"],"fonts":["Inter"],"notes":"Dark navy with a green accent"},"productDetails":["Shared inbox","Saved replies","Response-time timers"],"questions":[{"question":"Should the video mention the free plan?","impact":"It changes the call to action"}],"summary":"Brightdesk is a shared inbox for small support teams. The site stresses one inbox for every channel and a free plan for two agents."},"researchApproved":true,"sources":[],"directions":[{"id":"d1","title":"Five inboxes, one team","promise":"Nothing gets lost again","hook":"Five notification sounds at once, then silence","tone":"Calm and exact","motion":"Cards fly in from five edges and stack into one list","cta":"Start free with two agents","why":"The site's main message is one inbox for every channel"},{"id":"d2","title":"The 9:02 rush","promise":"Monday morning without the panic","hook":"A clock hits 9:02 and the queue explodes","tone":"Light, a little funny","motion":"Counters roll down as tickets get assigned","cta":"Try Brightdesk free","why":"Support leads remember the Monday spike"}],"chosenDirection":"d1","script":{"directionId":"d1","title":"Five inboxes, one team","narration":{"use":false,"why":"On-screen text carries a 30-second product video better than a voice"},"scenes":[{"id":"sc1","role":"hook","name":"Five pings","duration":4,"voiceover":"","onScreenText":"5 inboxes. 1 team.","visual":"Five app icons pulse on a navy background","motion":"Icons pop in on each ping","assets":[]},{"id":"sc2","role":"solution","name":"One list","duration":6,"voiceover":"","onScreenText":"Everything lands in one place","visual":"The five streams merge into one clean list","motion":"Cards slide into a single column","assets":["kg2m4p6r8t0v1x3z5b7d9f1h3k5m7p9q"]},{"id":"sc3","role":"cta","name":"Start free","duration":4,"voiceover":"","onScreenText":"Free for 2 agents","visual":"Logo and the button","motion":"Logo settles, button pulses once","assets":[]}],"musicPrompt":"calm modern electronic, 100 bpm, instrumental"},"scriptApproved":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{projectId}/composition":{"get":{"operationId":"getComposition","tags":["Pipeline"],"summary":"Get the composition","description":"The built video as JSON: scenes, layers, timing, theme, music and effects. MP4 files are rendered in the WTFLOW editor in the browser; open `editorUrl` to export. Server-side rendering is not available yet.","x-he-summary":"קריאת הקומפוזיציה","x-he-description":"הסרטון הבנוי כ-JSON: סצנות, שכבות, תזמון, עיצוב, מוזיקה ואפקטים. קובץ MP4 מרונדר בעורך של WTFLOW בדפדפן: פותחים את editorUrl ומייצאים. רינדור בשרת עוד לא זמין.","x-credits":"free","x-mcp-tool":"get_composition","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"}],"responses":{"200":{"description":"The composition.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompositionResponse"},"example":{"projectId":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","revision":7,"updatedAt":"2026-09-29T09:42:10.000Z","duration":14,"composition":{"version":1,"aspect":"16:9","fps":30,"theme":{"bg":"#0F172A","surface":"#1E293B","text":"#F8FAFC","muted":"#94A3B8","accent":"#22C55E","accent2":"#38BDF8","headingFont":"Inter","bodyFont":"Inter","radius":16,"direction":"ltr","language":"en"},"scenes":[{"id":"s1","name":"Five pings","role":"hook","duration":4,"background":{"type":"gradient","from":"#0F172A","to":"#1E293B","angle":135,"pattern":"glow"},"layers":[{"id":"t1","type":"text","name":"Headline","text":"5 inboxes. 1 team.","start":0.3,"end":4,"x":0.5,"y":0.5,"w":0.8,"h":0.2,"font":"Inter","weight":800,"size":96,"color":"#F8FAFC","align":"center","enter":{"preset":"rise","duration":0.6,"delay":0,"ease":"out"}}],"transition":{"type":"fade","duration":0.4},"voiceover":{"text":"","status":"none"},"sfx":[{"id":"fx1","name":"Ping","at":0.3,"query":"soft notification ping","volume":0.65,"status":"ready","assetId":"kg2m4p6r8t0v1x3z5b7d9f1h3k5m7p9q","title":"Soft Ping 02"}]}],"music":{"query":"calm modern electronic","title":"Quiet Motion","assetId":"kg2m4p6r8t0v1x3z5b7d9f1h3k5m7p9q","volume":0.6,"status":"ready"},"voiceVolume":1,"captions":false},"editorUrl":"https://www.wtflow-studio.com/p/j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","rendering":{"serverSide":false,"message":"MP4 export runs in the WTFLOW editor, in the browser. Open editorUrl to export. Server-side rendering is not available yet."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{projectId}/messages":{"get":{"operationId":"listMessages","tags":["Chat & edits"],"summary":"List chat messages","description":"The project's chat, oldest first. An assistant reply with `pending: true` is still being written. A reply to an edit request carries a `proposal`.","x-he-summary":"הודעות הצ׳אט","x-he-description":"הצ׳אט של הפרויקט, מהישן לחדש. תשובה עם pending: true עוד נכתבת. תשובה לבקשת עריכה מגיעה עם proposal.","x-credits":"free","x-mcp-tool":"list_messages","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"},{"name":"limit","in":"query","description":"How many to return (1-200, default 50).","x-he":"כמה להחזיר (1 עד 200, ברירת מחדל 50).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Messages.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}},"example":{"data":[{"id":"n97a1d3f5h7k9m2p4r6t8v0x1z3b5c7d","role":"user","stage":"storyboard","text":"Make the headline in scene 1 green and shorter","pending":false,"steps":[],"attachments":[],"proposal":null,"createdAt":"2026-09-29T09:41:00.000Z"},{"id":"n97a1d3f5h7k9m2p4r6t8v0x1z3b5c8e","role":"assistant","stage":"storyboard","text":"Changed the headline to “One inbox.” in the accent green.","pending":false,"steps":[{"label":"Working on it","status":"done","detail":null}],"attachments":[],"proposal":{"state":"pending","summary":"Changed the headline to “One inbox.” in the accent green.","changedScenes":["Five pings"],"changedLayers":["Five pings · Headline"],"rejected":[],"mediaCount":0,"opCount":2,"appliedVersion":null},"createdAt":"2026-09-29T09:41:00.000Z"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"sendMessage","tags":["Chat & edits"],"summary":"Send a chat message","description":"Talk to the project the way you would in the studio chat. Before the research is approved the message refines the brief; at the script stage it refines the script; once scenes exist it becomes an edit request, and the reply carries a proposal you apply or dismiss. Poll GET /projects/{projectId}/messages until the reply's `pending` is false.","x-he-summary":"שליחת הודעה בצ׳אט","x-he-description":"מדברים עם הפרויקט כמו בצ׳אט של הסטודיו. לפני אישור המחקר ההודעה מעדכנת את הבריף, בשלב התסריט היא מעדכנת את התסריט, ואחרי שנבנו סצנות היא בקשת עריכה שהתשובה עליה מביאה הצעה (proposal) לאישור או לדחייה. בודקים את ההודעות עד שהתשובה כבר לא pending.","x-credits":"charged","x-mcp-tool":"send_message","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"The message (up to 4,000 characters).","x-he":"ההודעה (עד 4,000 תווים)."},"attachments":{"type":"array","items":{"type":"string","description":"Asset id."},"description":"Asset ids to attach (up to 10). Images are shown to the model, and you can ask to put them in the video.","x-he":"מזהי קבצים לצרף (עד 10). תמונות נשלחות למודל, ואפשר לבקש לשים אותן בסרטון."}},"required":["text"]},"example":{"text":"Make the headline in scene 1 green and shorter"}}}},"responses":{"202":{"description":"Sent; the reply is being written.","content":{"application/json":{"schema":{"type":"object","properties":{"messageId":{"type":["string","null"],"description":"Your message."},"replyId":{"type":["string","null"],"description":"The assistant's reply, pending for now."},"status":{"type":"string","description":"started"},"poll":{"type":"string","description":"How to follow up."}}},"example":{"messageId":"n97a1d3f5h7k9m2p4r6t8v0x1z3b5c7d","replyId":"n97a1d3f5h7k9m2p4r6t8v0x1z3b5c8e","status":"started","poll":"GET /projects/j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v/messages until the reply's \"pending\" is false"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{projectId}/proposals/{messageId}/apply":{"post":{"operationId":"applyProposal","tags":["Chat & edits"],"summary":"Apply a proposal","description":"Applies the edit the assistant proposed. The state before it is saved as a version, so it can be undone in the editor. If the proposal includes paid media (voice, images, video, motion layers) those jobs start now and are charged.","x-he-summary":"אישור הצעה","x-he-description":"מחיל את העריכה שהעוזר הציע. המצב שלפניה נשמר כגרסה, כך שאפשר לחזור אליו בעורך. אם בהצעה יש מדיה בתשלום (קריינות, תמונות, וידאו, שכבות מושן), העבודות האלה מתחילות עכשיו ומחויבות.","x-credits":"free","x-mcp-tool":"apply_proposal","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"},{"name":"messageId","in":"path","required":true,"description":"The assistant message that carries the proposal.","x-he":"הודעת העוזר שמחזיקה את ההצעה.","schema":{"type":"string"},"example":"n97a1d3f5h7k9m2p4r6t8v0x1z3b5c8e"}],"responses":{"200":{"description":"Applied.","content":{"application/json":{"schema":{"type":"object","properties":{"messageId":{"type":"string","description":"Message."},"state":{"type":"string","description":"applied"},"version":{"type":["integer","null"],"description":"New version number."},"revision":{"type":["integer","null"],"description":"Composition revision."},"mediaJobs":{"type":"integer","description":"Paid media jobs started."}}},"example":{"messageId":"n97a1d3f5h7k9m2p4r6t8v0x1z3b5c8e","state":"applied","version":4,"revision":8,"mediaJobs":0}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{projectId}/proposals/{messageId}/dismiss":{"post":{"operationId":"dismissProposal","tags":["Chat & edits"],"summary":"Dismiss a proposal","description":"Marks the proposal as dismissed. Nothing changes in the video.","x-he-summary":"דחיית הצעה","x-he-description":"מסמן את ההצעה כנדחתה. שום דבר לא משתנה בסרטון.","x-credits":"free","x-mcp-tool":"dismiss_proposal","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"},{"name":"messageId","in":"path","required":true,"description":"The assistant message that carries the proposal.","x-he":"הודעת העוזר שמחזיקה את ההצעה.","schema":{"type":"string"},"example":"n97a1d3f5h7k9m2p4r6t8v0x1z3b5c8e"}],"responses":{"200":{"description":"Dismissed.","content":{"application/json":{"schema":{"type":"object","properties":{"messageId":{"type":"string","description":"Message."},"state":{"type":"string","description":"dismissed"}}},"example":{"messageId":"n97a1d3f5h7k9m2p4r6t8v0x1z3b5c8e","state":"dismissed"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{projectId}/jobs":{"get":{"operationId":"listJobs","tags":["Chat & edits"],"summary":"List jobs","description":"Every AI job of the project, newest first, with status, progress, errors and the credits each one cost.","x-he-summary":"עבודות AI","x-he-description":"כל עבודות ה-AI של הפרויקט, מהחדשה לישנה, עם סטטוס, התקדמות, שגיאות והקרדיטים שכל אחת עלתה.","x-credits":"free","x-mcp-tool":"list_jobs","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","x-he":"מזהה הפרויקט.","schema":{"type":"string"},"example":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v"},{"name":"limit","in":"query","description":"How many to return (1-100, default 50).","x-he":"כמה להחזיר (1 עד 100, ברירת מחדל 50).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Jobs.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}}},"example":{"data":[{"id":"jd7f9h1k3m5p7r9t1v3x5z7b9d1f3h5k","kind":"llm","purpose":"research","label":"Understanding the business","status":"completed","progress":100,"error":null,"errorCode":null,"credits":38.5,"createdAt":"2026-09-29T09:41:00.000Z","finishedAt":"2026-09-29T09:42:10.000Z"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/library":{"get":{"operationId":"searchLibrary","tags":["Assets"],"summary":"Search Jennie's media library","description":"Find transparent motion and 3D renders by Hebrew or English search. Import the chosen file URL using import_asset, then use its asset ID. Inspect item credits. Rendered 3D videos are distinct from editable GLB models.","x-he-summary":"חיפוש בספריית ג׳ני","x-he-description":"חיפוש אלמנטים שקופים ואנימציות. מייבאים את הקובץ הרצוי באמצעות import_asset ומשלבים לפי מזהה הנכס.","x-credits":"free","x-mcp-tool":"search_library","parameters":[{"name":"q","in":"query","description":"Hebrew or English search.","x-he":"מילות חיפוש בעברית או באנגלית.","schema":{"type":"string","maxLength":200}},{"name":"type","in":"query","description":"Optional asset category.","x-he":"סוג הפריט.","schema":{"type":"string","enum":["3d","motion"]}}],"responses":{"200":{"description":"Library matches.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"total":{"type":"integer","description":"Matching items"},"next":{"type":"string","description":"Import instructions"}}},"example":{"data":[],"total":0,"next":"Use import_asset."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/undefined"}}}},"/assets":{"get":{"operationId":"listAssets","tags":["Assets"],"summary":"List assets","description":"Your files (uploads, images read from sites, generated media, stock audio). Pass `projectId` for one project's files. Download URLs are temporary.","x-he-summary":"רשימת קבצים","x-he-description":"הקבצים שלכם: העלאות, תמונות מהאתר, מדיה שנוצרה ואודיו מהסטוק. עם projectId מקבלים רק את קבצי הפרויקט. קישורי ההורדה זמניים.","x-credits":"free","x-mcp-tool":"list_assets","parameters":[{"name":"projectId","in":"query","description":"Only this project's assets.","x-he":"רק הקבצים של הפרויקט הזה.","schema":{"type":"string"}}],"responses":{"200":{"description":"Assets.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}}}},"example":{"data":[{"id":"kg2m4p6r8t0v1x3z5b7d9f1h3k5m7p9q","name":"logo.svg","kind":"image","category":"brand","origin":"user","projectId":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","status":"ready","mime":"image/svg+xml","size":4180,"width":null,"height":null,"duration":null,"url":"https://…/api/storage/3f7c2a91-…","createdAt":"2026-09-29T09:41:00.000Z"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"importAsset","tags":["Assets"],"summary":"Import a file from a URL","description":"Downloads an image, video, audio or GLB model file (up to 100 MB) from a public URL into your library. Use the returned id in `assetIds`, message `attachments` or script scenes.","x-he-summary":"ייבוא קובץ מכתובת","x-he-description":"מוריד תמונה, וידאו או אודיו (עד 100MB) מכתובת ציבורית לספרייה שלכם. את המזהה שחוזר משתמשים ב-assetIds, בצירופים להודעה או בסצנות התסריט.","x-credits":"free","x-mcp-tool":"import_asset","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Public http(s) URL of the file.","format":"uri","x-he":"כתובת ציבורית של הקובץ."},"projectId":{"type":"string","description":"Put it in this project.","x-he":"לשייך לפרויקט הזה."},"name":{"type":"string","description":"Name in the library. Defaults to the file name.","x-he":"שם בספרייה. ברירת המחדל: שם הקובץ."},"category":{"type":"string","description":"Library category.","enum":["brand","product","image","video","audio","motion"],"x-he":"קטגוריה בספרייה."}},"required":["url"]},"example":{"url":"https://brightdesk.example/press/logo.png","projectId":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","category":"brand"}}}},"responses":{"201":{"description":"Imported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"},"example":{"id":"kg2m4p6r8t0v1x3z5b7d9f1h3k5m7p9q","name":"logo.png","kind":"image","category":"brand","origin":"user","projectId":"j57b2m9x4k8d1c6f3h0q7t5w2n9r4s1v","status":"ready","mime":"image/png","size":18230,"width":null,"height":null,"duration":null,"url":"https://…/api/storage/3f7c2a91-…","createdAt":"2026-09-29T09:41:00.000Z"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/skills":{"get":{"operationId":"listSkills","tags":["Skills"],"summary":"List skills","description":"Your house rules. Enabled, ready skills are applied on every model call where they are relevant.","x-he-summary":"רשימת סקילים","x-he-description":"הכללים של הבית שלכם. סקיל פעיל ומוכן נכנס לכל קריאה למודל שהוא רלוונטי לה.","x-credits":"free","x-mcp-tool":"list_skills","responses":{"200":{"description":"Skills.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}}}},"example":{"data":[{"id":"ks1a3c5e7g9j2l4n6q8s0u2w4y6a8c0e","name":"Our CTA","description":"How every video ends","whenToUse":"","instructions":"- The last scene always says “Start free”\n- Logo bottom-right, 12% of the width","enabled":true,"source":"user","status":"ready","origin":null,"error":null,"uses":3,"createdAt":"2026-09-29T09:41:00.000Z","updatedAt":"2026-09-29T09:41:00.000Z"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createSkill","tags":["Skills"],"summary":"Create a skill","description":"Adds a house rule set, enabled right away.","x-he-summary":"יצירת סקיל","x-he-description":"מוסיף סט כללים, פעיל מיד.","x-credits":"free","x-mcp-tool":"create_skill","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"2-5 words (up to 80 characters).","x-he":"2 עד 5 מילים (עד 80 תווים)."},"instructions":{"type":"string","description":"The rules, one per line (up to 8,000 characters).","x-he":"הכללים, שורה לכל כלל (עד 8,000 תווים)."},"description":{"type":"string","description":"One sentence.","x-he":"משפט אחד."},"whenToUse":{"type":"string","description":"When it applies. Leave empty for always.","x-he":"מתי הוא חל. ריק = תמיד."}},"required":["name","instructions"]},"example":{"name":"Our CTA","description":"How every video ends","instructions":"- The last scene always says “Start free”\n- Logo bottom-right, 12% of the width"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"},"example":{"id":"ks1a3c5e7g9j2l4n6q8s0u2w4y6a8c0e","name":"Our CTA","description":"How every video ends","whenToUse":"","instructions":"- The last scene always says “Start free”\n- Logo bottom-right, 12% of the width","enabled":true,"source":"user","status":"ready","origin":null,"error":null,"uses":0,"createdAt":"2026-09-29T09:41:00.000Z","updatedAt":"2026-09-29T09:41:00.000Z"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/skills/{skillId}":{"get":{"operationId":"getSkill","tags":["Skills"],"summary":"Get a skill","description":"One skill with its full instructions.","x-he-summary":"פרטי סקיל","x-he-description":"סקיל אחד עם כל ההוראות.","x-credits":"free","parameters":[{"name":"skillId","in":"path","required":true,"description":"The skill's id.","x-he":"מזהה הסקיל.","schema":{"type":"string"},"example":"ks1a3c5e7g9j2l4n6q8s0u2w4y6a8c0e"}],"responses":{"200":{"description":"The skill.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"},"example":{"id":"ks1a3c5e7g9j2l4n6q8s0u2w4y6a8c0e","name":"Our CTA","description":"How every video ends","whenToUse":"","instructions":"- The last scene always says “Start free”","enabled":true,"source":"user","status":"ready","origin":null,"error":null,"uses":3,"createdAt":"2026-09-29T09:41:00.000Z","updatedAt":"2026-09-29T09:41:00.000Z"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updateSkill","tags":["Skills"],"summary":"Update a skill","description":"Changes any of name, description, whenToUse, instructions or enabled.","x-he-summary":"עדכון סקיל","x-he-description":"משנה כל אחד מהשדות: name, description, whenToUse, instructions או enabled.","x-credits":"free","parameters":[{"name":"skillId","in":"path","required":true,"description":"The skill's id.","x-he":"מזהה הסקיל.","schema":{"type":"string"},"example":"ks1a3c5e7g9j2l4n6q8s0u2w4y6a8c0e"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name.","x-he":"שם."},"description":{"type":"string","description":"One sentence.","x-he":"משפט אחד."},"whenToUse":{"type":"string","description":"When it applies.","x-he":"מתי הוא חל."},"instructions":{"type":"string","description":"The rules.","x-he":"הכללים."},"enabled":{"type":"boolean","description":"Switch it on or off.","x-he":"הפעלה או כיבוי."}}},"example":{"enabled":false}}}},"responses":{"200":{"description":"The updated skill.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"},"example":{"id":"ks1a3c5e7g9j2l4n6q8s0u2w4y6a8c0e","name":"Our CTA","description":"How every video ends","whenToUse":"","instructions":"- The last scene always says “Start free”","enabled":false,"source":"user","status":"ready","origin":null,"error":null,"uses":3,"createdAt":"2026-09-29T09:41:00.000Z","updatedAt":"2026-09-29T09:42:10.000Z"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"deleteSkill","tags":["Skills"],"summary":"Delete a skill","description":"Deletes the skill and any imported source files kept for it.","x-he-summary":"מחיקת סקיל","x-he-description":"מוחק את הסקיל ואת קבצי המקור שנשמרו לו בייבוא.","x-credits":"free","parameters":[{"name":"skillId","in":"path","required":true,"description":"The skill's id.","x-he":"מזהה הסקיל.","schema":{"type":"string"},"example":"ks1a3c5e7g9j2l4n6q8s0u2w4y6a8c0e"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Skill id."},"deleted":{"type":"boolean","description":"Always true."}}},"example":{"id":"ks1a3c5e7g9j2l4n6q8s0u2w4y6a8c0e","deleted":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/skills/import/github":{"post":{"operationId":"importSkillsFromGithub","tags":["Skills"],"summary":"Discover skills in a GitHub repository","description":"Downloads a public repository (or a folder in one) and lists the skills found in it (SKILL.md, README.md and other .md files), with status `found`. Free. Nothing is learned until you call POST /skills/learn with the ids you want.","x-he-summary":"גילוי סקילים ממאגר GitHub","x-he-description":"מוריד מאגר ציבורי (או תיקייה בתוכו) ומחזיר את הסקילים שנמצאו בו (SKILL.md, README.md וקבצי md אחרים) בסטטוס found. חינם. שום דבר לא נלמד עד שקוראים ל-learn עם המזהים שבחרתם.","x-credits":"free","x-mcp-tool":"import_skills_from_github","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"https://github.com/owner/repo, or …/tree/main/some/folder.","format":"uri","x-he":"קישור למאגר, או לתיקייה בתוכו."}},"required":["url"]},"example":{"url":"https://github.com/acme/brand-skills/tree/main/skills"}}}},"responses":{"200":{"description":"What was found.","content":{"application/json":{"schema":{"type":"object","properties":{"discovered":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Skill id."},"name":{"type":"string","description":"Name."},"path":{"type":["string","null"],"description":"Folder in the repository."},"files":{"type":"integer","description":"Files."},"chars":{"type":"integer","description":"Characters."},"status":{"type":"string","description":"found"}}}},"next":{"type":"string","description":"What to do next."}}},"example":{"discovered":[{"id":"ks1a3c5e7g9j2l4n6q8s0u2w4y6a8c0e","name":"brand-voice","path":"skills/brand-voice","files":2,"chars":5320,"status":"found"}],"next":"POST /skills/learn with the ids you want to keep. Discovery is free; learning costs credits."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/skills/learn":{"post":{"operationId":"learnSkills","tags":["Skills"],"summary":"Learn discovered skills","description":"Each chosen skill goes to the model once, which keeps the rules that shape how a video is written, designed, timed and sounds. Poll GET /skills until each one is `ready` (or `failed`, with the reason in `error`).","x-he-summary":"לימוד סקילים","x-he-description":"כל סקיל שבחרתם עובר פעם אחת במודל, שמשאיר את הכללים שמשפיעים על הכתיבה, העיצוב, התזמון והסאונד. בודקים את רשימת הסקילים עד שכל אחד ready (או failed עם הסיבה ב-error).","x-credits":"charged","x-mcp-tool":"learn_skills","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"skillIds":{"type":"array","items":{"type":"string","description":"Skill id."},"description":"Ids of the skills to learn (up to 40), from the import or from GET /skills.","x-he":"מזהי הסקילים ללימוד (עד 40)."},"language":{"type":"string","description":"Language of the learned rules.","enum":["he","en"],"default":"he","x-he":"שפת הכללים שייכתבו."}},"required":["skillIds"]},"example":{"skillIds":["ks1a3c5e7g9j2l4n6q8s0u2w4y6a8c0e"],"language":"en"}}}},"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","properties":{"queued":{"type":"integer","description":"Skills sent to learning."},"data":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}},"poll":{"type":"string","description":"How to follow up."}}},"example":{"queued":1,"data":[{"id":"ks1a3c5e7g9j2l4n6q8s0u2w4y6a8c0e","name":"brand-voice","description":"","whenToUse":"","instructions":"","enabled":false,"source":"github","status":"drafting","origin":{"url":"https://github.com/acme/brand-skills/tree/main/skills","path":"skills/brand-voice","files":2,"chars":5320},"error":null,"uses":0,"createdAt":"2026-09-29T09:41:00.000Z","updatedAt":"2026-09-29T09:41:00.000Z"}],"poll":"GET /skills until each skill's status is ready or failed"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/stock/search":{"get":{"operationId":"searchStock","tags":["Stock library"],"summary":"Search music and sound effects","description":"Searches the licensed stock library that WTFLOW uses for music and effects. Free.","x-he-summary":"חיפוש מוזיקה ואפקטים","x-he-description":"חיפוש בספריית הסטוק המורשית ש-WTFLOW משתמשת בה למוזיקה ולאפקטים. חינם.","x-credits":"free","x-mcp-tool":"search_stock","parameters":[{"name":"type","in":"query","required":true,"description":"music or sfx.","x-he":"music או sfx.","schema":{"type":"string","enum":["music","sfx"]},"example":"music"},{"name":"q","in":"query","required":true,"description":"What to look for, e.g. calm corporate piano.","x-he":"מה לחפש, למשל calm corporate piano.","schema":{"type":"string"},"example":"calm modern electronic"},{"name":"page","in":"query","description":"Page (1-20).","x-he":"עמוד (1 עד 20).","schema":{"type":"integer","minimum":1,"maximum":20,"default":1}}],"responses":{"200":{"description":"Results.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockItem"}}}},"example":{"data":[{"id":"a272dc1b-18ec-4b4b-80db-bed216f2f8f5","title":"Quiet Motion","duration":142,"bpm":100,"tags":["calm","electronic","corporate"],"instrumental":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","tags":["Meta"],"summary":"This document","description":"The OpenAPI 3.1 description of the API. No key needed.","x-he-summary":"המסמך הזה","x-he-description":"תיאור ה-API בפורמט OpenAPI 3.1. לא צריך מפתח.","x-credits":"free","responses":{"200":{"description":"The OpenAPI document.","content":{"application/json":{"schema":{"type":"object"},"example":{"openapi":"3.1.0","info":{"title":"WTFLOW API","version":"1.0.0"}}}}}},"security":[]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"wtf_live_ followed by 32 letters and digits","description":"Create a key at https://www.wtflow-studio.com/developers."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable, machine-readable error code."},"message":{"type":"string","description":"What went wrong, in plain English."}},"required":["code","message"]}},"required":["error"]},"Status":{"type":"object","properties":{"busy":{"type":"boolean","description":"True while a step runs in the background. Poll until it is false."},"step":{"type":["string","null"],"description":"What the project is doing, as shown in the studio (in the project's language)."},"error":{"type":["string","null"],"description":"Why the last step failed, when it did."},"since":{"type":["string","null"],"format":"date-time","description":"When the current step started."}},"required":["busy","step","error","since"]},"Me":{"type":"object","properties":{"id":{"type":"string","description":"Your user id."},"email":{"type":["string","null"],"description":"Account email."},"name":{"type":["string","null"],"description":"Account name."},"balance":{"type":"number","description":"Credits left."},"admin":{"type":"boolean","description":"True for WTFLOW admins."},"plan":{"type":["object","null"],"properties":{"id":{"type":"string","description":"Plan id.","enum":["starter","pro","studio"]},"name":{"type":"string","description":"Plan name."},"status":{"type":"string","description":"Subscription state.","enum":["active","past_due","canceled"]},"interval":{"type":"string","description":"Billing interval. Credits refill monthly on both.","enum":["month","year"]},"creditsPerMonth":{"type":"integer","description":"Credits the plan adds each month."},"periodEnd":{"type":"string","format":"date-time","description":"End of the paid month."},"cancelAtPeriodEnd":{"type":"boolean","description":"True when the plan will not renew."}}},"key":{"type":"object","properties":{"scope":{"type":"string","description":"Key scope.","enum":["user","admin"]},"rateLimitPerMinute":{"type":"integer","description":"Requests allowed per minute with this key."}}}},"required":["id","balance","plan"]},"ProjectSummary":{"type":"object","properties":{"id":{"type":"string","description":"Project id."},"name":{"type":"string","description":"Project name."},"stage":{"type":"string","description":"Where the project stands in the studio.","enum":["research","script","storyboard","editor","review","export"]},"aspect":{"type":"string","description":"Frame format.","enum":["16:9","9:16","1:1"]},"language":{"type":"string","description":"Video language.","enum":["he","en"]},"duration":{"type":["number","null"],"description":"Length of the built video in seconds (null before the build)."},"status":{"$ref":"#/components/schemas/Status"},"reviewStatus":{"type":"string","description":"Review state.","enum":["draft","pending","approved"]},"createdAt":{"type":"string","format":"date-time","description":"Created."},"updatedAt":{"type":"string","format":"date-time","description":"Last change."},"editorUrl":{"type":"string","description":"The project in the WTFLOW editor. Export the MP4 from there.","format":"uri"}},"required":["id","name","stage","status","editorUrl"]},"Brief":{"type":"object","properties":{"url":{"type":["string","null"],"description":"The business website."},"prompt":{"type":"string","description":"What the client asked for."},"videoType":{"type":"string","description":"Kind of video."},"goal":{"type":["string","null"],"description":"Goal of the video."},"audience":{"type":["string","null"],"description":"Who it is for."},"language":{"type":"string","description":"Video language.","enum":["he","en"]},"duration":{"type":"integer","description":"Target length in seconds."},"aspect":{"type":"string","description":"Frame format.","enum":["16:9","9:16","1:1"]},"narration":{"type":"string","description":"auto: the model decides; none: on-screen text only; voice: a voice-over.","enum":["auto","none","voice"]}}},"Claim":{"type":"object","properties":{"text":{"type":"string","description":"The claim."},"source":{"type":"string","description":"URL, \"brief\" or a file name; empty when unknown."},"kind":{"type":"string","description":"fact or assumption","enum":["fact","assumption"]},"confirmed":{"type":"boolean","description":"Confirmed by the client."}},"required":["text","kind"]},"Research":{"type":"object","description":"The business brief. Every claim carries its source; guesses are marked as assumptions.","properties":{"company":{"type":"object","properties":{"name":{"type":"string","description":"Business name."},"oneLiner":{"type":"string","description":"One sentence."},"category":{"type":"string","description":"Category.","enum":["saas","ecommerce","fashion","service","other"]}}},"whatItDoes":{"type":"string","description":"What the business does."},"audience":{"type":"array","items":{"type":"string","description":"A group."}},"problem":{"type":"string","description":"The problem it solves."},"benefits":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"messages":{"type":"array","items":{"type":"string","description":"A message the video can carry."}},"tone":{"type":"object","properties":{"words":{"type":"array","items":{"type":"string","description":"A tone word."}},"description":{"type":"string","description":"Tone in a sentence."}}},"facts":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"assumptions":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"brand":{"type":"object","properties":{"colors":{"type":"array","items":{"type":"string","description":"Hex colour."}},"fonts":{"type":"array","items":{"type":"string","description":"Font family."}},"notes":{"type":"string","description":"Brand notes."}}},"productDetails":{"type":"array","items":{"type":"string","description":"A product detail."}},"questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Open question."},"impact":{"type":"string","description":"What the answer changes."}}}},"summary":{"type":"string","description":"The brief in a paragraph."}}},"Direction":{"type":"object","properties":{"id":{"type":"string","description":"Direction id (d1, d2, …)."},"title":{"type":"string","description":"Title."},"promise":{"type":"string","description":"The promise."},"hook":{"type":"string","description":"Opening hook."},"tone":{"type":"string","description":"Tone."},"motion":{"type":"string","description":"Motion idea."},"cta":{"type":"string","description":"Call to action."},"why":{"type":"string","description":"Why it fits this business."}},"required":["id","title"]},"ScriptScene":{"type":"object","properties":{"id":{"type":"string","description":"Scene id."},"role":{"type":"string","description":"hook, problem, solution, feature, proof, offer, cta or other."},"name":{"type":"string","description":"Scene name."},"duration":{"type":"number","description":"Seconds (1-30)."},"voiceover":{"type":"string","description":"Narration line; empty when the video has no voice."},"onScreenText":{"type":"string","description":"Text on screen."},"visual":{"type":"string","description":"What we see."},"motion":{"type":"string","description":"How it moves."},"assets":{"type":"array","items":{"type":"string","description":"Asset id to use in this scene."}}},"required":["id","name","duration"]},"Script":{"type":"object","properties":{"directionId":{"type":"string","description":"The direction this script follows."},"title":{"type":"string","description":"Title."},"narration":{"type":"object","properties":{"use":{"type":"boolean","description":"True when the video has a voice-over."},"why":{"type":"string","description":"Why."}}},"scenes":{"type":"array","items":{"$ref":"#/components/schemas/ScriptScene"},"description":"Up to 16 scenes."},"musicPrompt":{"type":"string","description":"What to search for in the music library."}},"required":["scenes"]},"Project":{"type":"object","properties":{"id":{"type":"string","description":"Project id."},"name":{"type":"string","description":"Project name."},"stage":{"type":"string","description":"Where the project stands in the studio.","enum":["research","script","storyboard","editor","review","export"]},"aspect":{"type":"string","description":"Frame format.","enum":["16:9","9:16","1:1"]},"language":{"type":"string","description":"Video language.","enum":["he","en"]},"duration":{"type":["number","null"],"description":"Length of the built video in seconds (null before the build)."},"status":{"$ref":"#/components/schemas/Status"},"reviewStatus":{"type":"string","description":"Review state.","enum":["draft","pending","approved"]},"createdAt":{"type":"string","format":"date-time","description":"Created."},"updatedAt":{"type":"string","format":"date-time","description":"Last change."},"editorUrl":{"type":"string","description":"The project in the WTFLOW editor. Export the MP4 from there.","format":"uri"},"next":{"type":"string","description":"The call to make next: run_research, wait, approve_research, choose_direction, approve_script, edit, or retry (run the failed step again).","enum":["run_research","wait","approve_research","choose_direction","approve_script","edit","retry"]},"hasComposition":{"type":"boolean","description":"True once the scenes are built."},"brief":{"$ref":"#/components/schemas/Brief"},"research":{"anyOf":[{"$ref":"#/components/schemas/Research"},{"type":"null"}]},"researchApproved":{"type":"boolean","description":"True after approve."},"sources":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Page."},"title":{"type":"string","description":"Title."},"status":{"type":"string","description":"ok, failed or skipped."},"note":{"type":"string","description":"Why it failed."},"chars":{"type":"integer","description":"Characters read."}}},"description":"What was read from the site."},"directions":{"type":"array","items":{"$ref":"#/components/schemas/Direction"}},"chosenDirection":{"type":["string","null"],"description":"The chosen direction id."},"script":{"anyOf":[{"$ref":"#/components/schemas/Script"},{"type":"null"}]},"scriptApproved":{"type":"boolean","description":"True after approve."}},"required":["id","name","stage","status","next","brief","editorUrl"]},"Composition":{"type":"object","description":"The full scene description the WTFLOW renderer plays. Positions are fractions of the frame (0-1), times are seconds.","properties":{"version":{"type":"integer","description":"Format version (1)."},"aspect":{"type":"string","description":"Frame format."},"fps":{"type":"integer","description":"Frames per second."},"theme":{"type":"object","description":"Colours, fonts, radius and text direction.","properties":{}},"scenes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Scene id."},"name":{"type":"string","description":"Name."},"role":{"type":"string","description":"Role."},"duration":{"type":"number","description":"Seconds."},"background":{"type":"object","properties":{}},"layers":{"type":"array","items":{"type":"object","properties":{}}},"transition":{"type":"object","properties":{}},"voiceover":{"type":"object","properties":{}},"sfx":{"type":"array","items":{"type":"object","properties":{}}},"motion":{"type":"object","description":"Optional animated motion layer (code written by the model).","properties":{}}}}},"music":{"type":"object","description":"The music track from the stock library.","properties":{}},"voiceVolume":{"type":"number","description":"Voice-over volume (0-1)."},"captions":{"type":"boolean","description":"Burn captions into the export."}},"required":["version","aspect","scenes"]},"CompositionResponse":{"type":"object","properties":{"projectId":{"type":"string","description":"Project id."},"revision":{"type":"integer","description":"Increases with every change."},"updatedAt":{"type":"string","format":"date-time","description":"Last change."},"duration":{"type":"number","description":"Seconds."},"composition":{"$ref":"#/components/schemas/Composition"},"editorUrl":{"type":"string","description":"Open to preview and export the MP4.","format":"uri"},"rendering":{"type":"object","properties":{"serverSide":{"type":"boolean","description":"Always false for now."},"message":{"type":"string","description":"How to get the MP4."}}}},"required":["projectId","revision","composition","editorUrl","rendering"]},"Proposal":{"type":"object","properties":{"state":{"type":"string","description":"pending, applied or dismissed.","enum":["pending","applied","dismissed"]},"summary":{"type":"string","description":"What the change does."},"changedScenes":{"type":"array","items":{"type":"string","description":"Scene name."}},"changedLayers":{"type":"array","items":{"type":"string","description":"Layer name."}},"rejected":{"type":"array","items":{"type":"string","description":"A part of the request that could not be applied, and why."}},"mediaCount":{"type":"integer","description":"Paid media jobs (voice, images, video, motion) the change will start."},"opCount":{"type":"integer","description":"Number of operations."},"appliedVersion":{"type":["integer","null"],"description":"Version number once applied."}}},"Message":{"type":"object","properties":{"id":{"type":"string","description":"Message id."},"role":{"type":"string","description":"user or assistant.","enum":["user","assistant"]},"stage":{"type":"string","description":"Stage when it was sent."},"text":{"type":"string","description":"Text."},"pending":{"type":"boolean","description":"True while the assistant is still working on this reply."},"steps":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Step."},"status":{"type":"string","description":"running, done or failed."},"detail":{"type":["string","null"],"description":"Note."}}}},"attachments":{"type":"array","items":{"type":"string","description":"Asset id."}},"proposal":{"anyOf":[{"$ref":"#/components/schemas/Proposal"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","description":"Sent."}},"required":["id","role","text","pending"]},"Job":{"type":"object","properties":{"id":{"type":"string","description":"Job id."},"kind":{"type":"string","description":"llm, image, video, speech, music or sound."},"purpose":{"type":"string","description":"What the job is for (research, directions, script, build, motion, edit, voiceover, …)."},"label":{"type":"string","description":"Human label."},"status":{"type":"string","description":"queued, running, completed, failed or cancelled.","enum":["queued","running","completed","failed","cancelled"]},"progress":{"type":["number","null"],"description":"0-100 when known."},"error":{"type":["string","null"],"description":"Why it failed."},"errorCode":{"type":["string","null"],"description":"Error code."},"credits":{"type":["number","null"],"description":"Credits the job cost."},"createdAt":{"type":"string","format":"date-time","description":"Queued."},"finishedAt":{"type":["string","null"],"format":"date-time","description":"Finished."}},"required":["id","kind","status"]},"Asset":{"type":"object","properties":{"id":{"type":"string","description":"Asset id."},"name":{"type":"string","description":"Name."},"kind":{"type":"string","description":"image, video or audio.","enum":["image","video","audio","model3d"]},"category":{"type":"string","description":"brand, product, image, video, audio or motion."},"origin":{"type":"string","description":"user, site, ai or stock."},"projectId":{"type":["string","null"],"description":"Project it belongs to."},"status":{"type":"string","description":"ready, processing or failed."},"mime":{"type":["string","null"],"description":"MIME type."},"size":{"type":["integer","null"],"description":"Bytes."},"width":{"type":["integer","null"],"description":"Pixels."},"height":{"type":["integer","null"],"description":"Pixels."},"duration":{"type":["number","null"],"description":"Seconds."},"url":{"type":["string","null"],"description":"Download URL (temporary, do not store).","format":"uri"},"createdAt":{"type":"string","format":"date-time","description":"Created."}},"required":["id","name","kind","status"]},"Skill":{"type":"object","properties":{"id":{"type":"string","description":"Skill id."},"name":{"type":"string","description":"Name."},"description":{"type":"string","description":"One sentence."},"whenToUse":{"type":"string","description":"When it applies; empty = always."},"instructions":{"type":"string","description":"The rules."},"enabled":{"type":"boolean","description":"Applied on every model call when true."},"source":{"type":"string","description":"user, ai, upload or github."},"status":{"type":"string","description":"ready, drafting, failed, or found (discovered in an import, not learned yet).","enum":["ready","drafting","failed","found"]},"origin":{"type":["object","null"],"properties":{"url":{"type":["string","null"],"description":"Repository URL."},"path":{"type":["string","null"],"description":"Folder."},"files":{"type":"integer","description":"Files."},"chars":{"type":"integer","description":"Characters."}}},"error":{"type":["string","null"],"description":"Why learning failed."},"uses":{"type":"integer","description":"Times applied."},"createdAt":{"type":"string","format":"date-time","description":"Created."},"updatedAt":{"type":"string","format":"date-time","description":"Last change."}},"required":["id","name","status","enabled"]},"StockItem":{"type":"object","properties":{"id":{"type":"string","description":"Stock id."},"title":{"type":"string","description":"Title."},"duration":{"type":["number","null"],"description":"Seconds."},"bpm":{"type":["number","null"],"description":"Tempo."},"tags":{"type":"array","items":{"type":"string","description":"Mood, genre or tag."}},"instrumental":{"type":["boolean","null"],"description":"True for instrumental music."}}}},"responses":{"BadRequest":{"description":"The input is missing a field or has the wrong type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"`prompt` must be a string."}}}}},"Unauthorized":{"description":"No key, or the key is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"The API key is not valid. It may have been revoked."}}}}},"PaymentRequired":{"description":"Not enough credits to start this step.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits for this step. Choose a plan or redeem a gift code, then try again."}}}}},"Forbidden":{"description":"The key's plan does not include the API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"plan_required","message":"API and MCP access is part of the Pro and Studio plans: https://www.wtflow-studio.com/pricing"}}}}},"NotFound":{"description":"No such resource, or it belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Project was not found."}}}}},"Conflict":{"description":"The project is not in a state that allows this call yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"project_busy","message":"The project is still working on \"Reading the website\". Poll GET /projects/{id} until status.busy is false."}}}}},"RateLimited":{"description":"More than 60 requests in a minute with this key. Wait for Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many requests: the limit is 60 a minute per key."}}}}}}}}