REST API · Version 1

Build with MoodTrue

Access account data, mood insights, privacy-aware social profiles, API usage, and playlists through a consistent JSON API.

Production base URL https://api.moodtrue.com/v1

Start integrating Download OpenAPI

Quickstart

Authenticate every request

Create a developer token in MoodTrue account settings and send it in the standard Bearer authorization header. Tokens must never be included in query strings, client-side source code, or public repositories.

curl https://api.moodtrue.com/v1/user \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Accept: application/json"

JSON by default

Successful responses and errors use JSON. Send Content-Type: application/json when a request has a body.

Secure transport

Use HTTPS for every request. Treat developer tokens like passwords and rotate them immediately if exposed.

Platform policy

Rate limits

Limits are enforced across the authenticated account. Responses expose remaining burst, minute, daily, and monthly capacity through X-RateLimit-* headers. A rejected request returns 429 Too Many Requests with Retry-After.

Plan	Burst	Per minute	Per day	Per month
Free	10 / 10 sec	30	100	2,000
Premium	30 / 10 sec	180	3,000	75,000
Pro	100 / 10 sec	600	20,000	500,000

Response conventions

Predictable errors

{
  "error": "Valid developer token required",
  "code": "AUTH_REQUIRED"
}

400 The request or a parameter is invalid.

401 A valid developer token is required.

403 Privacy settings or permissions deny access.

404 The requested resource does not exist.

429 A rate limit has been reached.

500 The service could not complete the request.

API reference

Endpoints

Open an endpoint and try it from the panel. Every example is ready to copy and uses the production API.

Current user

Account and profile details for the token owner.

GET/v1/user

Get current user

Returns the authenticated user's basic account information.

curl https://api.moodtrue.com/v1/user \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Accept: application/json"

Responses 200 user data · 401 authentication required

GET/v1/user/profile

Get detailed profile

Returns profile details, connected services, subscription state, and developer token information.

curl https://api.moodtrue.com/v1/user/profile \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Accept: application/json"

Responses 200 profile data · 401 authentication required

Moods

Current mood, history, and aggregate statistics.

GET/v1/user/mood

Get current mood

Returns the token owner's current mood, emoji, and available translations.

curl https://api.moodtrue.com/v1/user/mood \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

GET/v1/user/mood/history

List mood history

Returns paginated mood history with optional date filtering.

curl "https://api.moodtrue.com/v1/user/mood/history?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

GET/v1/user/mood/statistics

Get mood statistics

Returns mood distribution and trends for a selected period.

curl "https://api.moodtrue.com/v1/user/mood/statistics?period=monthly&limit=20" \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

Public data with privacy and block rules enforced on every response.

GET/v1/users/{username}

Get a public profile

Returns profile, public counters, relationship state, and applicable privacy flags.

curl https://api.moodtrue.com/v1/users/{username} \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

GET/v1/users/{username}/posts

List public posts

Returns visible posts using cursor pagination.

curl "https://api.moodtrue.com/v1/users/{username}/posts?limit=20" \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

GET/v1/users/{username}/mood

Get a user's visible mood

Returns the current mood only when the requester is permitted to view activity.

curl https://api.moodtrue.com/v1/users/{username}/mood \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

GET/v1/users/{username}/followers

List followers

Returns a privacy-filtered, cursor-paginated list of followers.

curl "https://api.moodtrue.com/v1/users/{username}/followers?limit=20" \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

GET/v1/users/{username}/following

List following

Returns a privacy-filtered, cursor-paginated list of followed accounts.

curl "https://api.moodtrue.com/v1/users/{username}/following?limit=20" \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

POST/v1/users/{username}/follow

Follow a public account

Creates a follow relationship owned by the authenticated token user. Private accounts continue to require approval.

curl -X POST https://api.moodtrue.com/v1/users/{username}/follow \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

DELETE/v1/users/{username}/follow

Unfollow an account

Removes only the authenticated token user's own follow relationship. The console asks for confirmation before sending.

curl -X DELETE https://api.moodtrue.com/v1/users/{username}/follow \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

Usage

Account and token consumption.

GET/v1/usage

Get API usage

Returns token usage and account-wide rate-limit windows.

curl https://api.moodtrue.com/v1/usage \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

Responses 200 usage snapshot · 429 limit reached

Playlists

Read and manage playlists owned by the token user.

GET/v1/playlists

List playlists

Returns every playlist available to the authenticated user.

curl https://api.moodtrue.com/v1/playlists \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

GET/v1/playlists/{id}

Get playlist details

Returns metadata and tracks for a playlist owned by the authenticated user.

curl https://api.moodtrue.com/v1/playlists/{id} \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

DELETE/v1/playlists/{id}

Delete a playlist

Permanently deletes a playlist owned by the authenticated user. The console asks for confirmation before sending.

curl -X DELETE https://api.moodtrue.com/v1/playlists/{id} \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"