{"openapi":"3.1.0","info":{"title":"Suwar API","version":"1.0.0","description":"API publique de Suwar : rendre des modèles (un ou tous leurs formats), tableurs, automatisations (REST hooks pour n8n, Make, Zapier). Clé d’API (Développeurs › Clés API) en jeton Bearer. Les rappels (callback_url) sont signés : X-Suwar-Signature: t=<horodatage>,v1=<HMAC-SHA256(secret des rappels de la clé, \"<t>.<corps>\")>."},"servers":[{"url":"https://suwar.app/api/v1","description":"API v1"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key generated from the Suwar dashboard (Settings → API Keys)"}}},"security":[{"BearerAuth":[]}],"paths":{"/render":{"post":{"summary":"Render a template","description":"Render a template with the given variables and return the output URL. The rendered image/PDF is stored on the server and the URL is returned.","tags":["Render"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["templateId"],"properties":{"templateId":{"type":"string","description":"The template ID to render","example":"clxyz1234567890"},"variables":{"type":"object","description":"Key-value pairs of variable names and their values","example":{"title":"Hello World","subtitle":"Welcome"}},"format":{"type":"string","enum":["png","jpg","webp","pdf"],"default":"png","description":"Output format"},"scale":{"type":"number","default":1,"description":"Scale multiplier (1 = original size, 2 = 2x, etc.)"}}}}}},"responses":{"200":{"description":"Render successful","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"renderId":{"type":"string"},"outputUrl":{"type":"string"},"format":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"}}}}}}}},"400":{"description":"Missing templateId"},"401":{"description":"Invalid or missing API key"},"404":{"description":"Template not found"},"500":{"description":"Render failed"}}}},"/templates/{id}/renders":{"post":{"summary":"Rendre plusieurs formats du modèle en un appel (travail en tâche de fond)","description":"« formats »: \"all\" rend chaque format du modèle ; Suwar prévient `callback_url` à la fin, une seule fois (signé, 5 nouvelles tentatives).","tags":["Rendu"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"formats":{"oneOf":[{"type":"string","enum":["all"]},{"type":"array","items":{"type":"string"}}],"description":"\"all\" ou des noms de formats (post, story…)"},"variables":{"type":"object","additionalProperties":true},"file":{"type":"string","enum":["png","jpg","webp","pdf"],"default":"png"},"callback_url":{"type":"string","format":"uri"}}}}}},"responses":{"202":{"description":"Travail accepté : { job, formats }"},"400":{"description":"Format inconnu ou callback_url invalide"},"404":{"description":"Modèle introuvable"},"423":{"description":"Modèle en attente d’approbation"}}}},"/templates":{"get":{"summary":"Modèles de la clé (identifiant, nom, formats, variables)","tags":["Rendu"],"responses":{"200":{"description":"[{ id, name, width, height, formats, variables }]"}}}},"/datasets":{"get":{"summary":"Tableurs de la clé","tags":["Automatisations"],"responses":{"200":{"description":"[{ id, name, template_id, rows }]"}}}},"/hooks":{"post":{"summary":"S'abonner à un événement (REST hook pour n8n, Make, Zapier)","tags":["Automatisations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","event"],"properties":{"url":{"type":"string","format":"uri"},"event":{"type":"string","enum":["render.completed","render.failed","form.submitted","visual.approved","template.created","template.updated","template.deleted","post.boost_candidate"]},"source":{"type":"string","enum":["n8n","make","zapier","autre"]}}}}}},"responses":{"201":{"description":"{ id, event, secret } : le secret signe X-Suwar-Signature (sha256=…)"}}},"get":{"summary":"Abonnements de la clé","tags":["Automatisations"],"responses":{"200":{"description":"Liste"}}}},"/hooks/{id}":{"delete":{"summary":"Se désabonner","tags":["Automatisations"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Supprimé"}}}},"/datasets/{id}/rows":{"post":{"summary":"Ajouter des lignes à un tableur (« nom de colonne » → valeur)","tags":["Automatisations"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"responses":{"201":{"description":"{ added, total, row_ids }"}}}},"/datasets/{id}/renders":{"post":{"summary":"Rendre un tableur (une ligne = un visuel), en tâche de fond","tags":["Automatisations"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"template_id":{"type":"string","description":"Par défaut, le modèle lié au tableur"},"row_ids":{"type":"array","items":{"type":"string"}},"file":{"type":"string","enum":["png","jpg","webp","pdf"]},"callback_url":{"type":"string","format":"uri"}}}}}},"responses":{"202":{"description":"{ job, rows }"}}}},"/jobs/{id}":{"get":{"summary":"État d'un travail (rendus de plusieurs formats)","tags":["Rendu"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ job, status: queued | running | done | failed, progress, renders }"},"404":{"description":"Travail inconnu ou expiré (30 min après la fin)"}}}},"/render/{templateId}.{format}":{"get":{"summary":"Render and stream a template","description":"Render a template and stream the output directly as a binary file. Variables are passed as query parameters.","tags":["Render"],"parameters":[{"in":"path","name":"templateId","required":true,"schema":{"type":"string"},"description":"The template ID"},{"in":"path","name":"format","required":true,"schema":{"type":"string","enum":["png","jpg","jpeg","webp","pdf"]},"description":"Output format"},{"in":"query","name":"variables","style":"form","explode":true,"schema":{"type":"object","additionalProperties":{"type":"string"}},"description":"Template variables as query params (e.g., ?title=Hello&subtitle=World)"}],"responses":{"200":{"description":"Rendered image/PDF binary stream","content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"Template not found"},"500":{"description":"Render failed"}}}},"/remove-bg":{"post":{"summary":"Remove image backgrounds (batch)","description":"Détourage IA (BiRefNet, GPU). Envoie jusqu'à 10 images en multipart (`files`) ou en JSON (`urls` — URLs publiques). Renvoie pour chaque image l'URL d'un PNG transparent (conservé selon la rétention des rendus, 30 jours par défaut).\n","tags":["Tools"],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"string","format":"binary"}}}}},"application/json":{"schema":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"string"},"example":["https://example.com/photo.jpg"]}}}}}},"responses":{"200":{"description":"PNG transparents générés","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"size":{"type":"integer"},"engine":{"type":"string","example":"birefnet-gpu"}}}},"failed":{"type":"array","items":{"type":"object"}}}}}}}}}}},"tags":[]}