API Usage Guidelines

To maintain the best experience for Habitica players, all third-party apps must abide by these rules when making API calls:

Rules for API Calls

• Add a condition that stops automatic calls if the action can no longer be completed, such as running out of Mana when using Skills.
• For automated scripts that run in the background, include a delay of 30 seconds between API calls. This includes POST, PUT, and GET calls.
• All API calls must include an "X-Client" header as described below.
• If your tool will be used by others, its code must be reviewable in a public repository such as GitHub.

X-Client Header

We require all third-party API requests to include an "X-Client" HTTP header with every API request. This header should contain the tool creator's Habitica UserID and name of the tool in the format "UserID-appname". X-Client headers help our team identify tools that may be causing server issues. If your tool is found to be causing problems, you may be rate limited or blocked from making more calls. The team will attempt to contact you if this happens.

Example of a X-Client header: 12345678-90ab-416b-cdef-1234567890ab-AutoCaster

Rate Limiting

All API requests from third-party tools are handled by a rate limiting mechanism to ensure a surge in requests won't result in degraded server performance or outages.

All responses from the API include these HTTP headers:

• X-RateLimit-Limit: the total amount of requests that can be made in a period
• X-RateLimit-Remaining: the number of remaining requests that can be made in the current period
• X-RateLimit-Reset: when the current period will end

When the limit of requests is exceeded, subsequent requests made using the same UserID or IP address will return a 429 Too Many Requests HTTP error. The HTTP header Retry-After will be added to the response, indicating how many seconds to wait before making a new request.