{"openapi":"3.1.0","info":{"title":"Slatebox slate API","version":"1","description":"Use a personal access token from Profile → Developer access."},"servers":[{"url":"/api/v1"}],"security":[{"personalToken":[]}],"paths":{"/slates/{shareId}/invite":{"post":{"operationId":"createSlateInvite","summary":"Create an unlisted invitation or update its role","description":"The registered owner explicitly enables an unlisted link. Changing its role keeps the URL. Public boards require the Share dialog. The URL grants access to its holder.","x-required-scope":"slates:share","parameters":[{"in":"path","name":"shareId","required":true,"schema":{"type":"string"}},{"in":"header","name":"Idempotency-Key","description":"Reuse the same key with the same token for retries of one intended write.","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[!-~]+$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["read","comment","edit"]}},"required":["role"],"additionalProperties":false}}}},"responses":{"200":{"description":"An active invitation was updated or replayed.","content":{"application/json":{"schema":{"type":"object","properties":{"shareId":{"type":"string"},"inviteId":{"type":"string","pattern":"^[a-f0-9]{32}$"},"role":{"type":"string","enum":["read","comment","edit"]},"url":{"type":"string","format":"uri"}},"required":["shareId","inviteId","role","url"]}}}},"201":{"description":"A new invitation was created.","content":{"application/json":{"schema":{"type":"object","properties":{"shareId":{"type":"string"},"inviteId":{"type":"string","pattern":"^[a-f0-9]{32}$"},"role":{"type":"string","enum":["read","comment","edit"]},"url":{"type":"string","format":"uri"}},"required":["shareId","inviteId","role","url"]}}}},"400":{"description":"Inspect error.code and error.message.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Inspect error.code and error.message.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Inspect error.code and error.message.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Inspect error.code and error.message.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Public slate, multiple legacy grants, conflicting key or the invitation no longer matches the issued role.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/slates/{shareId}/invite/{inviteId}":{"delete":{"operationId":"revokeSlateInvite","summary":"Withdraw the specified unlisted invitation and make the slate private","description":"Named team grants remain intact. Repeating the original request confirms that exact generation was withdrawn. A different current invitation is never withdrawn by a stale command.","x-required-scope":"slates:share","parameters":[{"in":"path","name":"shareId","required":true,"schema":{"type":"string"}},{"in":"path","name":"inviteId","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{32}$"}},{"in":"header","name":"Idempotency-Key","description":"Reuse the same key with the same token for retries of one intended write.","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[!-~]+$"},"required":true}],"responses":{"200":{"description":"This invitation was withdrawn.","content":{"application/json":{"schema":{"type":"object","properties":{"shareId":{"type":"string"},"inviteId":{"type":"string","pattern":"^[a-f0-9]{32}$"},"revoked":{"const":true}},"required":["shareId","inviteId","revoked"]}}}},"400":{"description":"Inspect error.code and error.message.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Inspect error.code and error.message.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Inspect error.code and error.message.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Inspect error.code and error.message.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Inspect error.code and error.message.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/slates":{"post":{"operationId":"createSlate","summary":"Create a private slate from a brief","description":"Omitting kind creates the original playable decision map. Use kind diagram to create editable native notes and connections from your own steps or a supported source. The registered token owner owns the result.","x-required-scope":"slates:write","parameters":[{"in":"header","name":"Idempotency-Key","description":"Reuse the same key with the same token for retries of one intended write.","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[!-~]+$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"kind":{"const":"map"},"brief":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[^<>\\x00-\\x1f\\x7f]+$","example":"Who can approve a customer refund?"}},"required":["brief"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"diagram"},"source":{"type":"string","enum":["sign-in-outage","call-status","interview-notes","friday-launch"]},"brief":{"type":"string","minLength":1,"maxLength":1200,"description":"Plain text, including multiple lines. Connect two named steps using → or ->. Use up to 24 distinct notes including source notes.","example":"Field report → Support reply"}},"required":["kind","brief"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Replayed original creation.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"shareId":{"type":"string"},"url":{"type":"string","format":"uri"},"workshop":{"$ref":"#/components/schemas/Workshop"}},"required":["shareId","url","workshop"]},{"type":"object","properties":{"shareId":{"type":"string"},"url":{"type":"string","format":"uri"},"diagram":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"nodeCount":{"type":"integer","minimum":0},"nodes":{"type":"array","items":{"type":"object"}},"connections":{"type":"array","items":{"type":"object"}}},"required":["name","description","nodeCount","nodes","connections"]}},"required":["shareId","url","diagram"]}]}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"shareId":{"type":"string"},"url":{"type":"string","format":"uri"},"workshop":{"$ref":"#/components/schemas/Workshop"}},"required":["shareId","url","workshop"]},{"type":"object","properties":{"shareId":{"type":"string"},"url":{"type":"string","format":"uri"},"diagram":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"nodeCount":{"type":"integer","minimum":0},"nodes":{"type":"array","items":{"type":"object"}},"connections":{"type":"array","items":{"type":"object"}}},"required":["name","description","nodeCount","nodes","connections"]}},"required":["shareId","url","diagram"]}]}}}},"409":{"description":"The key belongs to another request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"410":{"description":"The previously created slate is unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"default":{"description":"Inspect error.code and error.message.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/slates/{shareId}":{"parameters":[{"in":"path","name":"shareId","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getSlate","summary":"Read an accessible slate","x-required-scope":"slates:read","parameters":[{"in":"query","name":"include","schema":{"type":"string","enum":["full"]}}],"responses":{"200":{"description":"Current state. Playable maps include summary.workshop. Request include=full for the stored document.","content":{"application/json":{"schema":{"type":"object","properties":{"shareId":{"type":"string"},"summary":{"type":"object","properties":{"workshop":{"$ref":"#/components/schemas/Workshop"}},"required":[]},"slate":{"type":"object"}},"required":["shareId","summary"]}}}},"default":{"description":"Inspect error.code and error.message.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/slates/{shareId}/operations":{"parameters":[{"in":"path","name":"shareId","required":true,"schema":{"type":"string"}}],"post":{"operationId":"applySlateOperations","summary":"Preview or save an edit","x-required-scope":"slates:write","description":"Set dryRun to true to preview. Omitting it writes. Saving a map edit or workshop move requires an Idempotency-Key and the revision read from the board.","parameters":[{"in":"header","name":"Idempotency-Key","description":"Reuse the same key with the same token for retries of one intended write.","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[!-~]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","default":false},"userMessage":{"type":"string"},"plan":{"oneOf":[{"$ref":"#/components/schemas/CanvasPlan"},{"$ref":"#/components/schemas/WorkshopMovePlan"},{"$ref":"#/components/schemas/PresentationOrderPlan"},{"$ref":"#/components/schemas/MapAuthoringPlan"}]}},"required":["plan"]}}}},"responses":{"200":{"description":"Preview or replay.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"dryRun":{"type":"boolean"},"shareId":{"type":"string"},"message":{"type":"string"},"operations":{"type":"array","items":{"type":"object"}},"report":{"type":"object","properties":{"presentationOrder":{"type":"array","minItems":2,"maxItems":5,"uniqueItems":true,"items":{"type":"string","minLength":1},"description":"All lane or station IDs exactly once, in presentation order. Board positions and routes stay intact."},"addedBranches":{"type":"array","items":{"type":"object","properties":{"fromStationId":{"type":"string"},"stationId":{"type":"string"}},"required":["fromStationId","stationId"]}},"updatedOutcomes":{"type":"array","items":{"type":"object","properties":{"stationId":{"type":"string"}},"required":["stationId"]}}}},"workshop":{"$ref":"#/components/schemas/Workshop"}},"required":["ok","dryRun","shareId","message","operations","report"]}}}},"201":{"description":"Edit saved.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"dryRun":{"type":"boolean"},"shareId":{"type":"string"},"message":{"type":"string"},"operations":{"type":"array","items":{"type":"object"}},"report":{"type":"object","properties":{"presentationOrder":{"type":"array","minItems":2,"maxItems":5,"uniqueItems":true,"items":{"type":"string","minLength":1},"description":"All lane or station IDs exactly once, in presentation order. Board positions and routes stay intact."},"addedBranches":{"type":"array","items":{"type":"object","properties":{"fromStationId":{"type":"string"},"stationId":{"type":"string"}},"required":["fromStationId","stationId"]}},"updatedOutcomes":{"type":"array","items":{"type":"object","properties":{"stationId":{"type":"string"}},"required":["stationId"]}}}},"workshop":{"$ref":"#/components/schemas/Workshop"}},"required":["ok","dryRun","shareId","message","operations","report"]}}}},"default":{"description":"Inspect error.code and error.message.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}}},"components":{"securitySchemes":{"personalToken":{"type":"http","scheme":"bearer"}},"schemas":{"CanvasPlan":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string","description":"A concise, natural response describing exactly what will change. Do not claim an operation that is absent from operations."},"operations":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":true,"properties":{"kind":{"type":"string","enum":["add_nodes","update_nodes","delete_nodes","connect_nodes","disconnect_nodes","update_connections","arrange_nodes","update_slate"]},"count":{"type":"integer","minimum":1,"maximum":20},"shape":{"type":"string","enum":["rectangle","roundedrectangle","ellipse","circle","star","triangle","pentagon","hexagon","octagon","trapezium","parallelogram","rarrow","larrow","diamond"]},"text":{"type":"string"},"ids":{"type":"array","items":{"type":"string"}},"connectionIds":{"type":"array","items":{"type":"string"}},"width":{"type":"number","minimum":20,"maximum":5000},"height":{"type":"number","minimum":20,"maximum":5000},"gap":{"type":"number","minimum":0,"maximum":2000},"style":{"type":"object","additionalProperties":true},"target":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"text":{"type":"string"}},"additionalProperties":false},"placement":{"type":"object","properties":{"relativeTo":{"type":"string"},"direction":{"type":"string","enum":["left","right","above","below","center"]},"arrangement":{"type":"string","enum":["row","column","grid"]},"gap":{"type":"number","minimum":0,"maximum":2000}},"additionalProperties":false},"changes":{"type":"object","additionalProperties":true},"from":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"text":{"type":"string"}},"additionalProperties":false},"to":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"text":{"type":"string"}},"additionalProperties":false},"layout":{"type":"string","enum":["row","column","grid","circle"]}},"required":["kind"]}}},"required":["message","operations"]},"WorkshopMovePlan":{"type":"object","properties":{"message":{"type":"string","minLength":1},"operations":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"kind":{"const":"move_workshop_card"},"cardId":{"type":"string"},"laneId":{"type":"string"},"expectedRevision":{"type":"integer","minimum":0}},"required":["kind","cardId","laneId","expectedRevision"],"additionalProperties":false}}},"required":["message","operations"]},"PresentationOrderPlan":{"type":"object","properties":{"message":{"type":"string","minLength":1},"operations":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"kind":{"const":"set_presentation_order"},"laneIds":{"type":"array","minItems":2,"maxItems":5,"uniqueItems":true,"items":{"type":"string","minLength":1},"description":"All lane or station IDs exactly once, in presentation order. Board positions and routes stay intact."},"expectedRevision":{"type":"integer","minimum":0}},"required":["kind","laneIds","expectedRevision"],"additionalProperties":false}}},"required":["message","operations"]},"MapAuthoringPlan":{"type":"object","properties":{"message":{"type":"string","minLength":1},"operations":{"type":"array","minItems":1,"maxItems":1,"items":{"oneOf":[{"type":"object","properties":{"kind":{"const":"add_map_branch"},"fromStationId":{"type":"string"},"label":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[^<>\\x00-\\x1f]+$"},"outcome":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[^<>\\x00-\\x1f]+$"},"expectedRevision":{"type":"integer","minimum":0}},"required":["kind","fromStationId","label","outcome","expectedRevision"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"update_map_outcome"},"stationId":{"type":"string"},"outcome":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[^<>\\x00-\\x1f]+$"},"expectedRevision":{"type":"integer","minimum":0}},"required":["kind","stationId","outcome","expectedRevision"],"additionalProperties":false}]}}},"required":["message","operations"]},"Workshop":{"type":"object","properties":{"title":{"type":"string"},"presentationOrder":{"type":"array","minItems":2,"maxItems":5,"uniqueItems":true,"items":{"type":"string","minLength":1},"description":"All lane or station IDs exactly once, in presentation order. Board positions and routes stay intact."},"revision":{"type":"integer","minimum":0},"lanes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"capacity":{"type":"integer"},"outcome":{"type":"string"},"next":{"type":"array","items":{"type":"string"}}},"required":["id","label"]}},"cards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"laneId":{"type":"string"},"legalLaneIds":{"type":"array","items":{"type":"string"}}},"required":["id","label","laneId","legalLaneIds"]}},"outcomes":{"type":"array","items":{"type":"object","properties":{"present":{"type":"boolean"},"text":{"type":"string"}},"required":["present","text"]}}},"required":["title","presentationOrder","revision","lanes","cards","outcomes"]}}}}