canonical: https://jentic.com/apis/habitica.com/habitica

# Habitica API

Habitica is a gamified habit-tracking and task-management platform that turns daily routines into a role-playing game. The API exposes operations for managing user profiles, tasks (habits, dailies, todos, rewards), challenges, parties and guilds, chat, quests, in-game shops, tags, notifications, and webhooks. Agents can score tasks up or down, equip gear, hatch pets, run group quests, and react to chat messages programmatically. The platform is open source and free to use, with REST endpoints returning JSON.

## For AI agents

Score habits and dailies, manage todos and rewards, run group challenges and quests, and trigger Habitica webhooks on behalf of a gamified-productivity user.

## Scope

Does not handle real-money payments, calendar scheduling, or external file storage - use for gamified habit, daily, and todo management within Habitica only.

## Capabilities

- Score habits, dailies, and todos up or down to award gold and experience
- Create, update, and reorder tasks within a user's task list
- Run party and guild quests, including invite, accept, and force-start flows
- Manage challenges with prize gems, member lists, and shared task templates
- Buy gear, hatch pets with eggs and hatching potions, and feed pets food
- Post and like chat messages in groups, parties, and tavern channels
- Register webhooks that fire on task scoring, group chat, and quest activity

## Use cases

### Gamified Habit Coaching Agent

Build an AI accountability coach that scores Habitica habits and dailies on behalf of the user as real-world events occur. The agent listens for triggers (calendar events, fitness app data, journal entries) and calls the score endpoint to award gold and experience for completed routines. Habitica handles the gamification layer - HP loss, level-ups, gear drops - while the agent owns the trigger logic. Setup takes a few hours with the user's API token.

Example prompt: Score the habit with id abc-123 in the positive direction and report the user's new gold and experience totals.

### Party Quest Coordinator

Coordinate multi-player Habitica quests by inviting party members, watching for accept events, and force-starting once a quorum is reached. The quest endpoints expose invite, accept, reject, cancel, abort, and force-start verbs against a group id. This is useful for guild leaders running long-running boss quests and for community managers who run themed event quests.

Example prompt: Invite all members of party 'guild-42' to the Vice Drake quest and force-start it once at least four members have accepted.

### Daily Reset Reporting

Generate end-of-day reports on which dailies the user actually completed, how much HP was lost, and which streaks survived. The agent pulls the user's tasks list filtered by daily type, inspects the completed flag and streak counter, and writes a digest into a journaling tool. Useful for self-reflection workflows and ADHD support agents.

Example prompt: Pull all dailies for the user, list which were completed today versus missed, and report current streak counts for each daily.

### Webhook-Driven Reward Pipeline

Register a Habitica webhook that fires whenever a task is scored, then route those events into an external rewards or notification system. The agent owns webhook registration via the user webhooks endpoint and consumes payloads describing task id, direction, and resulting drops. Integration runs in well under an hour through Jentic.

Example prompt: Create a Habitica webhook of type 'taskActivity' that posts to https://example.com/hooks/habitica and confirm it returns active=true.

### Agent Discovery Through Jentic

AI agents discover Habitica operations by searching Jentic with intents like 'score a habit' or 'invite to party quest' and receive matching operations with their input schemas. The agent loads the schema, fills in the task id and direction, and executes through the Jentic SDK without ever browsing the Habitica wiki. Credentials stay isolated in your Jentic One instance.

Example prompt: Use the Jentic search 'score a habit' to find the Habitica scoring operation, load its schema, and execute it for taskId 'abc-123' with direction 'up'.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/user` | Get the authenticated user's profile and stats |
| POST | `/tasks/user` | Create a new task for the user |
| POST | `/tasks/{taskId}/score/{direction}` | Score a habit, daily, or todo up or down |
| GET | `/tasks/user` | List all tasks owned by the user |
| POST | `/groups/{groupId}/chat` | Post a chat message to a group |
| POST | `/challenges` | Create a new challenge with prize gems |
| POST | `/user/webhooks` | Register a webhook for user events |

## Key resources

- **User** — Read profile, sleep, equip gear, hatch and feed pets, change class, revive, and rebirth
- **Tasks** — Create, update, reorder, score, and manage checklists for habits, dailies, todos, and rewards
- **Tags** — Create, list, update, delete, and attach tags to tasks for organisation
- **Groups** — Manage parties, guilds, and the public tavern, including join, leave, chat, and like operations
- **Challenges** — Create challenges with prize gems, manage members, and clone task templates to participants
- **Quests** — Invite, accept, reject, force-start, abort, and cancel party quests
- **Webhooks** — Register, list, update, and delete user webhooks for task activity, group chat, and quest events

## Why Jentic

- **Setup:** Wiring the Habitica API by hand means setting two separate headers, the x-api-user id and the x-api-key token, on every call and building each task and party request yourself. Through Jentic you install once, import the Habitica API from the API Directory, store the user id and key once, and your agent calls it.
- **Permission scoping:** Habitica puts the task id in the URL path (`/tasks/{taskId}/score/{direction}`), so a rule can pin your agent to one task: it can score or update that task and nothing else. You choose the operations it may call, so actions like creating challenges or deleting tasks are not included unless you add them.
- **Credential handling:** Your Habitica x-api-user id and x-api-key are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'score a habit' or 'post a party chat message', and Jentic returns the matching Habitica operation with its input schema so the agent calls the right endpoint without browsing the Habitica wiki.

## Related APIs

- **ClickUp API** — Team-oriented productivity platform with tasks, docs, and goals and no gamification layer.
- **Asana API** — Sync work tasks from Asana into Habitica as personal todos.
- **Trello API** — Pull cards from a Trello board and create matching Habitica todos.

## FAQ

### What authentication does the Habitica API use?

Habitica uses two API key headers: x-api-user with the user id and x-api-key with the user's API token, both sourced from the Habitica account settings page. Through Jentic, both values stay encrypted in the vault and are injected at execution time, so agents never receive the raw token in their context.

### Can I score habits and dailies with the Habitica API?

Yes. POST `/tasks/{taskId}/score/{direction}` scores any habit, daily, or todo in the up or down direction and returns the resulting gold, experience, HP, and item drops. Negative habits and missed dailies will reduce HP rather than award rewards.

### What are the rate limits for the Habitica API?

Habitica rate-limits requests per user token and returns 429 responses when limits are exceeded. The platform has historically published a limit of around 30 requests per minute per user; check the X-RateLimit-Remaining header on responses for the current allowance and back off when it nears zero.

### How do I register a Habitica webhook through Jentic?

Search Jentic for 'register habitica webhook' to load the POST `/user/webhooks` operation, then execute it with a target URL and a type such as taskActivity, groupChatReceived, or questActivity. Jentic returns the webhook id which you can use later to update or delete it.

### Is the Habitica API free to use?

Yes. Habitica is open source and the API is free for personal use. The platform asks third-party tools to set a User-Agent identifying the integration so the maintainers can contact authors if a tool causes issues.

### Can I run party quests through the API?

Yes. The `/groups/{groupId}/quests`/* endpoints support invite, accept, reject, cancel, abort, force-start, and leave operations. The user calling the endpoint must be a member of the group, and force-start requires being the quest leader or group leader.

### Can I limit what my agent is allowed to do with the Habitica API?

Yes. Because Jentic One is self-hosted, you set the rules that decide which Habitica operations your agent may call, so it can score a task but never create challenges or delete tasks unless you allow those. Habitica puts the task id directly in the URL path, as in POST `/tasks/{taskId}/score/{direction}`, so a rule can pin the agent to a single task and let it score or update only that one. Your x-api-user id and x-api-key are held by your own instance and injected at execution time, never reaching the agent's prompt or context.