{"openapi":"3.1.0","info":{"title":"Guru (BYOK) API","version":"0.1.0","description":"Guru (BYOK) lets an AI assistant read your own Guru data through the Guru API with a key you supply (Guru user email (the API username)). Read-only: 10 tools (get_whoami, list_teams, get_team_stats, list_collections, list_folders, list_folder_items, search_cards, get_card, list_card_versions, list_tag_categories). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-guru.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-guru/docs"},"termsOfService":"https://connectorbay.com/byok-guru/terms"},"servers":[{"url":"https://byok-guru.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-guru/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_whoami":{"post":{"operationId":"get_whoami","summary":"Show the Guru user the credentials belong to, with the team they are on and the type of authentication used. Use for \"Wh","description":"Show the Guru user the credentials belong to, with the team they are on and the type of authentication used. Use for \"Which Guru account am I connected as\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_whoamiArguments","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 Guru teams (id, name, status, creation date); the team id is needed for tags and statistics. Use for \"What is m","description":"List the Guru teams (id, name, status, creation date); the team id is needed for tags and statistics. Use for \"What is my Guru team id\".","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/get_team_stats":{"post":{"operationId":"get_team_stats","summary":"Get a team's card counts: trusted and unverified cards, overall trust score and card totals. Use for \"How many Guru card","description":"Get a team's card counts: trusted and unverified cards, overall trust score and card totals. Use for \"How many Guru cards are unverified\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_id":{"description":"Guru team id (from list_teams).","maxLength":200,"title":"Team Id","type":"string"}},"required":["team_id"],"title":"get_team_statsArguments","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 collections you can access with card, folder and tag counts and default verification interval (collection tokens ar","description":"List collections you can access with card, folder and tag counts and default verification interval (collection tokens are not returned). Use for \"Which Guru collections do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search term for collection names.","title":"Search"},"sort_field":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Field to sort by.","title":"Sort Field"},"sort_dir":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Sort Dir"}},"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/list_folders":{"post":{"operationId":"list_folders","summary":"List folders (first page, about 110) with collection, card count and last modified date, optionally filtered by text or ","description":"List folders (first page, about 110) with collection, card count and last modified date, optionally filtered by text or collection. Use for \"What folders exist in the Support collection of Guru\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search term for folder titles.","title":"Search"},"collection":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Collection id to limit to.","title":"Collection"},"sort_field":{"anyOf":[{"enum":["title","lastModified"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by title or lastModified.","title":"Sort Field"},"sort_order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"description":"ASC or DESC.","title":"Sort Order"}},"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/list_folder_items":{"post":{"operationId":"list_folder_items","summary":"List the cards and sub-folders directly inside one folder (first page, up to 50). Use for \"What is inside this Guru fold","description":"List the cards and sub-folders directly inside one folder (first page, up to 50). Use for \"What is inside this Guru folder\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"folder_id":{"description":"Guru folder id (from list_folders).","maxLength":200,"title":"Folder Id","type":"string"},"card_detail":{"anyOf":[{"enum":["NONE","BASIC","FULL"],"type":"string"},{"type":"null"}],"default":"BASIC","description":"Card detail level: NONE, BASIC or FULL.","title":"Card Detail"}},"required":["folder_id"],"title":"list_folder_itemsArguments","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 cards by text and/or a Guru Query Language filter such as 'lastModified < 7_days_ago'; returns up to 50 metadata ","description":"Search cards by text and/or a Guru Query Language filter such as 'lastModified < 7_days_ago'; returns up to 50 metadata rows without card bodies. Use for \"Which Guru cards changed in the last 7 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_terms":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Text to find in titles and content.","title":"Search Terms"},"query":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Guru Query Language filter, for example lastModified < 7_days_ago.","title":"Query"},"show_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to list archived cards (search_terms is then ignored).","title":"Show Archived"},"max_results":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many cards to return (1 to 50).","title":"Max Results"},"sort_field":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":"lastModified","description":"Sort field, for example lastModified, title, viewCount or lastVerified.","title":"Sort Field"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"asc or desc.","title":"Sort Order"}},"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 card with its HTML content, verification state, collection, tags and owner name. Use for \"Show the content of th","description":"Get one card with its HTML content, verification state, collection, tags and owner name. Use for \"Show the content of this Guru card\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"card_id":{"description":"Guru card id (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_card_versions":{"post":{"operationId":"list_card_versions","summary":"List a card's version history (first page) with modification dates and verification state. Use for \"How often was this G","description":"List a card's version history (first page) with modification dates and verification state. Use for \"How often was this Guru card edited\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"card_id":{"description":"Guru card id.","maxLength":200,"title":"Card Id","type":"string"}},"required":["card_id"],"title":"list_card_versionsArguments","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_tag_categories":{"post":{"operationId":"list_tag_categories","summary":"List a team's tag categories with the tags in each and how many cards use each tag. Use for \"Which tags does my Guru tea","description":"List a team's tag categories with the tags in each and how many cards use each tag. Use for \"Which tags does my Guru team use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_id":{"description":"Guru team id (from list_teams).","maxLength":200,"title":"Team Id","type":"string"}},"required":["team_id"],"title":"list_tag_categoriesArguments","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}}}}