echolotl.lol backend API thing docs

Status

• GET /spotify

  Gets echolotl's current playing song on Spotify.

  Gets echolotl's current playing song on Spotify.

  Rate Limit

  15 requests over 1 minute

  Returns

  200 OK

  Returns the currently playing song on Spotify, if any.

  Type

  Example

  204 No Content

  Returns if echolotl is not currently playing anything on Spotify.
• GET /status

  Gets echolotl's latest status.

  Gets echolotl's latest status.

  Rate Limit

  15 requests over 2 minutes

  Returns

  200 OK

  Returns the latest status object.

  Example

  204 No Content

  Returns when no status has been set yet. (Which probably means that the database got deleted. Whoops!)
• GET /status/history

  Gets recent status history.

  Gets recent statuses, newest first.

  Query Parameters

  limit (optional number): Number of statuses to return. Defaults to 10.

  Rate Limit

  15 requests over 2 minutes

  Returns

  200 OK

  Returns a list of statuses and the count returned.

  Example

  { "count": 2, "statuses": [ { "text": "sleepy", "emoji": "😴", "createdAt": 1741553075123 }, { "text": "working on the backend api", "emoji": null, "createdAt": 1741553070000 } ] }

  204 No Content

  Returns when no statuses are available.
• POST /status lock

  Sets a new status.

  Creates a new status entry.

  Headers

  Requires an Authorization: Bearer <PASSKEY> header, where PASSKEY matches the server's configured PASSKEY environment variable.

  Body

  {
    "text": "string (1-100 chars)",
    "emoji": "emoji (optional, nullable)"
  }

  Rate Limit

  15 requests over 2 minutes

  Returns

  200 OK

  Returns a confirmation text string with the new status.

  401 Unauthorized

  Missing or invalid Authorization bearer token.

Discord OAuth

Lets you login with Discord for echolotl.lol. This is what will power any authenticated requests.

• GET /auth/discord/

  Starts the Discord login flow.

  Redirects the browser to Discord's OAuth consent screen. Sets a short-lived oauth_state cookie for validation.

  Rate Limit

  20 requests over 1 minute, shared across all Discord auth routes

  Returns

  302 Found

  Redirects to Discord's OAuth authorize page.
• GET /auth/discord/authenticate

  OAuth callback used by Discord.

  This is the redirect_uri configured on the Discord application and it's not meant to be called directly. Discord redirects here with a code and state after the user approves the login.

  This does more additional checks to ensure the Discord account is at least a month old (to mitigate spam), and then saves the Discord user info to the database and sets a session cookie for future authenticated requests.

  Query Parameters

  code (string): Authorization code provided by Discord.
  state (string): Must match the oauth_state cookie set in /auth/discord/.

  Rate Limit

  20 requests over 1 minute, shared across all Discord auth routes

  Returns

  302 Found

  Login succeeded. Redirects to the frontend with a session cookie set.

  400 Bad Request

  Missing or invalid query parameters.

  403 Forbidden

  The Discord account doesn't meet the minimum account age requirement.

  502 Bad Gateway

  Failed to reach Discord's token exchange or user info endpoints.
• GET /auth/discord/logout

  Logs out the current session.

  Destroys the session tied to the session cookie (if any) and clears the cookie.

  Rate Limit

  20 requests over 1 minute, shared across all Discord auth routes

  Returns

  200 OK

  Returns a confirmation text string.

• GET /auth/discord/me

  Gets the currently logged in user.

  Reads the session cookie and returns the associated user as a full user object. This always returns the full user object, even if the user has enabled anonymous mode.

  Rate Limit

  20 requests over 1 minute, shared across all Discord auth routes

  Returns

  200 OK

  Anonymous mode disabled:

  Anonymous mode enabled:

  204 No Content

  Returns if not logged in.
• PATCH /auth/discord/me lock

  Toggles anonymous mode for the current user.

  Requires an active session cookie. Can be used to set the anonymous mode for the current user, and returns a full user object with the updates. This is a non-anonymous object for the same reason as the GET /auth/discord/me endpoint.

  Body

  Rate Limit

  20 requests over 1 minute, shared across all Discord auth routes

  Returns

  200 OK

  Returns the updated user.

  401 Unauthorized

  Returns if not logged in.

  404 Not Found

  Returns if the user no longer exists.
• DELETE /auth/discord/me lock

  Deletes the current user and their data.

  Requires an active session cookie. This will delete the current user and all their data from the database, including their status history.

  Rate Limit

  20 requests over 1 minute, shared across all Discord auth routes

  Returns

  200 OK

  Returns a confirmation text string.

  401 Unauthorized

  Returns if not logged in.

  404 Not Found

  Returns if the user doesn't exist.
• GET /auth/discord/user/:userId

  Looks up a user by their standalone user ID.

  Returns a user object for the given userId. If the user has enabled anonymous mode, this will return a redacted user object with a generic username and display name, and no avatar hash.

  Path Parameters

  userId (string): The user's standalone userId, as returned by /auth/discord/me or itself.

  Rate Limit

  20 requests over 1 minute, shared across all Discord auth routes

  Returns

  200 OK

  Anonymous mode disabled:

  Anonymous mode enabled:

  404 Not Found

  Returns if no user has that userId.