{"openapi":"3.1.0","info":{"title":"diagramkit API","version":"1","description":"Make, change, animate and download diagrams. Full reference: /docs/api.md on diagramkit’s site."},"servers":[{"url":"https://app.learnwithcaret.com/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key (aid_…) from Settings › API."}},"schemas":{"Job":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"title":{"type":["string","null"]},"description":{"type":["string","null"],"description":"What the diagram shows and any assumptions it made."},"version":{"type":"integer","description":"How many versions it has; 0 until the first is made."},"animated":{"type":"boolean"},"progress":{"type":["string","null"]},"image_url":{"type":["string","null"],"format":"uri"},"downloads":{"type":["object","null"],"additionalProperties":{"type":"string","format":"uri"},"description":"png, jpg, svg, pdf, and mp4 and gif when animated."},"error":{"type":["object","null"],"properties":{"type":{"type":"string"},"message":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"applied":{"type":"array","items":{"type":"object"},"description":"Text edits only: the edits made."},"skipped":{"type":"array","items":{"type":"object"},"description":"Text edits only: the edits not made, with a reason."}},"required":["id","status","version","animated","created_at"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"issues":{"type":"array","items":{"type":"string"}}},"required":["type","message"]}}},"Image":{"type":"object","properties":{"name":{"type":"string"},"mime":{"type":"string","enum":["image/png","image/jpeg","image/webp","image/gif"]},"data_base64":{"type":"string","description":"Standard base64 without a data: prefix; up to 6 MB."}},"required":["name","mime","data_base64"]}}},"paths":{"/diagrams":{"post":{"summary":"Make a diagram","operationId":"createDiagram","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"A key used before on this account returns that job instead of making another."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":4000},"images":{"type":"array","maxItems":4,"items":{"$ref":"#/components/schemas/Image"}},"animate":{"type":"boolean","default":false},"wait":{"type":"integer","minimum":0,"maximum":300,"default":0,"description":"Hold the request open until done or this many seconds pass."}}}}}},"responses":{"200":{"description":"The finished job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"202":{"description":"Accepted and still being made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"402":{"description":"no_credits: the balance cannot pay for this request (5 credits a new diagram, 2 a change, 8 an animation). Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List recent diagrams","operationId":"listDiagrams","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"How many."}],"responses":{"200":{"description":"Newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"diagrams":{"type":"array","items":{"type":"object"}}}}}}}}}},"/diagrams/{id}":{"get":{"summary":"Get a job","operationId":"getDiagram","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"wait","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":300,"default":0,"description":"Hold the request open until done or this many seconds pass."},"description":"Answer when the job finishes or after this long."}],"responses":{"200":{"description":"The finished job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"202":{"description":"Accepted and still being made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"402":{"description":"no_credits: the balance cannot pay for this request (5 credits a new diagram, 2 a change, 8 an animation). Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a diagram and every version","operationId":"deleteDiagram","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}}}}},"/diagrams/{id}/revisions":{"post":{"summary":"Ask for a change","operationId":"reviseDiagram","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"A key used before on this account returns that job instead of making another."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":4000},"images":{"type":"array","maxItems":4,"items":{"$ref":"#/components/schemas/Image"}},"wait":{"type":"integer","minimum":0,"maximum":300,"default":0,"description":"Hold the request open until done or this many seconds pass."}}}}}},"responses":{"200":{"description":"The finished job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"202":{"description":"Accepted and still being made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"402":{"description":"no_credits: the balance cannot pay for this request (5 credits a new diagram, 2 a change, 8 an animation). Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/diagrams/{id}/animate":{"post":{"summary":"Animate a diagram","operationId":"animateDiagram","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"A key used before on this account returns that job instead of making another."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":1000},"wait":{"type":"integer","minimum":0,"maximum":300,"default":0,"description":"Hold the request open until done or this many seconds pass."}}}}}},"responses":{"200":{"description":"The finished job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"202":{"description":"Accepted and still being made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"402":{"description":"no_credits: the balance cannot pay for this request (5 credits a new diagram, 2 a change, 8 an animation). Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/diagrams/{id}/edits":{"post":{"summary":"Change text without the AI","operationId":"editDiagramText","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["edits"],"properties":{"edits":{"type":"array","minItems":1,"maxItems":30,"items":{"type":"object","required":["before","after"],"properties":{"before":{"type":"string","maxLength":600},"after":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"The finished job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"202":{"description":"Accepted and still being made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"402":{"description":"no_credits: the balance cannot pay for this request (5 credits a new diagram, 2 a change, 8 an animation). Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/diagrams/{id}/image.png":{"get":{"summary":"PNG","operationId":"downloadPng","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"device","in":"query","required":false,"schema":{"type":"string","enum":["desktop","phone"],"default":"desktop"},"description":"Which layout: 900 px or 390 px wide."},{"name":"quality","in":"query","required":false,"schema":{"type":"string","enum":["web","high","print"],"default":"web"},"description":"web 1×, high 2×, print 300 dpi at width_in."},{"name":"width_in","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":20,"default":6.5},"description":"Printed width in inches, with quality=print."}],"responses":{"200":{"description":"The file.","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/diagrams/{id}/image.jpg":{"get":{"summary":"JPEG","operationId":"downloadJpeg","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"device","in":"query","required":false,"schema":{"type":"string","enum":["desktop","phone"],"default":"desktop"},"description":"Which layout: 900 px or 390 px wide."},{"name":"quality","in":"query","required":false,"schema":{"type":"string","enum":["web","high","print"],"default":"web"},"description":"web 1×, high 2×, print 300 dpi at width_in."},{"name":"width_in","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":20,"default":6.5},"description":"Printed width in inches, with quality=print."}],"responses":{"200":{"description":"The file.","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/diagrams/{id}/image.svg":{"get":{"summary":"SVG (paid plans)","operationId":"downloadSvg","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"device","in":"query","required":false,"schema":{"type":"string","enum":["desktop","phone"],"default":"desktop"},"description":"Which layout: 900 px or 390 px wide."}],"responses":{"200":{"description":"The file.","content":{"image/svg+xml":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/diagrams/{id}/image.pdf":{"get":{"summary":"PDF (paid plans)","operationId":"downloadPdf","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"device","in":"query","required":false,"schema":{"type":"string","enum":["desktop","phone"],"default":"desktop"},"description":"Which layout: 900 px or 390 px wide."}],"responses":{"200":{"description":"The file.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/diagrams/{id}/animation.mp4":{"get":{"summary":"MP4 of an animated diagram","operationId":"downloadMp4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"quality","in":"query","required":false,"schema":{"type":"string","enum":["low","medium","high"],"default":"medium"},"description":"Resolution and frame rate."},{"name":"size","in":"query","required":false,"schema":{"type":"string","enum":["chat","square","portrait","story","landscape"],"default":"chat"},"description":"The frame the animation is fitted into."}],"responses":{"200":{"description":"The file.","content":{"video/mp4":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/diagrams/{id}/animation.gif":{"get":{"summary":"GIF of an animated diagram","operationId":"downloadGif","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"quality","in":"query","required":false,"schema":{"type":"string","enum":["low","medium","high"],"default":"medium"},"description":"Resolution and frame rate."},{"name":"size","in":"query","required":false,"schema":{"type":"string","enum":["chat","square","portrait","story","landscape"],"default":"chat"},"description":"The frame the animation is fitted into."}],"responses":{"200":{"description":"The file.","content":{"image/gif":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}