{"openapi":"3.1.0","info":{"title":"Kanka (BYOK) API","version":"0.1.0","description":"Kanka (BYOK) lets an AI assistant read your own Kanka data through the Kanka API with a key you supply (Kanka personal access token). Read-only: 12 tools (get_profile, list_campaigns, search_campaign, list_characters, get_character, list_locations, get_location, list_organisations, list_notes, list_quests, list_journals, list_items). The BYOK key travels with each request, is used for that one...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-kanka.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-kanka/docs"},"termsOfService":"https://connectorbay.com/byok-kanka/terms"},"servers":[{"url":"https://byok-kanka.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-kanka/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 Kanka account the token belongs to: name, locale, timezone, subscriber status and the current request rate limi","description":"Show the Kanka account the token belongs to: name, locale, timezone, subscriber status and the current request rate limit. Use for \"Which Kanka account is my token connected to and what is my rate limit\".","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/list_campaigns":{"post":{"operationId":"list_campaigns","summary":"List the Kanka campaigns the token owner can access, with name, locale, visibility and dates. Use for \"Which Kanka campa","description":"List the Kanka campaigns the token owner can access, with name, locale, visibility and dates. Use for \"Which Kanka campaigns do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. Kanka returns 45 records per page for standard accounts (up to 100 for subscribers); meta tells the real page size.","title":"Page"}},"title":"list_campaignsArguments","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_campaign":{"post":{"operationId":"search_campaign","summary":"Search all entities of a campaign (characters, locations, notes, quests and so on) by a word or name. Use for \"Find ever","description":"Search all entities of a campaign (characters, locations, notes, quests and so on) by a word or name. Use for \"Find everything called 'Mordor' in my Kanka campaign\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Numeric id of the Kanka campaign. Find it with list_campaigns.","title":"Campaign Id","type":"integer"},"search_term":{"description":"Text to search for in entity names.","maxLength":200,"title":"Search Term","type":"string"}},"required":["campaign_id","search_term"],"title":"search_campaignArguments","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_characters":{"post":{"operationId":"list_characters","summary":"List a campaign's characters with title, age, sex, races and families (descriptions are left out; use get_character for ","description":"List a campaign's characters with title, age, sex, races and families (descriptions are left out; use get_character for one). Use for \"Who are the characters in my Kanka campaign\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Numeric id of the Kanka campaign. Find it with list_campaigns.","title":"Campaign Id","type":"integer"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. Kanka returns 45 records per page for standard accounts (up to 100 for subscribers); meta tells the real page size.","title":"Page"}},"required":["campaign_id"],"title":"list_charactersArguments","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_character":{"post":{"operationId":"get_character","summary":"Get one character of a campaign including the full HTML description and basic traits. Use for \"Show the character with i","description":"Get one character of a campaign including the full HTML description and basic traits. Use for \"Show the character with id 1 in campaign 12345\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Numeric id of the Kanka campaign. Find it with list_campaigns.","title":"Campaign Id","type":"integer"},"character_id":{"description":"Numeric id of the character inside the campaign. Find it with the matching list tool.","title":"Character Id","type":"integer"}},"required":["campaign_id","character_id"],"title":"get_characterArguments","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_locations":{"post":{"operationId":"list_locations","summary":"List a campaign's locations with title and type (descriptions are left out; use get_location for one). Use for \"What loc","description":"List a campaign's locations with title and type (descriptions are left out; use get_location for one). Use for \"What locations exist in my Kanka campaign\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Numeric id of the Kanka campaign. Find it with list_campaigns.","title":"Campaign Id","type":"integer"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. Kanka returns 45 records per page for standard accounts (up to 100 for subscribers); meta tells the real page size.","title":"Page"}},"required":["campaign_id"],"title":"list_locationsArguments","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_location":{"post":{"operationId":"get_location","summary":"Get one location of a campaign including the full HTML description. Use for \"Describe the location with id 1 in campaign","description":"Get one location of a campaign including the full HTML description. Use for \"Describe the location with id 1 in campaign 12345\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Numeric id of the Kanka campaign. Find it with list_campaigns.","title":"Campaign Id","type":"integer"},"location_id":{"description":"Numeric id of the location inside the campaign. Find it with the matching list tool.","title":"Location Id","type":"integer"}},"required":["campaign_id","location_id"],"title":"get_locationArguments","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_organisations":{"post":{"operationId":"list_organisations","summary":"List a campaign's organisations with type, status and the locations they are linked to. Use for \"Which organisations are","description":"List a campaign's organisations with type, status and the locations they are linked to. Use for \"Which organisations are in my Kanka campaign\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Numeric id of the Kanka campaign. Find it with list_campaigns.","title":"Campaign Id","type":"integer"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. Kanka returns 45 records per page for standard accounts (up to 100 for subscribers); meta tells the real page size.","title":"Page"}},"required":["campaign_id"],"title":"list_organisationsArguments","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 a campaign's notes with type and whether they are pinned (text is left out). Use for \"What notes do I have in my Ka","description":"List a campaign's notes with type and whether they are pinned (text is left out). Use for \"What notes do I have in my Kanka campaign\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Numeric id of the Kanka campaign. Find it with list_campaigns.","title":"Campaign Id","type":"integer"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. Kanka returns 45 records per page for standard accounts (up to 100 for subscribers); meta tells the real page size.","title":"Page"}},"required":["campaign_id"],"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/list_quests":{"post":{"operationId":"list_quests","summary":"List a campaign's quests with type, date and status. Use for \"Which quests are in my Kanka campaign\".","description":"List a campaign's quests with type, date and status. Use for \"Which quests are in my Kanka campaign\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Numeric id of the Kanka campaign. Find it with list_campaigns.","title":"Campaign Id","type":"integer"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. Kanka returns 45 records per page for standard accounts (up to 100 for subscribers); meta tells the real page size.","title":"Page"}},"required":["campaign_id"],"title":"list_questsArguments","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_journals":{"post":{"operationId":"list_journals","summary":"List a campaign's journals (session logs) with type, date and author. Use for \"Show my session journals in the Kanka cam","description":"List a campaign's journals (session logs) with type, date and author. Use for \"Show my session journals in the Kanka campaign\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Numeric id of the Kanka campaign. Find it with list_campaigns.","title":"Campaign Id","type":"integer"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. Kanka returns 45 records per page for standard accounts (up to 100 for subscribers); meta tells the real page size.","title":"Page"}},"required":["campaign_id"],"title":"list_journalsArguments","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_items":{"post":{"operationId":"list_items","summary":"List a campaign's items (objects) with type, price, size, weight and the location they are in. Use for \"What items are r","description":"List a campaign's items (objects) with type, price, size, weight and the location they are in. Use for \"What items are recorded in my Kanka campaign\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Numeric id of the Kanka campaign. Find it with list_campaigns.","title":"Campaign Id","type":"integer"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. Kanka returns 45 records per page for standard accounts (up to 100 for subscribers); meta tells the real page size.","title":"Page"}},"required":["campaign_id"],"title":"list_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}}}}