{"openapi":"3.1.0","info":{"title":"Edit Square API","version":"1.0.0","description":"The Edit Square API is used to create videos from a project's templates, along with supporting endpoints for the resources around them.\n\nThis document is published at https://api.editsquare.com/openapi.json."},"servers":[{"url":"https://api.editsquare.com","description":"Production"}],"security":[{"apiKey":[]}],"tags":[{"name":"Renders","description":"A render turns a project into a video file. Create one, then poll it or wait for the webhook."},{"name":"Projects","description":"A project is what someone builds in the editor and what renders are made from. Projects are read-only through the API."},{"name":"Templates","description":"A template is the set of fields a project exposes for filling in when creating a render."},{"name":"Teams","description":"A team owns projects and is what renders are billed to. An API key reaches the teams its owner belongs to, plus every team under an account they administer."},{"name":"Users","description":"The people on a team. `GET /v1/me` resolves the user an API key acts as - the quickest way to see what a key can reach."}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An Edit Square API key, sent as `Authorization: Bearer <key>`. Keys are created per team in the dashboard."}},"schemas":{"RenderList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Render"}},"has_more":{"type":"boolean","example":false,"description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to read the next page. Null on the last page."}},"required":["data","has_more","next_cursor"]},"Render":{"type":"object","properties":{"id":{"type":"string","example":"rend_jh716ctpaqbye9aw64tgkqwtks7gvx7g"},"name":{"type":"string","example":"My New Shiny Render"},"status":{"type":"string","enum":["initializing","ready","queued","processing","finalizing","complete","failed"]},"type":{"type":"string","enum":["local","cloud"]},"project":{"type":"object","properties":{"id":{"type":"string","example":"proj_jd71dcg41pjy7rax1v2h4pvcmd7gtar9"},"team":{"type":"string","example":"team_jn7fw41m8n5jtht7hxsy69tzg97gvef8"}},"required":["id","team"]},"output":{"type":"object","additionalProperties":{"type":"string"},"description":"Signed URLs for the finished video, keyed by variant (the master plus any smaller encodes). Present once the render is complete. The URLs are time-limited.","example":{"master":"https://files.editsquare.com/renders/rend_jh716ctpaqbye9aw64tgkqwtks7gvx7g/master.mp4?signature=..."}},"created_by":{"type":["string","null"],"example":"user_k970b359khfwwny0q8fjah1hc97gtcwm"},"created_at":{"type":"number","example":1748875980},"updated_at":{"type":["number","null"],"example":1748875986}},"required":["id","name","status","type","project","created_by","created_at","updated_at"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","example":"Render not found"}},"required":["error"]},"ProjectList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"has_more":{"type":"boolean","example":false,"description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to read the next page. Null on the last page."}},"required":["data","has_more","next_cursor"]},"Project":{"type":"object","properties":{"id":{"type":"string","example":"proj_jd71dcg41pjy7rax1v2h4pvcmd7gtar9"},"name":{"type":"string","example":"Summer campaign"},"team":{"type":"object","properties":{"id":{"type":"string","example":"team_jn7fw41m8n5jtht7hxsy69tzg97gvef8"},"name":{"type":"string","example":"Brand team"}},"required":["id","name"]},"created_by":{"type":["string","null"],"example":"user_k970b359khfwwny0q8fjah1hc97gtcwm"},"thumbnail_url":{"type":["string","null"],"description":"A signed, time-limited still of the project. Null until one has been rendered."},"created_at":{"type":"number","example":1748875980},"updated_at":{"type":["number","null"],"example":1748875986}},"required":["id","name","team","created_by","thumbnail_url","created_at","updated_at"]},"TemplateList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TemplateSummary"}}},"required":["data"]},"TemplateSummary":{"type":"object","properties":{"id":{"type":"string","example":"tpl_8f2c1d4e6a7b9c0d1e2f3a4b5c6d7e8f"},"name":{"type":"string","example":"Welcome video"},"description":{"type":["string","null"],"example":"One clip per new customer."},"project_id":{"type":"string","example":"proj_jd71dcg41pjy7rax1v2h4pvcmd7gtar9"},"target_composition_id":{"type":"string","example":"comp_4f1f0f7c","description":"The composition this template renders."},"field_count":{"type":"number","example":3}},"required":["id","name","description","project_id","target_composition_id","field_count"]},"Template":{"allOf":[{"$ref":"#/components/schemas/TemplateSummary"},{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/TemplateField"}}},"required":["fields"]}]},"TemplateField":{"type":"object","properties":{"key":{"type":"string","example":"customer_name","description":"The key to use in a render's `values` object."},"label":{"type":["string","null"],"example":"Customer name"},"description":{"type":["string","null"],"example":"Shown on the opening card."},"kind":{"type":"string","example":"control","description":"What the field drives."},"widget":{"type":["string","null"],"example":"text","description":"How the editor renders the input."},"default_value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"example":"Acme","description":"Used when a render omits this key."}},"required":["key","label","description","kind","widget","default_value"]},"TeamList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Team"}}},"required":["data"]},"Team":{"type":"object","properties":{"id":{"type":"string","example":"team_jn7fw41m8n5jtht7hxsy69tzg97gvef8"},"name":{"type":"string","example":"Brand team"},"account_id":{"type":"string","example":"acc_jh716ctpaqbye9aw64tgkqwtks7gvx7g"},"role":{"type":["string","null"],"enum":["admin","member",null],"example":"admin","description":"The caller's role on this team."},"created_at":{"type":"number","example":1748875980}},"required":["id","name","account_id","role","created_at"]},"User":{"type":"object","properties":{"id":{"type":"string","example":"user_k970b359khfwwny0q8fjah1hc97gtcwm"},"email":{"type":["string","null"],"example":"ada@example.com"},"created_at":{"type":"number","example":1748875980}},"required":["id","email","created_at"]},"TeamMemberList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}}},"required":["data"]},"TeamMember":{"allOf":[{"$ref":"#/components/schemas/User"},{"type":"object","properties":{"role":{"type":"string","enum":["admin","member"],"example":"member"},"joined_at":{"type":"number","example":1748875980}},"required":["role","joined_at"]}]}},"parameters":{}},"paths":{"/v1/renders":{"get":{"operationId":"listRenders","summary":"List renders","description":"Lists the renders of one project, newest first.","tags":["Renders"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":60,"example":20,"description":"How many to return. 1–60, 20 by default."},"required":false,"description":"How many to return. 1–60, 20 by default.","name":"limit","in":"query"},{"schema":{"type":"string","description":"The `next_cursor` of the previous page. Omit for the first page."},"required":false,"description":"The `next_cursor` of the previous page. Omit for the first page.","name":"cursor","in":"query"},{"schema":{"type":"string","minLength":1,"example":"proj_j123456789","description":"Project ID"},"required":true,"description":"Project ID","name":"project_id","in":"query"},{"schema":{"type":"string","example":"welcome","description":"Filter by name. Matches are returned by relevance rather than by date."},"required":false,"description":"Filter by name. Matches are returned by relevance rather than by date.","name":"search","in":"query"},{"schema":{"type":"string","enum":["initializing","ready","queued","processing","finalizing","complete","failed"],"example":"complete","description":"Return only renders with this status."},"required":false,"description":"Return only renders with this status.","name":"status","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"example":"desc","description":"Oldest or newest first. Newest by default, and ignored when `search` is set."},"required":false,"description":"Oldest or newest first. Newest by default, and ignored when `search` is set.","name":"order","in":"query"}],"responses":{"200":{"description":"A page of renders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderList"}}}}}},"post":{"operationId":"createRender","summary":"Create a new render","description":"Queues a render of a project. Pass `template_id` and `values` to render the project with a form submission applied; omit both to render it as it stands.","tags":["Renders"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":250},"project_id":{"type":"string","minLength":1},"template_id":{"type":"string"},"values":{"type":"object","additionalProperties":{}}},"required":["name","project_id"]}}}},"responses":{"201":{"description":"Render created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/renders/{id}":{"get":{"operationId":"getRender","summary":"Get a render","description":"Retrieves a single render, including its status and - once complete - the signed URLs of its output.","tags":["Renders"],"parameters":[{"schema":{"type":"string","minLength":1,"example":"rend_j123456789","description":"Render ID"},"required":true,"description":"Render ID","name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the render","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}}}},"404":{"description":"Render not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects":{"get":{"operationId":"listProjects","summary":"List projects","description":"Lists a team's projects, newest first.","tags":["Projects"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":60,"example":20,"description":"How many to return. 1–60, 20 by default."},"required":false,"description":"How many to return. 1–60, 20 by default.","name":"limit","in":"query"},{"schema":{"type":"string","description":"The `next_cursor` of the previous page. Omit for the first page."},"required":false,"description":"The `next_cursor` of the previous page. Omit for the first page.","name":"cursor","in":"query"},{"schema":{"type":"string","minLength":1,"example":"team_jn7fw41m8n5jtht7hxsy69tzg97gvef8","description":"The team whose projects to list."},"required":true,"description":"The team whose projects to list.","name":"team_id","in":"query"},{"schema":{"type":"string","example":"campaign","description":"Filter by name. Matches are returned by relevance rather than by date."},"required":false,"description":"Filter by name. Matches are returned by relevance rather than by date.","name":"search","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"example":"desc","description":"Oldest or newest first. Newest by default, and ignored when `search` is set."},"required":false,"description":"Oldest or newest first. Newest by default, and ignored when `search` is set.","name":"order","in":"query"}],"responses":{"200":{"description":"A page of projects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectList"}}}},"404":{"description":"Team not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{id}":{"get":{"operationId":"getProject","summary":"Get a project","description":"Retrieves a single project.","tags":["Projects"],"parameters":[{"schema":{"type":"string","minLength":1,"example":"proj_jd71dcg41pjy7rax1v2h4pvcmd7gtar9","description":"Project ID"},"required":true,"description":"Project ID","name":"id","in":"path"}],"responses":{"200":{"description":"The project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/templates":{"get":{"operationId":"listTemplates","summary":"List templates","description":"Lists the templates a project exposes, in the order the project defines them.","tags":["Templates"],"parameters":[{"schema":{"type":"string","minLength":1,"example":"proj_jd71dcg41pjy7rax1v2h4pvcmd7gtar9","description":"Project ID"},"required":true,"description":"Project ID","name":"project_id","in":"query"}],"responses":{"200":{"description":"The project's templates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateList"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/templates/{template_id}":{"get":{"operationId":"getTemplate","summary":"Get a template","description":"Retrieves one template, including every field it exposes - the keys a render's `values` object can set.","tags":["Templates"],"parameters":[{"schema":{"type":"string","minLength":1,"example":"tpl_8f2c1d4e6a7b9c0d1e2f3a4b5c6d7e8f","description":"Template ID"},"required":true,"description":"Template ID","name":"template_id","in":"path"},{"schema":{"type":"string","minLength":1,"example":"proj_jd71dcg41pjy7rax1v2h4pvcmd7gtar9","description":"Project ID"},"required":true,"description":"Project ID","name":"project_id","in":"query"}],"responses":{"200":{"description":"The template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"404":{"description":"Template not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/teams":{"get":{"operationId":"listTeams","summary":"List teams","description":"Lists every team this API key can reach.","tags":["Teams"],"responses":{"200":{"description":"The teams the key can reach","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamList"}}}}}}},"/v1/teams/{id}":{"get":{"operationId":"getTeam","summary":"Get a team","description":"Retrieves a single team.","tags":["Teams"],"parameters":[{"schema":{"type":"string","minLength":1,"example":"team_jn7fw41m8n5jtht7hxsy69tzg97gvef8","description":"Team ID"},"required":true,"description":"Team ID","name":"id","in":"path"}],"responses":{"200":{"description":"The team","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Team"}}}},"404":{"description":"Team not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/me":{"get":{"operationId":"getMe","summary":"Get the current user","description":"Resolves the user this API key belongs to.","tags":["Users"],"responses":{"200":{"description":"The user the key acts as","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}}}}},"/v1/users":{"get":{"operationId":"listUsers","summary":"List team members","description":"Lists the members of a team, with each member's role.","tags":["Users"],"parameters":[{"schema":{"type":"string","minLength":1,"example":"team_jn7fw41m8n5jtht7hxsy69tzg97gvef8","description":"The team whose members to list."},"required":true,"description":"The team whose members to list.","name":"team_id","in":"query"}],"responses":{"200":{"description":"The team's members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamMemberList"}}}},"404":{"description":"Team not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/users/{id}":{"get":{"operationId":"getUser","summary":"Get a user","description":"Retrieves a user the caller shares a team with.","tags":["Users"],"parameters":[{"schema":{"type":"string","minLength":1,"example":"user_k970b359khfwwny0q8fjah1hc97gtcwm","description":"User ID"},"required":true,"description":"User ID","name":"id","in":"path"}],"responses":{"200":{"description":"The user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}