{"openapi":"3.1.0","info":{"title":"HackMD (BYOK) API","version":"0.1.0","description":"HackMD (BYOK) lets an AI assistant read your own HackMD data through the HackMD API with a key you supply (HackMD API token). Read-only: 9 tools (get_me, list_notes, get_note, list_history, list_teams, list_team_notes, list_folders, get_folder, list_team_folders). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-hackmd.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-hackmd/docs"},"termsOfService":"https://connectorbay.com/byok-hackmd/terms"},"servers":[{"url":"https://byok-hackmd.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-hackmd/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_me":{"post":{"operationId":"get_me","summary":"Show the HackMD user the token belongs to: id, name, email, user path and teams. Use for \"Which HackMD account is my tok","description":"Show the HackMD user the token belongs to: id, name, email, user path and teams. Use for \"Which HackMD account is my token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_meArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_notes":{"post":{"operationId":"list_notes","summary":"List the notes in the token owner's HackMD workspace with title, tags, permissions and timestamps (no content). Use for ","description":"List the notes in the token owner's HackMD workspace with title, tags, permissions and timestamps (no content). Use for \"What are my latest HackMD notes\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_notesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_note":{"post":{"operationId":"get_note","summary":"Get one HackMD note by id including its Markdown content, tags and permissions. Use for \"Show the content of my HackMD n","description":"Get one HackMD note by id including its Markdown content, tags and permissions. Use for \"Show the content of my HackMD note abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"note_id":{"description":"Note id (from list_notes).","maxLength":200,"title":"Note Id","type":"string"}},"required":["note_id"],"title":"get_noteArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_history":{"post":{"operationId":"list_history","summary":"List notes the token owner recently opened in HackMD (reading history). Use for \"Which HackMD notes did I open recently\"","description":"List notes the token owner recently opened in HackMD (reading history). Use for \"Which HackMD notes did I open recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_historyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_teams":{"post":{"operationId":"list_teams","summary":"List the HackMD teams the token owner belongs to with path, visibility and description. Use for \"Which HackMD teams am I","description":"List the HackMD teams the token owner belongs to with path, visibility and description. Use for \"Which HackMD teams am I in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_teamsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_team_notes":{"post":{"operationId":"list_team_notes","summary":"List the notes of a HackMD team workspace (no content). Use for \"What notes does my HackMD team have\".","description":"List the notes of a HackMD team workspace (no content). Use for \"What notes does my HackMD team have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_path":{"description":"Team path (the 'path' value from list_teams), for example 'my-team'.","maxLength":200,"title":"Team Path","type":"string"}},"required":["team_path"],"title":"list_team_notesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_folders":{"post":{"operationId":"list_folders","summary":"List the token owner's personal HackMD folders. Use for \"What folders do I have in HackMD\".","description":"List the token owner's personal HackMD folders. Use for \"What folders do I have in HackMD\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_foldersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_folder":{"post":{"operationId":"get_folder","summary":"Get one personal HackMD folder by id. Use for \"Show HackMD folder f1\".","description":"Get one personal HackMD folder by id. Use for \"Show HackMD folder f1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"folder_id":{"description":"Folder id (from list_folders).","maxLength":200,"title":"Folder Id","type":"string"}},"required":["folder_id"],"title":"get_folderArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_team_folders":{"post":{"operationId":"list_team_folders","summary":"List the folders of a HackMD team workspace. Use for \"What folders does my HackMD team have\".","description":"List the folders of a HackMD team workspace. Use for \"What folders does my HackMD team have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_path":{"description":"Team path (the 'path' value from list_teams), for example 'my-team'.","maxLength":200,"title":"Team Path","type":"string"}},"required":["team_path"],"title":"list_team_foldersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}