{"openapi":"3.1.0","info":{"title":"Habitica (BYOK) API","version":"0.1.0","description":"Habitica (BYOK) lets an AI assistant read your own Habitica data through the Habitica API with a key you supply (Habitica API token). Read-only: 8 tools (get_profile, list_tasks, get_task, list_tags, list_groups, get_group, list_group_members, get_member). 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-habitica.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-habitica/docs"},"termsOfService":"https://connectorbay.com/byok-habitica/terms"},"servers":[{"url":"https://byok-habitica.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-habitica/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 your Habitica character: name, class, level, health, mana, experience and gold. Only the fields named in user_field","description":"Show your Habitica character: name, class, level, health, mana, experience and gold. Only the fields named in user_fields are fetched. Use for \"What level is my Habitica character and how much health do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_fields":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":"profile,stats","description":"Comma-separated user fields to fetch; keep to 'profile,stats' unless more is needed.","title":"User Fields"}},"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_tasks":{"post":{"operationId":"list_tasks","summary":"List your Habitica tasks (habits, dailies, to-dos, rewards), optionally of one type. Completed to-dos need type complete","description":"List your Habitica tasks (habits, dailies, to-dos, rewards), optionally of one type. Completed to-dos need type completedTodos (latest 30). Use for \"What daily tasks and to-dos do I have in Habitica\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"enum":["habits","dailys","todos","rewards","completedTodos"],"type":"string"},{"type":"null"}],"default":null,"description":"Task type: habits, dailys, todos, rewards or completedTodos; omit for all open tasks.","title":"Type"},"due_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Date used to compute nextDue for each task, for example 2026-10-16.","title":"Due Date"}},"title":"list_tasksArguments","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_task":{"post":{"operationId":"get_task","summary":"Get one Habitica task by its id or alias with text, notes, streak, due date and tags. Use for \"Show my Habitica task 'ap","description":"Get one Habitica task by its id or alias with text, notes, streak, due date and tags. Use for \"Show my Habitica task 'apiTrial'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"task_id":{"description":"Task id (UUID) or the alias you gave the task.","maxLength":200,"title":"Task Id","type":"string"}},"required":["task_id"],"title":"get_taskArguments","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 your Habitica tags (id and name) used to organize tasks. Use for \"Which tags do I use in Habitica\".","description":"List your Habitica tags (id and name) used to organize tasks. Use for \"Which tags do I use in Habitica\".","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_groups":{"post":{"operationId":"list_groups","summary":"List your Habitica groups of the given types: party, guilds, privateGuilds, publicGuilds or tavern. Use for \"Which Habit","description":"List your Habitica groups of the given types: party, guilds, privateGuilds, publicGuilds or tavern. Use for \"Which Habitica guilds and party am I in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"description":"Comma-separated group types: party, guilds, privateGuilds, publicGuilds, tavern.","maxLength":200,"title":"Type","type":"string"},"paginate":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"Set true to page public guilds, 30 per page.","title":"Paginate"},"page":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Page number for public guild paging, starting at 0.","title":"Page"}},"required":["type"],"title":"list_groupsArguments","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_group":{"post":{"operationId":"get_group","summary":"Get one Habitica group (party, guild or the Tavern) with its name, summary, privacy, leader and member count. Use for \"T","description":"Get one Habitica group (party, guild or the Tavern) with its name, summary, privacy, leader and member count. Use for \"Tell me about my Habitica party\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"group_id":{"description":"Group id (UUID), or the words 'party' for your party and 'habitrpg' for the Tavern.","maxLength":200,"title":"Group Id","type":"string"}},"required":["group_id"],"title":"get_groupArguments","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_group_members":{"post":{"operationId":"list_group_members","summary":"List members of a Habitica group (id and display name), 30 per request, 60 at most; page with last_id. Use for \"Who is i","description":"List members of a Habitica group (id and display name), 30 per request, 60 at most; page with last_id. Use for \"Who is in my Habitica party\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"group_id":{"description":"Group id (UUID), or the words 'party' for your party and 'habitrpg' for the Tavern.","maxLength":200,"title":"Group Id","type":"string"},"limit":{"anyOf":[{"maximum":60,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many members to return (1 to 60).","title":"Limit"},"last_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Id of the last member of the previous page, to get the next page.","title":"Last Id"}},"required":["group_id"],"title":"list_group_membersArguments","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_member":{"post":{"operationId":"get_member","summary":"Get another Habitica player's public profile: display name, blurb, level and class. Use for \"Show the public Habitica pr","description":"Get another Habitica player's public profile: display name, blurb, level and class. Use for \"Show the public Habitica profile of member 99999999-9999-9999-9999-8f14c101aeff\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"member_id":{"description":"The player's user id (UUID).","maxLength":200,"title":"Member Id","type":"string"}},"required":["member_id"],"title":"get_memberArguments","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}}}}