Veyra API documentation

Veyra is a Discord presence and profile API for developers who want supported data for users tracked by the Veyra service. It exposes a REST snapshot endpoint, a WebSocket stream, a status JSON endpoint, and a Discord bot command for viewing registered information.

How Veyra works

The implementation tracks non-bot members of the configured Veyra guild. The source defines the guild as 1399305230268760186. On startup, Veyra fetches guild members, adds or updates current members, and removes stored users who are no longer members.

Architecture

About Veyra

Veyra is built and maintained by Lorb (@6lxrb). The official creator website is https://lorbspace.vercel.app.

Official links: Veyra Documentation, Veyra Discord, and Lorb.

Quick start

1. Join the official Veyra Discord at discord.gg/ZTeU5HxznV.
2. Complete the server's required verification.
3. Wait for Veyra to register and track your guild membership. The implementation waits 5 seconds after joining before inserting a new user.
4. Run /info in the Veyra Discord to view your API URL.
5. Make a request to GET /api/user/:userId.

curl https://veyra-db3d.onbelmo.uk/api/user/YOUR_DISCORD_USER_ID

const response = await fetch("https://veyra-db3d.onbelmo.uk/api/user/YOUR_DISCORD_USER_ID");
const body = await response.json();

if (!body.success) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

console.log(body.data.discord_status);
console.log(body.data.discord_user.global_name || body.data.discord_user.username);

type VeyraResponse<T> =
  | { success: true; data: T }
  | { success: false; error: { code: string; message: string } };

const res = await fetch("https://veyra-db3d.onbelmo.uk/api/user/YOUR_DISCORD_USER_ID");
const body = (await res.json()) as VeyraResponse<{ discord_status: string }>;

if (!body.success) throw new Error(body.error.message);
console.log(body.data.discord_status);

import requests

res = requests.get("https://veyra-db3d.onbelmo.uk/api/user/YOUR_DISCORD_USER_ID", timeout=10)
body = res.json()

if not body["success"]:
    raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]}')

print(body["data"]["discord_status"])

Become a tracked user

Veyra can only return supported data for users registered in its database. Registration is created from guild membership, not from arbitrary Discord IDs.

/info command

The Veyra Discord bot registers a guild slash command named /info. It can show information for yourself or another selected user.

The command only works in the Veyra guild. If the command is used outside the guild, the bot replies ephemerally: Veyra only works in the Veyra guild.

Authentication

The public REST API and WebSocket gateway do not require API keys or bearer tokens in the provided implementation. CORS allows any origin for GET and OPTIONS.

The server allows an Authorization header through CORS, but no public route validates it. The internal badge fetcher may use DISCORD_USER_TOKEN server-side; clients never send that token to Veyra.

Rate limits

When the limit is exceeded, Veyra returns 429 with RATE_LIMITED. The implementation enables standard rate-limit headers and disables legacy headers.

Get user

Returns the tracked Discord user's current presence and supported profile information.

{
  "success": true,
  "data": {
    "kv": {},
    "discord_user": {
      "id": "123456789012345678",
      "username": "example",
      "global_name": "Example",
      "display_name": "Example",
      "discriminator": "0",
      "avatar": "avatar_hash",
      "avatar_url": "https://cdn.discordapp.com/avatars/...",
      "avatar_decoration_data": null,
      "banner": null,
      "banner_url": null,
      "accent_color": null,
      "public_flags": 4194304,
      "badges": ["ACTIVE_DEVELOPER"],
      "primary_guild": null
    },
    "activities": [],
    "discord_status": "online",
    "active_on_discord_web": false,
    "active_on_discord_desktop": true,
    "active_on_discord_mobile": false,
    "active_on_discord_embedded": false,
    "active_on_discord_vr": false,
    "listening_to_spotify": false,
    "spotify": null,
    "custom_status": null,
    "guild": {
      "id": "1399305230268760186",
      "nickname": null,
      "joined_at": "2026-01-01T00:00:00.000Z"
    },
    "last_updated": "2026-01-01T00:00:00.000Z",
    "tracked_since": "2026-01-01T00:00:00.000Z"
  }
}

Try it

This explorer calls the live public endpoint from your browser. It does not use credentials.

{}

Health JSON

GET /health serves the human status page. GET /health/json returns machine-readable health data.

WebSocket overview

Connect to wss://veyra-db3d.onbelmo.uk/socket. The server sends a hello payload, then clients subscribe to up to 50 valid Discord snowflakes per initialize message.

const userId = "YOUR_DISCORD_USER_ID";
let heartbeat;

function connect() {
  const ws = new WebSocket("wss://veyra-db3d.onbelmo.uk/socket");

  ws.addEventListener("message", (event) => {
    const msg = JSON.parse(event.data);

    if (msg.op === 1) {
      ws.send(JSON.stringify({ op: 2, d: { subscribe_to_ids: [userId] } }));
      heartbeat = setInterval(() => {
        if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ op: 3 }));
      }, msg.d.heartbeat_interval);
    }

    if (msg.op === 0 && msg.t === "INIT_STATE") {
      console.log(msg.d[userId] || "User is not tracked");
    }

    if (msg.op === 0 && msg.t === "PRESENCE_UPDATE") {
      console.log(msg.d.discord_status, msg.d.activities);
    }

    if (msg.op === 0 && msg.t === "USER_REMOVED") {
      console.log("Tracking removed for", msg.d.user_id);
    }
  });

  ws.addEventListener("close", () => {
    clearInterval(heartbeat);
    setTimeout(connect, 3000);
  });
}

connect();

WebSocket opcodes

WebSocket events

Reconnection

The server sends WebSocket pings every 30 seconds and terminates clients that do not respond with pong. Browser clients handle ping and pong automatically. Clients should still send op: 3 heartbeat messages at the interval from op: 1.

Invalid JSON closes the connection with code 1003. The WebSocket server is configured with a 1024 byte max payload, so keep subscription messages compact. Re-send op: 2 after every reconnect because subscriptions live only on the current socket.

User object

Presence

Veyra stores the presence status string provided by Discord. The docs intentionally limit status values to the values handled by the implementation and Discord.js presence objects.

Activities

Every raw Discord activity is normalized and returned in activities. Veyra also derives top-level spotify and custom_status fields from matching activities.

Spotify

Spotify is detected when an activity has name === "Spotify", type === 2, and a syncId. When absent, listening_to_spotify is false and spotify is null.

Badges

Badges are returned in discord_user.badges. They are derived from Discord public flags, and when a server-side DISCORD_USER_TOKEN is configured, from Discord profile data such as purchased flags and premium fields.

Implementation note: a separate badge router exists in the repository, but server.js does not mount it. This documentation therefore treats badges as fields on the active user endpoint.

Errors

OpenAPI

The rebuilt docs include OpenAPI files for the active REST surface only. Every response includes real, filled-in examples (not just schema), plus per-endpoint auth and rate-limit notes.

Open the interactive API explorer · Download openapi.json or download openapi.yaml.

JavaScript guide

Use direct HTTP requests. Veyra does not include an official SDK in the provided source.

async function getVeyraUser(userId) {
  const res = await fetch(`https://veyra-db3d.onbelmo.uk/api/user/${userId}`);
  const body = await res.json();
  if (!body.success) throw new Error(body.error.code);
  return body.data;
}

const user = await getVeyraUser("YOUR_DISCORD_USER_ID");
document.querySelector("[data-name]").textContent =
  user.discord_user.global_name || user.discord_user.username;

TypeScript guide

Define local types from the documented response fields. No official TypeScript SDK is present in the repository.

type VeyraError = { success: false; error: { code: string; message: string } };
type VeyraSuccess = { success: true; data: { discord_status: string; listening_to_spotify: boolean } };

async function fetchPresence(userId: string): Promise<VeyraSuccess["data"]> {
  const response = await fetch(`https://veyra-db3d.onbelmo.uk/api/user/${userId}`);
  const body = (await response.json()) as VeyraSuccess | VeyraError;
  if (!body.success) throw new Error(body.error.message);
  return body.data;
}

Python guide

Python applications can use the REST endpoint for snapshots. Use a WebSocket client library when you need live updates.

import requests

def get_veyra_user(user_id: str) -> dict:
    response = requests.get(
        f"https://veyra-db3d.onbelmo.uk/api/user/{user_id}",
        timeout=10,
    )
    body = response.json()
    if not body["success"]:
        raise RuntimeError(body["error"]["code"])
    return body["data"]

React guide

For React or Next.js, fetch Veyra data from a component or your own server route. Do not add private Discord tokens to browser code.

import { useEffect, useState } from "react";

export function VeyraStatus({ userId }) {
  const [user, setUser] = useState(null);

  useEffect(() => {
    fetch(`https://veyra-db3d.onbelmo.uk/api/user/${userId}`)
      .then((res) => res.json())
      .then((body) => body.success && setUser(body.data));
  }, [userId]);

  if (!user) return null;
  return <p>{user.discord_user.username}: {user.discord_status}</p>;
}

Migrating from Lanyard

Troubleshooting

FAQ

Can I query any Discord ID?

No. Veyra only returns data for tracked users stored by the service.

Does Veyra require authentication?

No public REST or WebSocket authentication is implemented in the provided source.

Where do I find my API link?

Run /info in the Veyra Discord. The bot displays BASE_URL/api/user/:userId.

Does Veyra have official SDKs?

No SDK package is present in the repository. Use direct REST or WebSocket calls.

What does USER_NOT_TRACKED mean?

Veyra has no stored record for that user. Join and complete the Veyra Discord process so tracking can start.