{"openapi":"3.1.0","info":{"title":"Pekto Developer API","version":"1.0.0","description":"Generate editable presentations and LinkedIn/Instagram carousels, read and edit projects, browse templates and brand kits, and schedule social posts."},"servers":[{"url":"https://fwpvfpysaskvlxgwcaxk.supabase.co/functions/v1/api-v1","description":"Production Pekto Developer API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Pekto API key (pekto_live_...), an OAuth 2.1 access token from Pekto sign-in (used by MCP clients), or a Pekto user session token."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"details":{"type":"object"}}}}},"Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"template_id":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","published","archived"]},"thumbnail_url":{"type":"string","nullable":true},"aspect_ratio":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"content":{"type":"object","description":"Document slide content when requested"}}},"PresentationPlanInput":{"type":"object","properties":{"topic":{"type":"string","description":"Topic or title for the presentation"},"content":{"type":"string","description":"Source text, meeting notes, or article content to convert into slides"},"instructions":{"type":"string","description":"Custom design or tone instructions for the slides"},"slide_count":{"type":"integer","minimum":1,"maximum":30,"description":"Number of slides to generate"},"language":{"type":"string","default":"English","description":"Target language for the presentation"},"aspect_ratio":{"type":"string","enum":["16:9","4:5","1:1","9:16","4:3"],"default":"16:9"},"include_stock_images":{"type":"boolean","default":false},"use_web_search":{"type":"boolean","default":false}}},"CreatePresentationInput":{"type":"object","properties":{"title":{"type":"string","maxLength":180,"description":"Optional project title"},"topic":{"type":"string","description":"Topic or working title for the presentation"},"content":{"type":"string","description":"Source text, article, notes, or report content"},"instructions":{"type":"string","description":"Audience, tone, or visual direction"},"slide_count":{"type":"integer","minimum":3,"maximum":30,"default":8,"description":"Presentations: 3–20 slides. Carousels: 3–30 slides (Instagram itself accepts at most 20)."},"language":{"type":"string","default":"Auto"},"format":{"type":"string","enum":["presentation","carousel"],"default":"presentation","description":"Use carousel for a LinkedIn or Instagram carousel. Pekto plans each slide (hook, tips, steps, stats, takeaway) and gives every slide a layout from one carousel theme that fits what it says."},"template_family":{"type":"string","description":"Optional carousel theme ID (for example carousel37). Valid only when format is carousel; when omitted Pekto picks a theme."},"aspect_ratio":{"type":"string","enum":["16:9","4:3","4:5"],"default":"16:9","description":"Carousel generation always uses the selected family’s native 4:5 geometry."},"include_stock_images":{"type":"boolean","default":false},"use_web_search":{"type":"boolean","default":false}},"anyOf":[{"required":["topic"]},{"required":["content"]},{"required":["instructions"]}]},"SchedulePostInput":{"type":"object","required":["social_account_id","post_type","caption","scheduled_for"],"properties":{"social_account_id":{"type":"string","format":"uuid","description":"ID of connected social account"},"post_type":{"type":"string","enum":["text","image","document"],"default":"text"},"caption":{"type":"string","description":"Post commentary text"},"scheduled_for":{"type":"string","format":"date-time","description":"ISO 8601 schedule date/time"},"media_urls":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Files you uploaded to Pekto: scheduled-media paths (<user_id>/file.pdf) or their public URLs. Required for image and document posts."}}},"ScheduledPostInput":{"type":"object","required":["social_account_id","post_type","caption","scheduled_for"],"properties":{"social_account_id":{"type":"string","format":"uuid","description":"ID of connected social account"},"post_type":{"type":"string","enum":["text","image","document"],"default":"text"},"caption":{"type":"string","description":"Post commentary text"},"scheduled_for":{"type":"string","format":"date-time","description":"ISO 8601 schedule date/time"},"media_urls":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Files you uploaded to Pekto: scheduled-media paths (<user_id>/file.pdf) or their public URLs. Required for image and document posts."}}}}},"paths":{"/projects":{"get":{"operationId":"listProjects","summary":"List user projects","description":"Returns the authenticated user’s Pekto design projects with pagination.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Max projects to return"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor from previous response"}],"responses":{"200":{"description":"List of projects with pagination"}}}},"/projects/{project_id}":{"get":{"operationId":"getProject","summary":"Get project details","description":"Retrieve a project by ID. Add ?include=content to retrieve full slide canvas data.","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Project UUID"},{"name":"include","in":"query","schema":{"type":"string","enum":["content"]},"description":"Pass content to include slide JSON/SVG"}],"responses":{"200":{"description":"Project details"}}},"patch":{"operationId":"updateProjectMetadata","summary":"Update a project","description":"Update the title, description or status of a project, patch one slide with patch_slide, or replace the whole document with content (cannot be undone). SVG containing scripts, event handlers or javascript: links is rejected with 400 unsafe_content. Requires projects:write.","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Project UUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":180},"description":{"type":"string","maxLength":2000},"status":{"type":"string","enum":["draft","published","archived"]},"content":{"type":"object","description":"Full document content. Replaces the whole document."},"patch_slide":{"type":"object","properties":{"index":{"type":"integer"},"svg_content":{"type":"string"},"title":{"type":"string"},"notes":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Updated project record"}}},"delete":{"operationId":"deleteProject","summary":"Delete project","description":"Permanently delete an owned project.","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Project UUID"}],"responses":{"200":{"description":"Project deleted confirmation"}}}},"/projects/{project_id}/duplicate":{"post":{"operationId":"duplicateProject","summary":"Duplicate project","description":"Create an independent duplicate of an existing project and return its direct editor URL.","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Source project UUID"}],"responses":{"201":{"description":"Duplicated project with editor_url"}}}},"/account":{"get":{"operationId":"getAccountStatus","summary":"Get account and credits status","description":"Inspect current user credit balance, plan tier, and generation costs.","responses":{"200":{"description":"Account status and remaining credits"}}}},"/templates":{"get":{"operationId":"listTemplates","summary":"Browse design templates","description":"List available Pekto presentation, pitch deck, and carousel templates. Supports filtering by category (presentation, pitch_deck, business, carousel, education), search keywords (e.g. startup, qbr, minimal), and trending status.","parameters":[{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by template category (e.g. presentation, pitch_deck, business, carousel, education, technology, marketing)"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Search term for template name or style (e.g. startup, minimal, qbr, board meeting)"},{"name":"is_trending","in":"query","schema":{"type":"boolean"},"description":"Filter only trending templates when true"},{"name":"limit","in":"query","schema":{"type":"integer","default":50},"description":"Max templates to return"}],"responses":{"200":{"description":"Array of templates"}}}},"/carousel-themes":{"get":{"operationId":"listCarouselThemes","summary":"List carousel themes","description":"The carousel themes Pekto can use, with their ids for the template_family field of POST /presentations. Requires templates:read.","responses":{"200":{"description":"Array of carousel themes: id, name, description, layoutCount"}}}},"/brand-kits":{"get":{"operationId":"listBrandKits","summary":"List user brand kits","description":"Retrieve the user’s brand kits containing logos, fonts, and primary/secondary colors.","responses":{"200":{"description":"Array of brand kits"}}},"post":{"operationId":"createBrandKit","summary":"Create brand kit","description":"Create a new brand identity kit with colors, fonts, and optional logo. Requires brand_kits:write.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kit_name"],"properties":{"kit_name":{"type":"string","maxLength":100},"brand_name":{"type":"string","maxLength":100},"brand_tagline":{"type":"string","maxLength":200},"brand_logo_url":{"type":"string","format":"uri","description":"https URL of the logo image."},"brand_primary_color":{"type":"string"},"brand_secondary_color":{"type":"string"},"brand_accent_color":{"type":"string"},"brand_background_color":{"type":"string"},"brand_font_heading":{"type":"string"},"brand_font_body":{"type":"string"},"is_default":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Created brand kit"}}}},"/brand-kits/{brand_kit_id}":{"delete":{"operationId":"deleteBrandKit","summary":"Delete brand kit","description":"Permanently remove a user brand kit. Requires brand_kits:write.","parameters":[{"name":"brand_kit_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Brand kit UUID"}],"responses":{"200":{"description":"Brand kit deleted confirmation"}}}},"/social-accounts":{"get":{"operationId":"listSocialAccounts","summary":"List connected social accounts","description":"List active social media accounts (e.g. LinkedIn) available for scheduling.","responses":{"200":{"description":"Array of connected social accounts"}}}},"/presentation-plans":{"post":{"operationId":"createPresentationPlan","summary":"Start Pekto smart presentation generation","description":"Create a secure generation request and return a Pekto URL. Opening that URL runs Pekto’s native outline, smart-template selection, content fitting, theme, and editable-project flow. Clients must not synthesize slide layouts themselves.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresentationPlanInput"}}}},"responses":{"201":{"description":"Created generation request. The job result contains generation_url for the user to open in Pekto."}}}},"/presentations":{"post":{"operationId":"createPresentation","summary":"Generate a finished editable Pekto presentation","description":"Checks and reserves 2.5 credits, generates the complete deck on the server, saves an editable project, and returns its direct editor URL. Failed generations are refunded automatically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePresentationInput"}}}},"responses":{"201":{"description":"Finished presentation project and editor URL"},"402":{"description":"The authenticated user does not have enough credits"}}}},"/jobs/{job_id}":{"get":{"operationId":"getJob","summary":"Check generation job status","description":"Inspect status and results of an async generation job.","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Job UUID"}],"responses":{"200":{"description":"Job record and results"}}}},"/scheduled-posts":{"get":{"operationId":"listScheduledPosts","summary":"List scheduled social posts","description":"List recent scheduled and published posts.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":25},"description":"Max posts to return"}],"responses":{"200":{"description":"Array of scheduled posts"}}},"post":{"operationId":"scheduleSocialPost","summary":"Schedule a social post","description":"Schedule text or media to a connected social account.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulePostInput"}}}},"responses":{"201":{"description":"Created scheduled post"}}}},"/scheduled-posts/{post_id}":{"delete":{"operationId":"deleteScheduledPost","summary":"Delete scheduled post","description":"Cancel and delete an unpublished scheduled post.","parameters":[{"name":"post_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Scheduled post UUID"}],"responses":{"204":{"description":"Post deleted successfully"}}}}}}