{"openapi":"3.1.0","info":{"title":"SharpMD API","version":"1.0.0","summary":"Read and write the Markdown notes of a SharpMD account from automated flows.","description":"The same notes the SharpMD app shows, over plain HTTP. Authenticate with a token created in Settings > API and automations (or Settings > AI): the tokens are the ones MCP uses, so a token limited to a folder only reaches that folder, and sharing needs a token created with that permission. Notes of the team space are under @team/. Notes inside a protected folder are encrypted in the browser: they are only reachable while the person has the folder unlocked for the AI.\n\nEvery response is JSON: { \"ok\": true, \"data\": … } or { \"ok\": false, \"error\": { \"code\", \"message\" } }. Each token can make 120 requests per minute; past that the answer is 429 with a Retry-After header.\n\nDocs with examples: https://sharpmd.app/api.html","license":{"name":"AGPL-3.0-or-later","identifier":"AGPL-3.0-or-later"}},"servers":[{"url":"https://sync.sharpmd.app"}],"security":[{"token":[]}],"tags":[{"name":"Notes"},{"name":"Boards","description":"Kanban boards inside a note: columns and cards with attributes."},{"name":"Comments","description":"Comments left for the AI on a note."},{"name":"Sharing","description":"Needs a token created with the sharing permission."},{"name":"Images","description":"Images attached to notes. A note keeps the address of each image, not its content."},{"name":"Inbound","description":"Secret addresses that add to a note without a token."}],"paths":{"/api/v1/me":{"get":{"tags":["Notes"],"operationId":"me","summary":"What this token reaches","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"account":{"type":"string","description":"Opaque id of the account","example":"acc_3f1c9a7b2d4e5f601234"},"plan":{"type":"string"},"scope":{"type":["string","null"],"description":"Folder the token is limited to, or null"},"can_share":{"type":"boolean"},"team":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/notes":{"get":{"tags":["Notes"],"operationId":"listNotes","summary":"List notes, newest first","parameters":[{"name":"folder","in":"query","required":false,"description":"Only the notes inside this folder","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Notes per page, 1 to 200 (50)","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"next_cursor of the previous page","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/NoteRow"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/note":{"get":{"tags":["Notes"],"operationId":"readNote","summary":"Read a note","parameters":[{"name":"path","in":"query","required":true,"description":"Path of the note, for example shop/board.md. Notes of the team space start with @team/.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Note"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"put":{"tags":["Notes"],"operationId":"writeNote","summary":"Create a note or replace its content","description":"POST works the same, for tools that cannot send PUT.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path","text"],"properties":{"path":{"type":"string","example":"shop/board.md"},"text":{"type":"string","description":"Full Markdown content"},"rev":{"type":"integer","minimum":0,"description":"Revision the change was made on. If the note is at another revision the request fails with rev_conflict and nothing is written. Leave it out to write on whatever is there."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Saved"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Notes"],"operationId":"deleteNote","summary":"Move a note to the trash","description":"It stays in the trash for 30 days and can be restored from the app.","parameters":[{"name":"path","in":"query","required":true,"description":"Path of the note, for example shop/board.md. Notes of the team space start with @team/.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"path":{"type":"string"},"trash":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/note/append":{"post":{"tags":["Notes"],"operationId":"appendNote","summary":"Add text at the end of a note","description":"Creates the note if it does not exist.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path","text"],"properties":{"path":{"type":"string"},"text":{"type":"string","description":"Markdown to add"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Saved"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/note/move":{"post":{"tags":["Notes"],"operationId":"moveNote","summary":"Move or rename a note","description":"Its history, comments, shares and public links follow it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Saved"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/folders":{"get":{"tags":["Notes"],"operationId":"listFolders","summary":"List folders with how many notes each one has","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"array","items":{"type":"object","properties":{"folder":{"type":"string"},"notes":{"type":"integer"},"protected":{"type":"boolean"},"locked":{"type":"boolean"},"team":{"type":"boolean"}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/search":{"get":{"tags":["Notes"],"operationId":"search","summary":"Search the text of every note","parameters":[{"name":"q","in":"query","required":true,"description":"Text to look for","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"hits":{"type":"array","items":{"type":"object","properties":{"line":{"type":"integer"},"text":{"type":"string"}}}},"locked":{"type":"boolean"}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/history":{"get":{"tags":["Notes"],"operationId":"history","summary":"Earlier versions of a note","description":"Without version, the list (newest first). With version, the text of that one.","parameters":[{"name":"path","in":"query","required":true,"description":"Path of the note, for example shop/board.md. Notes of the team space start with @team/.","schema":{"type":"string"}},{"name":"version","in":"query","required":false,"description":"Id of the version to read","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"version":{"type":"integer"},"saved":{"type":"string"},"size":{"type":"integer"}}}},{"type":"object","properties":{"path":{"type":"string"},"version":{"type":"integer"},"text":{"type":"string"}}}]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/boards":{"get":{"tags":["Boards"],"operationId":"readBoards","summary":"The boards of a note, as data","parameters":[{"name":"path","in":"query","required":true,"description":"Path of the note, for example shop/board.md. Notes of the team space start with @team/.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"boards":{"type":"array","items":{"$ref":"#/components/schemas/Board"}},"path":{"type":"string"},"rev":{"type":"integer"},"updated":{"type":"string"},"url":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/boards/cards":{"post":{"tags":["Boards"],"operationId":"createCard","summary":"Create a card","description":"The column is created if the board does not have it. The Markdown of the note is rewritten.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path","title"],"properties":{"path":{"type":"string"},"title":{"type":"string","example":"Call the supplier"},"column":{"type":"string","description":"Title of the column. Left out: the first one","example":"To do"},"board":{"type":"integer","description":"Which board of the note, from 0 (0)"},"attrs":{"type":"object","description":"Attributes of the card as key and value. Values are text, numbers or true/false, and are stored as text. null or an empty value removes the attribute. Keys start with a letter and have no spaces; id, created, updated and show are reserved.","additionalProperties":{"type":["string","number","boolean","null"]},"example":{"due":"2026-10-20","owner":"Ana Paz"}},"done":{"type":"boolean"},"position":{"type":"string","enum":["top","bottom"]},"rev":{"type":"integer","minimum":0,"description":"Revision the change was made on. If the note is at another revision the request fails with rev_conflict and nothing is written. Leave it out to write on whatever is there."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/CardResult"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/boards/cards/{id}":{"patch":{"tags":["Boards"],"operationId":"updateCard","summary":"Change a card: title, column, done, attributes","description":"Only what is sent changes. PUT works the same.","parameters":[{"name":"id","in":"path","required":true,"description":"Id of the card, or its ref (board.column.position, for example 0.1.2) when the card has no id yet.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path"],"properties":{"path":{"type":"string"},"title":{"type":"string"},"column":{"type":"string","description":"Move it to this column"},"done":{"type":"boolean"},"attrs":{"type":"object","description":"Attributes of the card as key and value. Values are text, numbers or true/false, and are stored as text. null or an empty value removes the attribute. Keys start with a letter and have no spaces; id, created, updated and show are reserved.","additionalProperties":{"type":["string","number","boolean","null"]},"example":{"due":"2026-10-20","owner":"Ana Paz"}},"position":{"type":"string","enum":["top","bottom"]},"rev":{"type":"integer","minimum":0,"description":"Revision the change was made on. If the note is at another revision the request fails with rev_conflict and nothing is written. Leave it out to write on whatever is there."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/CardResult"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Boards"],"operationId":"deleteCard","summary":"Remove a card","parameters":[{"name":"id","in":"path","required":true,"description":"Id of the card, or its ref (board.column.position, for example 0.1.2) when the card has no id yet.","schema":{"type":"string"}},{"name":"path","in":"query","required":true,"description":"Path of the note, for example shop/board.md. Notes of the team space start with @team/.","schema":{"type":"string"}},{"name":"rev","in":"query","required":false,"description":"Revision the change was made on","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/CardResult"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/boards/cards/{id}/move":{"post":{"tags":["Boards"],"operationId":"moveCard","summary":"Move a card to another column","parameters":[{"name":"id","in":"path","required":true,"description":"Id of the card, or its ref (board.column.position, for example 0.1.2) when the card has no id yet.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path","column"],"properties":{"path":{"type":"string"},"column":{"type":"string","example":"Done"},"position":{"type":"string","enum":["top","bottom"]},"rev":{"type":"integer","minimum":0,"description":"Revision the change was made on. If the note is at another revision the request fails with rev_conflict and nothing is written. Leave it out to write on whatever is there."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/CardResult"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/boards/cards/{id}/done":{"post":{"tags":["Boards"],"operationId":"doneCard","summary":"Mark a card as done","parameters":[{"name":"id","in":"path","required":true,"description":"Id of the card, or its ref (board.column.position, for example 0.1.2) when the card has no id yet.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path"],"properties":{"path":{"type":"string"},"done":{"type":"boolean","default":true},"rev":{"type":"integer","minimum":0,"description":"Revision the change was made on. If the note is at another revision the request fails with rev_conflict and nothing is written. Leave it out to write on whatever is there."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/CardResult"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/comments":{"get":{"tags":["Comments"],"operationId":"listComments","summary":"Open comments","parameters":[{"name":"path","in":"query","required":false,"description":"Only the comments on this note","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Comments"],"operationId":"addComment","summary":"Leave a comment on a note","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path","text"],"properties":{"path":{"type":"string"},"text":{"type":"string","description":"What should change"},"quote":{"type":"string","description":"The passage it refers to"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Comment"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/comments/{id}/resolve":{"post":{"tags":["Comments"],"operationId":"resolveComment","summary":"Mark a comment as done","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"reply":{"type":"string","description":"What was changed"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/shares":{"get":{"tags":["Sharing"],"operationId":"listShares","summary":"Who the notes are shared with, and the public links","parameters":[{"name":"path","in":"query","required":false,"description":"Only this note or folder","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"people":{"type":"array","items":{"type":"object"}},"links":{"type":"array","items":{"type":"object"}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Sharing"],"operationId":"share","summary":"Share a note or a folder with another account","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path","email"],"properties":{"path":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["view","edit"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Message"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Sharing"],"operationId":"unshare","summary":"Stop sharing","parameters":[{"name":"path","in":"query","required":true,"description":"Path of the note, for example shop/board.md. Notes of the team space start with @team/.","schema":{"type":"string"}},{"name":"email","in":"query","required":true,"description":"Address it was shared with","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Message"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/links":{"post":{"tags":["Sharing"],"operationId":"createLink","summary":"Create a read-only public link","description":"The URL is returned once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path"],"properties":{"path":{"type":"string"},"password":{"type":"string","description":"Optional password the reader must type"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"path":{"type":"string"},"url":{"type":"string"},"id":{"type":"integer"},"protected":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Sharing"],"operationId":"revokeLink","summary":"Revoke a public link by id, or every link of a note","parameters":[{"name":"id","in":"query","required":false,"description":"Id of the link","schema":{"type":"integer"}},{"name":"path","in":"query","required":false,"description":"Or the path of the note","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Message"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/files":{"get":{"tags":["Images"],"operationId":"listFiles","summary":"List the attached images and the storage in use","description":"A token limited to a folder only sees the images that the notes of that folder use. Images of protected folders are encrypted and have no public address.","parameters":[{"name":"space","in":"query","required":false,"description":"team for the team space. Leave it out for your own","schema":{"type":"string","enum":["team"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"used":{"type":"integer","description":"Bytes in use"},"max":{"type":"integer","description":"Bytes the plan holds"},"max_file":{"type":"integer","description":"Bytes one image may weigh"},"count":{"type":"integer"},"files":{"type":"array","items":{"$ref":"#/components/schemas/File"}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Images"],"operationId":"uploadFile","summary":"Upload an image","description":"The body is the image itself, not JSON: PNG, JPEG, GIF, WebP or AVIF. The type is read from the first bytes of the file, whatever Content-Type says. The answer carries the address to put in a note, as ![](url). Anyone with that address can see the image. Uploading is part of the paid plan. Limits by default: 10 MB per image and 1 GB, 2 GB per member on a team. Errors: files_need_plan (402), bad_image (415), file_too_large and storage_full (413, with max), upload_slow (408).","parameters":[{"name":"space","in":"query","required":false,"description":"team to upload to the team space","schema":{"type":"string","enum":["team"]}}],"requestBody":{"required":true,"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"image/avif":{"schema":{"type":"string","format":"binary"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","description":"Address of the image"},"type":{"type":"string","example":"image/png"},"size":{"type":"integer"},"markdown":{"type":"string","description":"Ready to paste into a note","example":"![](https://sync.sharpmd.app/f/…)"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"423":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/openapi.json":{"get":{"tags":["Notes"],"operationId":"openapi","summary":"This document","security":[],"responses":{"200":{"description":"OpenAPI 3.1"}}}},"/in/{secret}":{"post":{"tags":["Inbound"],"operationId":"inbound","summary":"Add to a note through an inbound address","security":[],"description":"An inbound address is created in Settings > API and automations. Depending on how it was set up, what arrives is added at the end of a note, becomes a new note in a folder, or becomes a card on a board. It takes text/plain, JSON ({ \"text\", \"title\" }; any other JSON becomes a table of field and value, or a code block if it is nested), application/x-www-form-urlencoded and multipart/form-data (fields become a list; files are skipped). Up to 64 KB and 60 requests per minute. The answer never carries content of the note. GET with ?text= works only if the address allows it.","parameters":[{"name":"secret","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"title":{"type":"string"}},"additionalProperties":true}},"application/x-www-form-urlencoded":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"id":{"type":"string","description":"Id of the card, when the address creates cards"}}}}}},"404":{"description":"No such address"},"413":{"description":"Too large"},"429":{"description":"Too many requests"}}}}},"webhooks":{"event":{"post":{"summary":"What SharpMD sends to the address of an automation","description":"One POST per event, JSON, signed. Header X-SharpMD-Signature: t=<unix seconds>,v1=<hex HMAC-SHA-256 of \"<t>.<raw body>\" with the secret of the automation>. Reject what does not match or carries a timestamp older than five minutes. X-SharpMD-Event carries the type and X-SharpMD-Delivery the id of the event, which repeats on a retry. Answer 2xx within 8 seconds; anything else is retried up to 5 times within an hour. With the Slack or Discord format the body is { \"text\" } or { \"content\" } instead.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Received"}}}}},"components":{"securitySchemes":{"token":{"type":"http","scheme":"bearer","description":"A token that starts with mdt_"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable code: no_auth, bad_auth, api_needs_plan, out_of_scope, not_found, rev_conflict, vault_locked, rate_limited, no_board, card_not_found, bad_attr_key, too_large…","example":"not_found"},"message":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait, on 429"},"rev":{"type":"integer","description":"Current revision, on rev_conflict"}}}}},"Message":{"type":"object","properties":{"message":{"type":"string"}}},"File":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","description":"Address of the image"},"type":{"type":"string","example":"image/webp"},"size":{"type":"integer"},"created":{"type":"string","description":"ISO date"},"encrypted":{"type":"boolean","description":"Encrypted in the browser, in a protected folder"},"in_use":{"type":["boolean","null"],"description":"Whether a note uses it. null when it is encrypted"}}},"NoteRow":{"type":"object","properties":{"path":{"type":"string"},"updated":{"type":"string","description":"ISO date"},"size":{"type":"integer"},"team":{"type":"boolean"},"protected":{"type":"boolean"},"locked":{"type":"boolean"}}},"Saved":{"type":"object","properties":{"path":{"type":"string"},"rev":{"type":"integer"},"updated":{"type":"string"},"size":{"type":"integer"},"url":{"type":"string","description":"Opens the note in the SharpMD app"},"created":{"type":"boolean"},"from":{"type":"string"}}},"Note":{"type":"object","properties":{"path":{"type":"string"},"text":{"type":"string","description":"Markdown"},"rev":{"type":"integer"},"updated":{"type":"string"},"size":{"type":"integer"},"url":{"type":"string"}}},"Card":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable id. null on a card of an older board that was never edited","example":"c8k2m9xq"},"ref":{"type":"string","description":"board.column.position, usable in place of the id","example":"0.0.2"},"title":{"type":"string"},"column":{"type":"string","description":"The status of the card: the title of its column"},"done":{"type":"boolean"},"created":{"type":["string","null"],"description":"ISO date and time"},"updated":{"type":["string","null"],"description":"ISO date and time of the last move or edit"},"attrs":{"type":"object","additionalProperties":{"type":"string"}}}},"Board":{"type":"object","properties":{"index":{"type":"integer"},"show":{"type":"array","items":{"type":"string"},"description":"Attributes shown on the cards"},"fields":{"type":"object","description":"Declared attributes and their type: text, longtext, date, number or select with its options","additionalProperties":{"type":"object","properties":{"type":{"type":"string","enum":["text","date","number","select"]},"options":{"type":"array","items":{"type":"string"}}}}},"columns":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"cards":{"type":"array","items":{"$ref":"#/components/schemas/Card"}}}}}}},"CardResult":{"type":"object","properties":{"card":{"$ref":"#/components/schemas/Card"},"board":{"type":"integer"},"path":{"type":"string"},"rev":{"type":"integer"},"updated":{"type":"string"},"url":{"type":"string"}}},"Comment":{"type":"object","properties":{"id":{"type":"integer"},"path":{"type":"string"},"quote":{"type":"string"},"comment":{"type":"string"},"created":{"type":"string"}}},"Event":{"type":"object","required":["id","type","created","account","note","actor","data"],"properties":{"id":{"type":"string","description":"Id of the event. The same on every retry","example":"evt_Zk3v9Q0aXc81LmPq7RtY"},"type":{"type":"string","enum":["note.created","note.updated","note.deleted","note.restored","note.moved","comment.created","comment.resolved","card.created","card.moved","card.updated","card.done","card.deleted","ping"]},"created":{"type":"string","description":"ISO date and time","example":"2026-10-07T14:03:11Z"},"account":{"type":"string","description":"Opaque id of the account. Never the email address","example":"acc_3f1c9a7b2d4e5f601234"},"note":{"type":["object","null"],"properties":{"path":{"type":"string","example":"shop/board.md"},"name":{"type":"string","example":"board.md"},"url":{"type":"string","description":"Opens the note in the app"},"space":{"type":"string","enum":["own","team"]}}},"actor":{"type":"object","properties":{"type":{"type":"string","enum":["app","api","mcp","inbox","member"]},"id":{"type":"string","description":"For member: an opaque id of the team member","example":"mem_3f1c9a7b2d4e5f60"},"role":{"type":"string","enum":["admin","editor","reader"]},"via":{"type":"string","enum":["app","api","mcp"]}}},"data":{"type":"object","description":"note.created, note.updated: rev, size, updated, and text only if the automation includes the content (up to 64 KB, with truncated). note.moved: from, to. note.deleted: trash. comment.*: comment { id, text, quote | reply }. card.*: card, board, and from/to (card.moved) or changes { key: { from, to } } (card.updated).","additionalProperties":true}}}}}}