{"openapi":"3.1.0","info":{"title":"Supernotes (BYOK) API","version":"0.1.0","description":"Supernotes (BYOK) lets an AI assistant read your own Supernotes data through the Supernotes API with a key you supply (Supernotes API key). Read-only: 9 tools (get_profile, search_cards, get_card, list_deleted_cards, list_card_comments, list_collections, get_collection, list_tags, list_templates). The BYOK key travels with each request, is used for that one call only and is never stored, logged...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-supernotes.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-supernotes/docs"},"termsOfService":"https://connectorbay.com/byok-supernotes/terms"},"servers":[{"url":"https://byok-supernotes.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-supernotes/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_profile":{"post":{"operationId":"get_profile","summary":"Show the Supernotes account the key belongs to: id, username, name and bio. Use for \"Which Supernotes account is my key ","description":"Show the Supernotes account the key belongs to: id, username, name and bio. Use for \"Which Supernotes account is my key connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_profileArguments","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/search_cards":{"post":{"operationId":"search_cards","summary":"Search or list your Supernotes cards (the API's base card query). Answer is keyed by card id with full card data and mem","description":"Search or list your Supernotes cards (the API's base card query). Answer is keyed by card id with full card data and membership. Use for \"Find my Supernotes cards that mention 'roadmap'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Text to search for in cards.","title":"Search"},"limit":{"anyOf":[{"maximum":25,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Maximum number of cards to return (1 to 25).","title":"Limit"},"parent_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only children of this card id.","title":"Parent Id"},"changed_since":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only cards changed after this ISO 8601 time.","title":"Changed Since"},"sort_ascending":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True for oldest first.","title":"Sort Ascending"}},"title":"search_cardsArguments","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_card":{"post":{"operationId":"get_card","summary":"Get one Supernotes card: title, Markdown text, tags, owner, dates, counts and backlinks. Use for \"Show my Supernotes car","description":"Get one Supernotes card: title, Markdown text, tags, owner, dates, counts and backlinks. Use for \"Show my Supernotes card 6f0e7c5a-0b0a-4d6a-9d3a-0123456789ab\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"card_id":{"description":"Card id (a UUID, from search_cards).","maxLength":200,"title":"Card Id","type":"string"}},"required":["card_id"],"title":"get_cardArguments","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_deleted_cards":{"post":{"operationId":"list_deleted_cards","summary":"List ids of recently deleted Supernotes cards. Use for \"Which Supernotes cards were deleted recently\".","description":"List ids of recently deleted Supernotes cards. Use for \"Which Supernotes cards were deleted recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_deleted_cardsArguments","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_card_comments":{"post":{"operationId":"list_card_comments","summary":"List the comments on a Supernotes card with author id, text and dates. Use for \"What comments are on my Supernotes card ","description":"List the comments on a Supernotes card with author id, text and dates. Use for \"What comments are on my Supernotes card 6f0e7c5a-0b0a-4d6a-9d3a-0123456789ab\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"card_id":{"description":"Card id (a UUID, from search_cards).","maxLength":200,"title":"Card Id","type":"string"}},"required":["card_id"],"title":"list_card_commentsArguments","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_collections":{"post":{"operationId":"list_collections","summary":"List the Supernotes collections you own (saved card filters and built-in views). Use for \"What collections do I have in ","description":"List the Supernotes collections you own (saved card filters and built-in views). Use for \"What collections do I have in Supernotes\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_collectionsArguments","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_collection":{"post":{"operationId":"get_collection","summary":"Get one Supernotes collection with its filter definition. Use for \"Show Supernotes collection c1\".","description":"Get one Supernotes collection with its filter definition. Use for \"Show Supernotes collection c1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"collection_id":{"description":"Collection id (from list_collections).","maxLength":200,"title":"Collection Id","type":"string"}},"required":["collection_id"],"title":"get_collectionArguments","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_tags":{"post":{"operationId":"list_tags","summary":"List all tags known to the Supernotes account. Use for \"Which tags do I use in Supernotes\".","description":"List all tags known to the Supernotes account. Use for \"Which tags do I use in Supernotes\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_tagsArguments","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_templates":{"post":{"operationId":"list_templates","summary":"List the card templates saved in Supernotes with name and Markdown text. Use for \"What Supernotes templates do I have\".","description":"List the card templates saved in Supernotes with name and Markdown text. Use for \"What Supernotes templates do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_templatesArguments","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}}}}