{"openapi":"3.1.0","info":{"title":"OKSign API","version":"0.1.0","description":"E-signature for people and their AI agents. Errors are { code, message, hint }. Send Idempotency-Key on every POST/PUT/PATCH. Signing itself is always done by a person."},"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"oks_live_… API key (Settings → API keys)"}},"schemas":{"Organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"legal_name":{"type":["string","null"]},"plan":{"type":"string"},"role":{"type":"string"}},"required":["id","name","legal_name","plan"]},"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","created_at"]},"Error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"}},"required":["code","message","hint"]},"Envelope":{"type":"object","properties":{"id":{"type":"string","example":"env_k3m9q2x7a8b4c5d6"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","sent","completed","declined","voided","expired"]},"project_id":{"type":["string","null"]},"message":{"type":["string","null"]},"payee":{"$ref":"#/components/schemas/Payee"},"lang":{"type":"string","enum":["ko","en","th"]},"extra_check":{"type":"boolean"},"created_at":{"type":"string"},"sent_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","title","status","project_id","message","payee","lang","extra_check","created_at","sent_at","completed_at"]},"Payee":{"type":["object","null"],"properties":{"bank":{"type":"string","maxLength":120},"branch":{"type":"string","maxLength":120},"holder":{"type":"string","maxLength":200,"description":"Account holder — should equal your organization's legal name"},"number":{"type":"string","maxLength":60},"swift":{"type":"string","maxLength":20},"currency":{"type":"string","minLength":3,"maxLength":3,"example":"KRW"}},"required":["bank","holder","number"],"description":"The only account money for this contract may be paid into. Locked once sent."},"EnvelopeListItem":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"signers":{"type":"object","properties":{"signed":{"type":"number"},"total":{"type":"number"},"waiting":{"type":"array","items":{"type":"string"},"description":"Names whose turn it is"}},"required":["signed","total","waiting"]}},"required":["signers"]}]},"EnvelopeDetail":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"document":{"$ref":"#/components/schemas/Document"},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/Recipient"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/Field"}},"ready":{"type":"object","properties":{"ok":{"type":"boolean"},"problems":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"hint":{"type":"string"}},"required":["code","hint"]}}},"required":["ok","problems"]},"revision":{"type":"number"},"replaces":{"type":["string","null"]},"series":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"revision":{"type":"number"},"status":{"type":"string"},"created_at":{"type":"string"}},"required":["id","revision","status","created_at"]},"description":"All revisions of this contract, oldest first"},"versions":{"type":"number","description":"Document versions (GET …/versions)"},"content":{"description":"Editable contract text when made from a template (PUT …/content)"}},"required":["document","recipients","fields","ready","revision","replaces","series","versions"]}]},"Document":{"type":["object","null"],"properties":{"name":{"type":"string"},"sha256":{"type":"string"},"pages":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"completed_sha256":{"type":["string","null"],"description":"SHA-256 of the signed PDF (GET …/document?version=completed) once everyone has signed"}},"required":["name","sha256","pages","completed_sha256"]},"Recipient":{"type":"object","properties":{"slot":{"type":"number"},"order":{"type":"number"},"role":{"type":"string","enum":["signer","cc"]},"name":{"type":"string"},"email":{"type":"string"},"lang":{"type":"string","enum":["ko","en","th"]},"status":{"type":"string"}},"required":["slot","order","role","name","email","lang","status"]},"Field":{"type":"object","properties":{"id":{"type":"string"},"recipient":{"type":"number"},"type":{"type":"string","enum":["sign","initials","date","text","check"]},"label":{"type":["string","null"]},"page":{"type":"number"},"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"},"required":{"type":"boolean"},"filled":{"type":"boolean"}},"required":["id","recipient","type","label","page","x","y","w","h","required","filled"]},"FieldInput":{"type":"object","properties":{"recipient":{"type":"integer","minimum":1,"maximum":20},"type":{"type":"string","enum":["sign","initials","date","text","check"]},"label":{"type":"string","maxLength":40},"page":{"type":"integer","minimum":1},"x":{"type":"number","minimum":0},"y":{"type":"number","minimum":0},"w":{"type":"number","exclusiveMinimum":0},"h":{"type":"number","exclusiveMinimum":0},"required":{"type":"boolean"}},"required":["recipient","type","page","x","y","w","h"],"description":"x, y = top-left in PDF points (1/72 inch) from the page's top-left corner"},"AuditEvent":{"type":"object","properties":{"seq":{"type":"number"},"type":{"type":"string"},"actor_type":{"type":"string"},"actor_id":{"type":["string","null"]},"ip":{"type":["string","null"]},"data":{},"at":{"type":"string"},"hash":{"type":"string"}},"required":["seq","type","actor_type","actor_id","ip","at","hash"]},"Template":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["standard","saved"]},"category":{"type":"string"},"name":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]},"summary":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]},"roles":{"type":"array","items":{"type":"object","properties":{"label":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]},"short":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]}},"required":["label","short"]}},"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]},"required":{"type":"boolean"},"example":{"type":"string"},"type":{"type":"string"},"none":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"],"description":"What the contract says if left empty"}},"required":["key","label","required"]}},"created_at":{"type":"string"},"body":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"h":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]}},"required":["h"]},{"type":"object","properties":{"p":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]}},"required":["p"]},{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]},"minItems":1,"maxItems":40}},"required":["items"]}]},"description":"The text (GET /templates/{id} only); edit it and send it as body to preview / from-template"}},"required":["id","kind","category","name","summary","roles","variables"]},"FromTemplate":{"type":"object","properties":{"template_id":{"type":"string","example":"sponsorship"},"mode":{"type":"string","enum":["ko","en","ko+en"],"default":"ko","description":"ko, en, or ko+en (bilingual)"},"variables":{"type":"object","additionalProperties":{"type":"string","maxLength":2000},"default":{},"description":"Blanks by key (see the template's variables). a_name, b_address… are each party's details; leave them out and that party fills them when signing.","example":{"event_name":"2027 Music Festival","fee":"KRW 5,000,000","b_name":"Acme Co., Ltd."}},"body":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"h":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]}},"required":["h"]},{"type":"object","properties":{"p":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]}},"required":["p"]},{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]},"minItems":1,"maxItems":40}},"required":["items"]}]},"minItems":1,"maxItems":200,"description":"Edited contract text (blocks as in GET /templates/{id}); default = the template's"},"recipients":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"email":{"type":"string","maxLength":254,"format":"email"},"lang":{"type":"string","enum":["ko","en","th"]},"order":{"type":"integer","minimum":1,"maximum":20,"description":"Signing order. Same number = sign at the same time. Default: list position (one after another)."},"role":{"type":"string","enum":["signer","cc"],"default":"signer","description":"cc = gets the completed PDF, does not sign"}},"required":["name","email"]},"minItems":1,"maxItems":20,"description":"Signers in the template's role order (갑 = 1, 을 = 2), then any cc"},"title":{"type":"string","minLength":1,"maxLength":200},"message":{"type":"string","maxLength":2000},"payee":{"$ref":"#/components/schemas/Payee"},"lang":{"type":"string","enum":["ko","en","th"]},"project_id":{"type":"string"},"extra_check":{"type":"boolean","default":false},"send":{"type":"boolean","default":false,"description":"true = send right away (same rules as POST /send)"},"prefill":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","minLength":1,"maxLength":300},{"type":"boolean"}]},"description":"Fill fields by their label now and lock them (price, tier box…): text, or true/false for a check box. Signers see them filled and cannot change them. Signatures and dates can't be prefilled.","example":{"계약 금액":"10,000,000","KRW":true}},"return_link":{"type":"boolean","default":false,"description":"With send and extra_check: also return the first signers' links (links[]) so your own page can open signing right away. The code still goes to the signer's email, so the link alone cannot sign."},"replaces":{"type":"string","description":"Id of a sent contract this one rewrites (next revision of its series). Sending this one cancels it if still out for signature."},"presign":{"type":"string","description":"Id of a completed standing-signature authorization (standard template \"presign\") that lists this template. The person who signed it is filled in as already signed with that signature and today's date; when the others sign, the contract is complete. Their other fields must be prefilled."}},"required":["template_id","recipients"]},"ContentEdit":{"type":"object","properties":{"mode":{"type":"string","enum":["ko","en","ko+en"]},"values":{"type":"object","additionalProperties":{"type":"string","maxLength":2000},"description":"Blanks by key (see the template's variables). a_name, b_address… are each party's details; leave them out and that party fills them when signing.","example":{"event_name":"2027 Music Festival","fee":"KRW 5,000,000","b_name":"Acme Co., Ltd."}},"body":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"h":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]}},"required":["h"]},{"type":"object","properties":{"p":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]}},"required":["p"]},{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]},"minItems":1,"maxItems":40}},"required":["items"]}]},"minItems":1,"maxItems":200},"name":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]},"note":{"type":"string","maxLength":200,"description":"What changed (shown in the version list)"}}},"Version":{"type":"object","properties":{"n":{"type":"number"},"kind":{"type":"string"},"sha256":{"type":"string"},"pages":{"type":"number"},"note":{"type":["string","null"]},"actor_type":{"type":"string"},"actor":{"type":["string","null"]},"created_at":{"type":"string"},"content":{}},"required":["n","kind","sha256","pages","note","actor_type","actor","created_at"]}},"parameters":{}},"paths":{"/api/v1/me":{"get":{"summary":"Who is calling: the organization, and the person if signed in","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"org":{"$ref":"#/components/schemas/Organization"},"user":{"type":["object","null"],"properties":{"id":{"type":"string"},"email":{"type":"string"}},"required":["id","email"]},"orgs":{"type":"array","items":{"$ref":"#/components/schemas/Organization"}},"usage":{"type":"object","properties":{"month":{"type":"string"},"sent":{"type":"number"},"limit":{"type":"number"}},"required":["month","sent","limit"]}},"required":["org","user","orgs","usage"]}}}}}}},"/api/v1/projects":{"get":{"summary":"List projects (events)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}}}}}},"post":{"summary":"Create a project (event)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"example":"K-Vibe Festa 2027"}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes":{"post":{"summary":"Create a draft envelope","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"message":{"type":"string","maxLength":2000},"payee":{"$ref":"#/components/schemas/Payee"},"lang":{"type":"string","enum":["ko","en","th"],"default":"en"},"project_id":{"type":"string"},"extra_check":{"type":"boolean","default":false}},"required":["title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List envelopes (newest first)","parameters":[{"schema":{"type":"string"},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string","enum":["draft","sent","completed","declined","voided","expired"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"created_at of the last item you have (paging)"},"required":false,"description":"created_at of the last item you have (paging)","name":"before","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EnvelopeListItem"}}}}}}}},"/api/v1/envelopes/{id}":{"patch":{"summary":"Change a draft (title, message, payee, project, extra check)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"message":{"type":"string","maxLength":2000},"payee":{"$ref":"#/components/schemas/Payee"},"lang":{"type":"string","enum":["ko","en","th"],"default":"en"},"project_id":{"type":"string"},"extra_check":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"Get an envelope with document, recipients, fields and what is missing before send","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/{id}/document":{"put":{"summary":"Upload the PDF (body = application/pdf). [[sign:N]] tags become fields.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":200,"default":"document.pdf"},"required":false,"name":"name","in":"query"}],"requestBody":{"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/{id}/recipients":{"put":{"summary":"Set recipients (replaces the list). Position 1 = [[sign:1]].","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"email":{"type":"string","maxLength":254,"format":"email"},"lang":{"type":"string","enum":["ko","en","th"]},"order":{"type":"integer","minimum":1,"maximum":20,"description":"Signing order. Same number = sign at the same time. Default: list position (one after another)."},"role":{"type":"string","enum":["signer","cc"],"default":"signer","description":"cc = gets the completed PDF, does not sign"}},"required":["name","email"]},"minItems":1,"maxItems":20}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/{id}/fields":{"put":{"summary":"Set fields by coordinates (replaces all fields)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FieldInput"},"maxItems":500}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/{id}/send":{"post":{"summary":"Send for signing: freezes the contract (incl. payee) and emails the first signers","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/{id}/void":{"post":{"summary":"Cancel a draft or an envelope out for signature; its signing links stop working","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/{id}/remind":{"post":{"summary":"Email a new link to the signers whose turn it is (at most once an hour)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Reminded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/{id}/events":{"get":{"summary":"Audit trail (hash-chained) and whether the chain is intact","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"intact":{"type":"boolean"},"events":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}}},"required":["intact","events"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/templates":{"get":{"summary":"Standard contracts (gallery) and this organization's saved templates","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}}}}}},"post":{"summary":"Save an envelope as a reusable template (document, fields, roles, payee, message)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"envelope_id":{"type":"string"},"name":{"type":"string","minLength":1,"maxLength":120}},"required":["envelope_id","name"]}}}},"responses":{"201":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/templates/{id}":{"get":{"summary":"One template with its roles and variables (blanks)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/templates/{id}/preview":{"post":{"summary":"Preview a standard contract as PDF with your values (nothing is saved)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["ko","en","ko+en"],"default":"ko"},"variables":{"type":"object","additionalProperties":{"type":"string","maxLength":2000},"default":{},"description":"Blanks by key (see the template's variables). a_name, b_address… are each party's details; leave them out and that party fills them when signing.","example":{"event_name":"2027 Music Festival","fee":"KRW 5,000,000","b_name":"Acme Co., Ltd."}},"body":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"h":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]}},"required":["h"]},{"type":"object","properties":{"p":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]}},"required":["p"]},{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]},"minItems":1,"maxItems":40}},"required":["items"]}]},"minItems":1,"maxItems":200,"description":"Edited text; default = the template's"}}}}}},"responses":{"200":{"description":"PDF","content":{"application/pdf":{"schema":{}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/from-template":{"post":{"summary":"Make a contract from a template in one call (and optionally send it)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FromTemplate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/{id}/content":{"put":{"summary":"Edit a draft contract's text, blanks or language; saves a new version and regenerates the PDF","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentEdit"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/{id}/content/preview":{"post":{"summary":"PDF of a draft contract with unsaved edits (nothing is saved)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentEdit"}}}},"responses":{"200":{"description":"PDF","content":{"application/pdf":{"schema":{}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/{id}/versions":{"get":{"summary":"Every document this envelope has had, newest first (with the contract text for text contracts)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Version"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/{id}/versions/{n}/restore":{"post":{"summary":"Make an old version current again (saved as a new version)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1},"required":true,"name":"n","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/{id}/revise":{"post":{"summary":"Start the next revision of a sent/finished contract as a draft. Sending it cancels the one it replaces if still out for signature.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"201":{"description":"Draft revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/envelopes/{id}/content/ai":{"post":{"summary":"Ask AI to edit a draft contract by instruction. Returns a proposal with a summary; nothing is saved until you PUT …/content","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"instruction":{"type":"string","minLength":2,"maxLength":1000,"example":"후원금 50%는 선급, 나머지는 행사 후 14일 안에 지급으로 바꿔줘"},"content":{"type":"object","properties":{"mode":{"type":"string","enum":["ko","en","ko+en"]},"values":{"type":"object","additionalProperties":{"type":"string","maxLength":2000},"description":"Blanks by key (see the template's variables). a_name, b_address… are each party's details; leave them out and that party fills them when signing.","example":{"event_name":"2027 Music Festival","fee":"KRW 5,000,000","b_name":"Acme Co., Ltd."}},"body":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"h":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]}},"required":["h"]},{"type":"object","properties":{"p":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]}},"required":["p"]},{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"ko":{"type":"string","maxLength":4000},"en":{"type":"string","maxLength":4000}},"required":["ko","en"]},"minItems":1,"maxItems":40}},"required":["items"]}]},"minItems":1,"maxItems":200}},"required":["mode","values","body"],"description":"Unsaved edits from the editor; default = the saved text"}},"required":["instruction"]}}}},"responses":{"200":{"description":"Proposal","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string"},"ops":{"type":"array","items":{}},"content":{}},"required":["summary","ops"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or another organization's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}