Nookara API: Python clients and raw HTTP

Nookara is your identity: accounts, direct messages, groups, friends, credits, push, the keys that prove who wrote a message, and hosting. Ember servers are separate. Each one is an instance with its own web address, either run by you or hosted by Nookara. This guide covers both halves.

The API does not require the Scratch extension or the Ember app to be running. Everything the official apps do goes through the routes listed below.

How the pieces fit

Joining an Ember server just means adding its address. The main community lives at chat.ikelene.net. Older Nookara-hosted chat servers (the /chat/servers routes) are now legacy and read-only. See Legacy Nookara-hosted chat.

Ember in five steps

1. Find the server. GET https://INSTANCE/.well-known/bonfire (no sign-in) names the software, accounts_mode, features, build and the community. See Discover an instance.
2. Sign in. A Nookara account trades a short, single-instance ticket (POST /bonfire/instance-token) for an instance session; a local-account server takes a username and password. Your Nookara token never reaches the instance.
3. Know your scopes. Scopes are only requested. The person may decline any of them, so check what you got and degrade gracefully. See Scopes and consent.
4. Use the instance. REST under /api/v1, live events on wss://INSTANCE/gateway, uploads and media import, invites, webhooks, optional signed messages that anyone can verify against Nookara's public keys.
5. Bots. Instance bots live on one server; Nookara developer bots can be listed in the bot gallery and added to many servers with one token and one gateway connection per server.

Choose a transport

Nookara routes are unversioned, for example /im/send. Instance routes always start with /api/v1.

Python quick start

Python 3.10 or newer. The REST client has no runtime dependencies. This package is distributed directly by Nookara, so install the wheel URL rather than searching PyPI:

python -m pip install "https://nookara.cc/assets/api/velora_api_client-0.5.8-py3-none-any.whl"

To add websocket support (the instance gateway and the Nookara user socket) or signing after installing the wheel:

python -m pip install "velora-api-client[realtime]==0.5.8"   # websockets
python -m pip install "velora-api-client[signing]==0.5.8"    # cryptography, for signed messages

Or extract the source zip and run python -m pip install ".[realtime]" in the folder containing pyproject.toml. Its requirements.txt installs the optional websocket dependency only. Use a virtual environment for your project.

from velora_api import Client, Instance, login, scope_mask

# Opens a browser where the person approves what you ask for. Every scope is optional for them.
token = login(project_name="My Python client", scopes=scope_mask("PROFILE_READ", "CHAT"))
velora = Client(token)
print(velora.scope_names())                # what they actually allowed
print(velora.bonfire_instances())          # the Ember servers saved on this account

chat = Instance("https://chat.ikelene.net")
chat.login_with_velora(velora)             # a one-instance ticket, not your Nookara token
channel = chat.channel_id("#general")
for message in chat.messages(channel, limit=20)["messages"]:
    print(message["author"]["username"], message["body"])
chat.send_message(channel, "Hello from Python!")

The request 2049 is View Basic Profile (1) plus Chat Messaging (2048). Add Sign Messages (32768) or Upload Media (4096) only for features that use them, and treat them as optional: the person can untick any scope, so use velora.has_scope(...) or catch ScopeError (see Scopes and consent). Store a token in an OS credential store or a private environment variable. An existing token can be loaded with Client(os.environ["VELORA_TOKEN"]). Never print it or distribute it with your app.

One method per REST operation

The endpoint reference shows the Python method name for every route. Parameters from the URL are keyword arguments. Use query for query parameters and json for JSON bodies.

chat.post_api_v1_servers_by_sid_roles(
    sid="YOUR_SERVER_SID",
    json={"name": "Member", "permissions": 257, "color": "#c084fc"},
)
chat.call("get_api_v1_servers_by_sid", sid="YOUR_SERVER_SID")
velora.call("get_bonfire_hosting_plans")
velora.request("GET", "/bonfire/instances")

Nookara helpers on Client: send_dm(username, message), can_reply_to_status(username), reply_to_status(username, message), set_activity(name), clear_activity(), storage_get(storage_id, key), storage_set(storage_id, key, value), scopes (granted_scopes(), scope_names(), has_scope(x), require_scope(x), bonfire_scopes()), Ember identity (instance_token(url), signing_key(), bonfire_instances(), sync_bonfire_instances(urls), bonfire_default_joined(), bonfire_instance_prefs(), bonfire_directory(q), bonfire_profiles(ids), bonfire_key(kid), bonfire_jwks(), server_latest(), start_bonfire_import(...)), the bot gallery (below), bot_installs() for bot programs, and the hosting helpers in Hosting, plans and backups. Ember(velora) gathers your saved servers and their joined communities, Instance is one server, and BotProgram(token) serves a bot on every server it is installed on. The old servers(), server(sid), messages(cid) and send_message(cid, message) still call the legacy Nookara routes and now warn that they are read-only; use Instance for Ember servers (see Ember servers). Errors are APIError; a missing scope is the subclass ScopeError with scope, label and disabled_by_admin. Game server helpers: game_downloads(), game_instances(sid), game_unlink(sid, iid), game_unclaimed(sid), game_claim(sid, cid), game_claim_state(code), game_status(cid), game_console(cid), game_exec(cid, command) and game_audit(sid) (legacy Nookara routes; the matching Instance.game_* helpers use the instance).

Errors and uploads

from velora_api import APIError, ScopeError, TransportError

try:
    uploaded = chat.upload("picture.png", cid="YOUR_CHANNEL_CID")      # the media scope
    chat.send_message("YOUR_CHANNEL_CID", "A picture", attachments=[uploaded])
except ScopeError:
    print("Upload Media was not allowed: log in again and keep it ticked.")
except APIError as exc:
    print(exc.status, exc.error, exc.retry_after)
except TransportError:
    print("Check connectivity and whether the operation completed.")

For multipart, use data={...}, files={"file": path}. A file may also be (filename, bytes_or_file_object, mime_type). The SDK buffers at most 64 MiB of file content per multipart request. Server limits may be smaller. Video should use chunks. raw=True returns response bytes. Empty 204 responses return None.

The library rejects redirects and never retries automatically. A timeout after sending a message or payment does not prove the server rejected it. Check state before retrying writes.

Realtime in Python

import asyncio
import os
from velora_api import RealtimeClient

async def main():
    async with RealtimeClient(os.environ["VELORA_TOKEN"]) as chat:
        await chat.set_activity("My Python app", state="Connected")
        async for event in chat:
            if event.get("type") == "chat_message":
                print(event["message"])

asyncio.run(main())

The context manager waits for auth_success, checks ToS state, starts the reader, and sends chat_hello when Chat is granted. await chat.send_message(cid, text) waits for a nonce-matched reply. send(type, **fields) sends any user frame; rpc() is for frames that actually reply with a nonce. chat.notification_events() yields only notification_new and notifications_updated, and Client.notifications(), unread_notifications(), mark_notifications_read() and notification_settings() wrap the notification routes. Consume events continuously. Reconnect explicitly and resync using REST.

Authentication from any language

Use the browser approval flow for a third-party client. It lets the user choose scopes without giving your program their password.

1. POST /auth/ext-code with {"permissions_integer":2049,"project_name":"My client"} (the scopes you request; the person can decline any). The response is {"code":"..."}. Names that start with Ember ( are reserved and answer 400 reserved_project_name.
2. Open https://nookara.cc/login?code=CODE&project=My%20client&permissions=2049 in the user's browser. URL encode every query value. The code is sensitive while authorization is pending.
3. Poll GET /auth/ext-code/status?code=CODE about once every 1.5 seconds. Pending is {"ready":false,"alive":true}; completed is {"ready":true,"token":"..."}.
4. Keep the returned token private and use Authorization: Bearer TOKEN on subsequent user requests.

The returned token holds only the scopes the person approved, which can be fewer than you requested: check it (see Scopes and consent). Codes expire after five minutes. The successful status response consumes the code, so one process should own the polling loop. A false alive value is a heartbeat hint, including while a browser is still opening. Stop on explicit cancellation or expiry. The browser performs /auth/ext-code/complete after user approval; your client should not try to grant itself scopes.

Scope masks

permissions_integer is the sum of the scope bits you want (see Scopes and consent for the table). Scopes are only requested, never required, and both 16-bit halves are read the same way. Send the mask in the high half, permissions_integer = mask << 16, as the Ember apps and the Python library do. Granted scopes are capped by the requested union and the approving session's permissions. Do not send zero: the creation endpoint treats a zero mask as its default full mask.

Lifecycle and restrictions

• User tokens expire after seven days without authenticated use; active requests refresh last-used time. Revoke sessions using DELETE /auth/sessions/:sessionId or /account/sessions/:tokenId.
• POST /auth/validate accepts a Bearer token or JSON {"token":"..."}. A current ToS acceptance may be required; present the official site to the user. Do not automatically agree on their behalf.
• /auth/logout currently returns success without revoking a token. Delete the local credential and explicitly revoke the session if revocation is intended.
• Admins can disable individual scopes account-wide. Handle scope_disabled and realtime restrictions updates. A person who declined a scope will get insufficient_scope from the routes that need it.
• Password login and registration have CAPTCHA/email/IP verification flows. They are not a shortcut for a headless client. The scoped approval flow is the recommended integration.

Use TLS, avoid tokens in URLs, never ship shared user tokens, and do not log Authorization headers, auth frames, authorization codes or webhook URLs.

Scopes and consent: requested, never required

A scope is a permission on one person's token. Your program requests scopes, and the person decides on Nookara's consent screen. Nothing can be required any more: every scope can be unticked, and the risky ones (View Sensitive Info, Modify Settings, Write Storage, Manage Friends, Spend Credits and Sign Messages) start unticked. Design for a token that comes back with fewer scopes than you asked for, and say "log in again to use this" when a feature needs one it does not have.

Scopes authorize platform services. They do not grant membership, server roles, account rank or permission to read private profiles. Token scopes and chat role permissions are different bitfields (see Roles and channel permissions).

Ask for scopes

Send the bits you want in permissions_integer (see Authentication). Both 16-bit halves of the integer are read as requests; the Ember apps put everything in the high half (permissions_integer = mask << 16) and the Python library does the same. A zero or missing value asks for everything (65535), so always send an explicit mask. Chat + Voice + Media Upload is 2048 | 16384 | 4096 = 22528. The approval is capped by what you requested and by what the approving session holds.

Check what you got

• GET /bonfire/session works for any token: {granted, effective, disabled, not_granted, ...}. granted is what the person approved, effective also drops services an administrator switched off for the account.
• The user websocket's auth_success carries scopes and disabled_scopes. GET /account/me lists the account's sessions with their scopes and scope_list.
• GET /bonfire/scopes.json is public and describes what the official Ember apps ask for: {version, scopes: [{id, bit, required: false, since, name, reason}], permissions_integer}. required is always false.

velora = Client(token)
velora.scope_names()                 # ['PROFILE_READ', 'CHAT']   what they allowed
velora.has_scope("MEDIA_UPLOAD")     # False: hide the upload button, offer "log in again"
velora.require_scope("CHAT")         # raises ScopeError(scope='CHAT', label='Chat Messaging')

When a scope is missing

Instance scopes: what an Ember server sees

When you trade a Nookara token for an instance ticket (POST /bonfire/instance-token), Nookara writes the instance scopes the token holds into the ticket's scp claim. The instance session keeps exactly those for its 30 days. To gain one, the person approves it on Nookara and your client asks for a new ticket and signs in again. No other Nookara scope (profile, instant messages, friends, credits, storage) ever reaches an instance.

Local-account instances have no Nookara scopes at all. Their sessions always hold chat, voice and media and never sign.

The official apps

The Ember apps request the list in scopes.json (a versioned list; version 2 added Sign Messages). When a new version asks for something an installed app's token lacks, the app shows "New permission updates" and offers to log in again. It never blocks the app. The apps sign in through /bonfire/app-login?state=STATE&client=web|desktop|android, which creates the approval request on the server so a link cannot be edited to ask for more. Their sessions are named Ember (desktop app), Ember (Android app) and Ember (web); POST /auth/ext-code refuses any project name that starts with Ember ( with 400 reserved_project_name. Use your own name.

Raw HTTP: the shared contract

Any language with HTTPS support can call the user API. Set Authorization: Bearer TOKEN. Send JSON with Content-Type: application/json. URL encode each path parameter as one segment, and encode query parameters separately. Preserve IDs as strings.

GET /chat/servers HTTP/1.1
Host: nookara.cc
Authorization: Bearer YOUR_TOKEN
Accept: application/json

POST /chat/channels/YOUR_CHANNEL_CID/messages HTTP/1.1
Host: nookara.cc
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{"message":"Hello!","reply_to":null,"attachments":[]}

Response envelopes vary: {"servers":[...]}, {"message":{...}}, {"ok":true}, {"success":true}, an array, a text/binary file, or empty 204. Check the HTTP status before decoding, handle empty bodies, and keep unknown response fields for forward compatibility. message is also a valid success field, so do not treat the presence of that key as an error.

curl

curl --fail-with-body "https://nookara.cc/chat/servers" \
  -H "Authorization: Bearer $VELORA_TOKEN"

curl --fail-with-body -X POST \
  "https://nookara.cc/chat/channels/YOUR_CHANNEL_CID/messages" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"message":"Hello from curl!"}'

These commands use a POSIX shell. In PowerShell, use curl.exe and $env:VELORA_TOKEN, or the Invoke-RestMethod example below.

JavaScript / Node.js

const token = process.env.VELORA_TOKEN;
async function velora(method, path, body) {
  const response = await fetch("https://nookara.cc" + path, {
    method,
    redirect: "error",
    headers: {
      Authorization: `Bearer ${token}`,
      ...(body === undefined ? {} : { "Content-Type": "application/json" }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const text = await response.text();
  if (!response.ok) throw new Error(`Nookara HTTP ${response.status}`);
  return text ? JSON.parse(text) : null;
}
console.log(await velora("GET", "/chat/servers"));
const cid = "YOUR_CHANNEL_CID";
await velora("POST", `/chat/channels/${encodeURIComponent(cid)}/messages`,
             { message: "Hello!" });

In a browser, get the token through the approval flow and pass it from your application state instead of process.env. This fetch helper expects JSON endpoints; download binary/text endpoints using their appropriate response methods.

Python without the library

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

req = Request("https://nookara.cc/chat/servers", headers={
    "Authorization": "Bearer " + os.environ["VELORA_TOKEN"],
    "Accept": "application/json",
})
try:
    with urlopen(req, timeout=30) as response:
        servers = json.load(response)["servers"]
except HTTPError as exc:
    print("HTTP status:", exc.code)
    exc.close()

For production, prevent credential forwarding on redirects, as the supplied SDK does. Use urllib.parse.quote(value, safe="") for path segments and urlencode for queries.

C# / .NET

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using var http = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false });
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("VELORA_TOKEN"));
using var response = await http.GetAsync("https://nookara.cc/chat/servers");
if (!response.IsSuccessStatusCode)
    throw new Exception($"Nookara HTTP {(int)response.StatusCode}");
using var data = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
Console.WriteLine(data.RootElement.GetProperty("servers"));

var cid = "YOUR_CHANNEL_CID";
var body = new StringContent(JsonSerializer.Serialize(new { message = "Hello!" }),
                             Encoding.UTF8, "application/json");
using var sent = await http.PostAsync(
    $"https://nookara.cc/chat/channels/{Uri.EscapeDataString(cid)}/messages", body);
sent.EnsureSuccessStatusCode();

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "time"
)

func main() {
    client := &http.Client{Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        }}
    req, err := http.NewRequest("GET", "https://nookara.cc/chat/servers", nil)
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer " + os.Getenv("VELORA_TOKEN"))
    resp, err := client.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()
    if resp.StatusCode < 200 || resp.StatusCode >= 300 {
        panic(fmt.Sprintf("Nookara HTTP %d", resp.StatusCode))
    }
    var data map[string]any
    if err := json.NewDecoder(resp.Body).Decode(&data); err != nil { panic(err) }
    fmt.Println(data["servers"])
}

For a POST in Go, JSON encode the body, wrap it in bytes.NewReader, set Content-Type, and use url.PathEscape on each ID.

PowerShell

$headers = @{ Authorization = "Bearer $env:VELORA_TOKEN" }
$servers = Invoke-RestMethod -Uri "https://nookara.cc/chat/servers" -Headers $headers -MaximumRedirection 0
$cid = [Uri]::EscapeDataString("YOUR_CHANNEL_CID")
$body = @{ message = "Hello from PowerShell!" } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "https://nookara.cc/chat/channels/$cid/messages" `
    -Headers $headers -ContentType "application/json" -Body $body -MaximumRedirection 0

Rust, Java, PHP and other languages use the same paths, headers, JSON and multipart fields. The OpenAPI inventory can seed your own client generator. Its request and response schemas are intentionally permissive; do not use it as a complete input validator.

Ember servers: instances

Ember is an open chat protocol. Anyone can write an Ember client and use Ember servers; Nookara's web, desktop and Android apps are just the clients the Nookara ecosystem uses.

An Ember server is a program running at a web address. It holds one community (what the apps call a server) with its channels, members, roles and messages. Nookara does not store those messages. Nookara only proves who you are, so the same Nookara account can walk into any instance, and an instance can also run with its own local usernames and passwords and never touch Nookara at all. The main community is https://chat.ikelene.net, Nookara hosts https://SLUG-bonfire.ikelene.net servers (see Hosting), and anyone can run the server software on their own domain.

The protocol document that the server implements is bonfire-server/PROTOCOL.md in the Nookara repository. Section numbers below refer to it. Administration, builds, relays and bridges are in Instance administration and Nookara relays.

Discover an instance

GET https://INSTANCE/.well-known/bonfire needs no sign-in and is the first call any client makes. Treat the address you were given as the identity of the server and normalize it first: scheme and host in lower case, default ports dropped, no path, query or trailing slash. https is required except for local tests.

from velora_api import Instance

chat = Instance("https://chat.ikelene.net")
info = chat.discover()
print(info["name"], info["accounts_mode"], info["build"]["version"], info["read_only"])
print(chat.features["signing"], chat.accounts_mode, chat.build.get("commit_short"))

GET /api/v1/instance/info (also public) returns {software, protocol, version, name, build}; with an instance admin session it adds runtime, stats and update (see build and updates). GET /health is a plain liveness check.

Two ways to sign in

chat.login_with_velora(velora)            # Nookara-login instances
# chat.register("nat", "a long password")   # local-account instances, first time
# chat.login("nat", "a long password")
print(chat.session is not None, chat.user, chat.scopes)
chat.logout()                              # POST /api/v1/auth/logout and forget the session

Both flows return {"session","user"}. A session is 32 random bytes, valid for 30 days from last use, and is revocable. Send it as Authorization: Bearer SESSION. A user looks like {"id":"v:123","kind":"velora","username":"nat","display_name":"nat","pfp":null,"velora_id":"123"}. Ids carry their kind: v: for Nookara accounts, l: for local accounts and b: for bots (a bot's user object also has bot:true and, for gallery bots, verified:true). GET /api/v1/me returns {user, instance_admin, instance_owner, scopes}.

The ticket is an EdDSA JWT signed with Nookara's key (/.well-known/bonfire/jwks.json). Its claims are iss (Nookara), sub (your Nookara id, a string), aud (the normalized instance address), iat/exp (ten minutes), a one-time jti, username, display_name, pfp and scp, the instance scopes the person allowed (chat, voice, media, sign). The instance checks signature, issuer, audience, expiry and that the jti was never seen, then keeps the scopes on the session. Without chat it answers 403 insufficient_scope. Errors from the instance: 401 invalid_token, unknown_kid, invalid_signature, invalid_issuer, invalid_audience, token_expired or token_replayed; 400 wrong_accounts_mode; 403 banned; 502 velora_unreachable. While Nookara is in maintenance, POST /bonfire/instance-token answers 503 maintenance, so new sign-ins wait; open sessions keep working.

Your server list and the official server

The Ember servers a person has joined are saved on their Nookara account so the list follows them between devices: GET and PUT /bonfire/instances (Chat). An entry is {url, position, added_at, muted, push, auto_join}, at most 100, always normalized addresses. Adding an address is how you "join" a server in the apps; the community is then joined with POST /servers/:sid/join or an invite on the instance itself. PATCH /bonfire/instances/prefs {url, muted?, push?} controls push for offline mentions: an instance may only push to people who have its address in their list with push on and muted off.

Every account gets the official server (default_instance, currently https://chat.ikelene.net) added once, at sign-up or on the first read of the list. auto_join is true on that entry until a client has joined the community and confirmed it with POST /bonfire/instances/default-joined {url?}, so it happens once per account across devices. Removing the server later sticks. The public directory (GET /bonfire/directory?q=&page=) lists instances that chose to be listed.

Instance REST

The routes use the same paths and the same JSON shapes the old Nookara chat used, with /chat replaced by /api/v1. People are identified by the principal id (v:123), where the old routes used usernames. All errors are {"error":"snake_code", ...} with a fitting status; every route sends open CORS headers and there are no cookies. The Python names follow the path: get_api_v1_servers_by_sid, post_api_v1_channels_by_cid_messages and so on, and Instance adds friendlier helpers.

Joining, invites and requests

• The community has a join_policy: open or request. POST /servers/:sid/join follows it: with request the answer is {"pending":true} (the same on a second call) until someone with Kick or Manage server accepts. People on the ban list cannot join.
• An invite code always admits you, even when the policy is request. That is the "anyone with the link" path: POST /join/:code with no body. GET /invite/:code is public and previews the community.
• Manage server can GET/POST /servers/:sid/invites ({expires_in?: seconds, max_uses?: int}) and DELETE /invites/:code. Invites are {code, created_by, created_at, expires_at, max_uses, uses}. Every community also keeps one legacy permanent invite_code; PATCH {new_invite:true} regenerates it.
• Open an invite in the Ember web app with https://nookara.cc/chat#/i/ENCODED_ORIGIN/invite/CODE, where the instance address is URL-encoded (https%3A%2F%2Fchat.example.com). That is also the link a listed server puts in the directory.
• Pending requests: GET /servers/:sid/requests returns {requests:[{user, message, created_at}]}; the gateway sends chat_join_request to people who can accept and chat_join_result to the requester. On a Nookara-hosted server a full community answers 403 member_cap_reached with cap.

Server settings and moderation

bonfire-server only (PROTOCOL section 6.4). These are the pages under Server settings in Ember: Dashboard, Joining, Message rules, Reports, AutoMod, Audit log and Uploads.

• Settings: GET and PATCH /servers/:sid/settings (Manage server). PATCH takes any of join_policy, join_password and the sections join (allowlist, max_members, default_roles), messages (max_length, search_results, max_reactions, link_previews), automod (blocked words, timeout_seconds, exempt_roles, spam limits), audit (enabled, retention) and uploads (per_minute, files_per_member, types, expire_days, never_expire_roles, storage_mb, image compression). A section only changes the keys you send, and nothing is saved unless every value is valid. The answer is {settings}, which also carries plan (a hosted plan's caps, else null).
• Joining: join_policy can also be password (POST /servers/:sid/join {password}, else password_required / wrong_password), allowlist (not_on_allowlist) or invite (invite_only). A full server answers server_full {cap}.
• Reports: any member can POST /servers/:sid/reports {message_id | user_id, reason?}. Kick, Ban, Manage messages or Manage server can GET /servers/:sid/reports?status=open|resolved|dismissed&before= ({reports, open, has_more}) and PATCH /servers/:sid/reports/:id {status, note?}. Moderators get gateway chat_report. Reports that break Nookara's rules go to Nookara instead (/api/report/submit).
• Timeouts: Kick or Ban can POST /servers/:sid/timeouts {user_id, seconds, reason?} (1 second up to 28 days, never the owner or someone as high as you) and get {until}; GET lists them and DELETE /servers/:sid/timeouts/:uid lifts one. A timed-out member can't post, react (403 timed_out {until}), join voice or play sounds, and gets gateway chat_timeout {server, until, reason?}. Server and member views carry timeout_until.
• Audit log: GET /servers/:sid/audit?category=&action=&before=&limit= (Manage server, Kick or Ban) returns {entries, has_more, actions, categories}.
• Dashboard: GET /servers/:sid/dashboard (Manage server) returns counts, storage use, health and channel activity.

chat.update_server_settings(join_policy="password", join_password="campfire",
                            automod={"words_enabled": True, "words": ["spoiler"], "timeout_seconds": 300})
chat.time_out("v:42", 3600, reason="cool off")
for report in chat.reports()["reports"]:
    chat.set_report_status(report["id"], "resolved", note="handled")
print(chat.audit_log(category="user_moderation")["entries"][:5])

Common payloads

Message text is limited to 4000 characters, and line breaks are stored as \n. History returns {"channel":{...},"messages":[...],"has_more":true} in chronological order. limit defaults to 50 and clamps to 1 through 100. Use the oldest message ID as before for earlier pages, or after for catch-up. Dedupe by message ID when combining REST history with realtime events.

{
  "id": "123", "channel": "c0123456789", "server": "s0123456789",
  "body": "Hello!", "author": {"id": "v:123", "username": "example", "velora_id": "123"},
  "attachments": [], "system": false, "pinned": false,
  "reply_to": null, "reply": null, "created_at": 1791660000000, "edited_at": null,
  "signature": null, "verified": null, "alias": null
}

This is a shortened illustrative message. Server-message timestamps are Unix milliseconds. A system message has author:null and welcome, leave and pin notices add subject and body_parts (see identity updates below). Webhooks, bridges, replies, embeds, reactions and mentions add fields. A webhook or bridged author is {id:null, name_only:true, webhook:true, username, pfp, bridge?}.

Channel types and config

Update channel properties with PATCH /api/v1/channels/:cid. Non-message channel types cannot all accept ordinary posts. Use returned can_post for UI affordances, while treating the server's authorization result as final. Paid roles: for a priced role you have not bought, POST /channels/:cid/shop/:rid returns {pending:true, pay_request:{id, approve_url, amount, expires_at}}. The person opens approve_url on Nookara (Pay or Cancel, with the CAPTCHA); poll GET /channels/:cid/shop/:rid/status until paid. Local accounts cannot pay (402 velora_required); the instance owner is paid when their Nookara account is linked.

CloudLink bridges

A logs channel whose config has "mode":"cloudlink" is joined by the instance to a CloudLink 4 WebSocket server (default wss://ikelene.net/cl/, the ScratchCord global chat). Create or switch one with POST /api/v1/servers/:sid/channels or PATCH /api/v1/channels/:cid and a config like the one in the table. It needs Manage channels. A server can have up to 3. The URL must be ws: or wss: on port 80 or 443, and the instance refuses private, LAN and loopback addresses, also after DNS. room is optional (empty = the main chat); username is optional and makes the bridge visible in CloudLink's user list (a room needs one, so it defaults to Ember). The public config also has official (true for the official server).

Messages from CloudLink arrive as bridged messages: author is {"username":"Name","pfp":...,"webhook":true,"bridge":"cloudlink"}, with bridge_from set to Discord, Fluxer or Ember when the line came through one of those bridges first. Mentions in them never ping (every @ gets a zero-width space). Inbound messages are rate limited per channel (8 per 10 seconds, 40 per minute); skipped ones produce one system message with sys_kind cl_skip per minute. What members write goes to CloudLink as {"cmd":"gmsg","val":"Ember | name: text"}. Webhook, bot-bridge and system messages are not forwarded. Sending !online in the channel posts the CloudLink user list instead of forwarding it.

GET /api/v1/channels/:cid/cloudlink returns {"status":{"state","error","since","retry_at","online","users","last_in","last_out","skipped","url","room","username","official"}}; state is connecting, handshaking, connected, waiting (reconnecting with backoff, error says why) or off. POST /api/v1/channels/:cid/cloudlink/reconnect reconnects now. Both need Manage channels. Discord and Fluxer bridges are described under Instance administration.

Uploads and media import

Uploads need the media instance scope (the person's Upload Media permission, 4096) and the community's allow_uploads setting. Both calls take sid (required) and optionally cid in the query; with cid the channel's Attach permission is checked, and sending an attachment checks it again.

• POST /api/v1/media/upload?sid=SID&cid=CID with multipart field file.
• POST /api/v1/media/import?sid=SID&cid=CID with JSON {url, name?} makes the instance fetch a file for you, for saved media that lives elsewhere. Only https URLs without credentials (4096 characters at most) are accepted; the fetcher pins public DNS answers, rechecks redirects, ports and private addresses, forwards no cookies or headers, and limits size and time. Errors: invalid_media_url, media_import_failed (422), file_too_large (413 with max_mb).

{ "url": "https://INSTANCE/uploads/2026/10/abc.png", "name": "cat.png", "size": 123, "mime": "image/png",
  "type": "image", "sha256": "HEX", "width": 640, "height": 480 }

Pass that object (up to 10) in a message's attachments. The instance only accepts its own /uploads/ URLs and Klipy GIF links. type is image, gif, video, audio or file. sha256 is the hash of the stored bytes (JPEG EXIF is stripped before hashing), which is what a signed message commits to. The size limit for a member is min(instance ceiling, plan ceiling, the larger of the community default and their roles' limits); GET /servers/:sid returns upload_max_mb (the default), my_upload_max_mb (yours) and upload_ceiling_mb. Roles take upload_max_mb (1 to 500 or null). Too large answers 413 {"error":"file_too_large","max_mb":N}. Files are served immutable with nosniff, and non-media types as downloads.

Quick start: read a channel

import os
from velora_api import Client, Instance

velora = Client(os.environ["VELORA_TOKEN"])      # needs Chat (2048)
chat = Instance("https://chat.ikelene.net")
chat.login_with_velora(velora)

channel = chat.channel_id("#general")            # a name or a cid
history = chat.messages(channel, limit=50)
for message in history["messages"]:
    author = (message.get("author") or {}).get("username", "system")
    print(author + ":", message["body"])

Joining is automatic in the Ember apps. From code, call chat.join() once. On a community with join_policy: "request" the answer is {"pending": true} until a moderator accepts you. To see every community across the whole saved list, use Ember(velora).communities(); servers that are down, local-account only or where Chat was declined are reported per entry instead of failing the rest.

Bots: instance bots and Nookara developer bots

There are two kinds of bot and they can work together.

import asyncio
import os
from velora_api import Instance

bot = Instance("https://chat.ikelene.net", bot_token=os.environ["BONFIRE_BOT_TOKEN"])

async def main():
    async with bot.bot_gateway() as gateway:
        async for event in gateway:                       # {"type", "data", "seq"}
            if event["type"] == "MESSAGE_CREATE":
                message = event["data"]
                if message["content"].strip() == "!ping" and not message["author"].get("bot"):
                    await asyncio.to_thread(bot.bot_send, message["channel_id"], "pong")

asyncio.run(main())

Bot REST is Discord-style under /bot/v1 (discover it at GET /bot/discovery): numeric ids serialized as strings, content instead of message, errors shaped like {"message","code"}, and 150 requests per 10 seconds per bot. Routes include /users/@me, /users/@me/guilds, /guilds/:gid/channels, /guilds/:gid/members, /channels/:cid/messages (GET, POST, PATCH, DELETE), reactions and pins. The Python names start with bot_v1, for example get_bot_v1_guilds_by_gid_channels. The compatibility surface is a subset of Discord's, not a promise that every Discord library works unchanged. A bot posts as a member: it needs Send in the channel and obeys locked and no-chat channels. A bot only receives events for channels it can see.

Slash commands work like Discord's application commands. A bot registers them with PUT /bot/v1/applications/@me/commands (global) or /bot/v1/applications/@me/guilds/:gid/commands (one server): type 1 slash commands with options, subcommands, choices and autocomplete, type 2 user menu commands and type 3 message menu commands. Members type / to pick from a list that shows the bot each command comes from, or right click a message or member and open Bots. A run arrives on the bot gateway as INTERACTION_CREATE and the bot has three seconds to answer with POST /bot/v1/interactions/:id/:token/callback: type 4 reply, 5 deferred reply, 6 deferred update, 7 update message, 8 autocomplete choices or 9 modal. Followups, edits and deletes go through /bot/v1/webhooks/:app/:token for 15 minutes. Flag 64 makes a reply ephemeral, so only the person who ran the command sees it and it is never stored. Replies can carry buttons, select menus and embeds, and modals take text inputs. Server owners choose which roles can use each command in Server settings > Bots, or a bot can set that for its own commands with the guild command permissions routes. Python: Instance.bot_set_commands(), bot_interaction_respond() and bot_followup(), with on("INTERACTION_CREATE", ...) on the bot gateway.

A bot added from the gallery runs on many instances with one token, so its program needs one connection per instance. Ask Nookara where it is installed: GET /bonfire/bots/self/installs with Authorization: Bot TOKEN returns {"instances":[{origin, name, test, added_at, seen_at}]}. Open one /bot/gateway per origin, ignore test installs unless you are the reviewer, and poll again every few minutes for new and removed installs. velora_api.BotProgram does exactly this.

Quick start: a webhook

Webhooks post into one channel without any account. Make one with chat.create_webhook(cid, "Scores") (Manage channels; text and logs channels, 30 per community) or in the channel settings. The URL has the form https://INSTANCE/api/v1/webhooks/WID/TOKEN and the token in it is the key, so treat the whole URL as a secret. PATCH /hooks/:wid renames it, moves it to another channel (channel) or rotates the secret (new_token:true).

from velora_api import execute_webhook

execute_webhook("https://chat.ikelene.net/api/v1/webhooks/WID/TOKEN", "Build finished",
                username="Build service")

The body is Discord's: {content, username, avatar_url, embeds} as JSON (up to 10 embeds), or multipart with payload_json and files (files[0], ...; an embed image can say attachment://name). ?wait=true returns the posted message, otherwise success is an empty 204. The limit is 30 posts per minute per webhook (429 with retry_after). GET on the URL returns its info and DELETE removes it. Webhook messages show a name only (author.webhook), are never signed and do not ping people who are offline. Webhook errors use Discord's {message, code} shape.

The instance gateway

Connect a websocket to wss://INSTANCE/gateway and keep to this order:

1. Send {"type":"auth","session":"SESSION"} within 10 seconds.
2. Wait for {"type":"auth_success","user":{...},"instance_admin":false,"instance_owner":false}. A bad session closes the socket with code 4001.
3. Send {"type":"chat_hello"} and wait for {"type":"chat_ready"}. Community events start now.
4. Send {"type":"ping"} every 25 seconds. The reply is pong, and a socket idle for 60 seconds is dropped.

Client frames: chat_send {nonce, channel, message, reply_to?, attachments?, signature?} (answered by chat_ack {nonce, message} or chat_error {nonce, error}), chat_typing {channel}, chat_read {channel, message_id}, the voice frames (chat_rtc_* and voice_sound, which need the voice scope). Events you receive include chat_message, chat_message_update, chat_message_delete, chat_reactions, chat_pins_update, chat_typing, chat_channels_update, chat_member_update, chat_members_stale, chat_emojis_update, chat_server_update, chat_roles_update, chat_perms_changed, chat_mention, chat_starboard, chat_identity_update, user_update, chat_join_request, chat_join_result, chat_server_added, chat_server_removed, chat_shop_update, chat_voice_state, chat_ephemeral, the Ember Link events (game_status, game_console, game_linked, game_unlinked), instance_update and instance_restarting. Events reach a member only when they can see the channel. Presence of people is not relayed by instances; it comes from your Nookara socket. The exception is bots: chat_presence (below) reports whether a bot is online. Voice rooms are named bf_ plus the channel id and use the same frames as Voice and video signaling; direct-message calls stay on Nookara.

import asyncio
from velora_api import APIError

async def main():
    chat.login_with_velora(velora)
    async with chat.gateway() as gateway:       # waits for chat_ready
        async for event in gateway:
            if event["type"] == "chat_message":
                print(event["message"]["author"]["username"], event["message"]["body"])
            elif event["type"] == "gateway_ready":      # emitted after every (re)connect: refetch history now
                pass
        # or register callbacks and call: await gateway.run()
    # await gateway.send_message(channel, "hi")  waits for the chat_ack and returns the message

asyncio.run(main())

The Python gateway authenticates before anything else, reconnects by itself with capped exponential backoff and jitter (1 second growing to 30), sends the ping, fails pending requests when the socket drops, and stops with an APIError on close codes 4001 and 4003. It also yields gateway_disconnected and gateway_ready markers. There is no replay: after a reconnect, refetch history over REST and dedupe messages by id.

Signed messages

Signing is optional and only works for Nookara-login instances. Every community accepts signed messages, none can require them, and unsigned messages are always accepted. It lets anyone check that a message really came from an account, independent of the instance. Every Nookara account has one Ed25519 signing key shared by all its apps. The private half is stored encrypted by Nookara and handed only to a token that holds Sign Messages (32768), which is off by default on the approval screen, so expect people to decline it and keep sending unsigned messages when they do.

1. GET /bonfire/signing-key on Nookara returns {kid, public_key, private_key, created_at}. Keep it in memory and never write it down.
2. Build the payload {v:1, iss, instance, community, channel, author, ts, nonce, body, attachments, reply_to, edit_of}: iss is Nookara's address, instance the normalized instance address, community the sid, channel the cid, author your Nookara id as a string, ts the time in milliseconds, nonce 16 random bytes in base64url, body the exact text (line breaks as \n), and attachments the sha256 of each uploaded file (url:URL for a link-only Klipy GIF).
3. Sign the UTF-8 bytes of "bonfire-msg-v1\n" followed by the canonical JSON of the payload (keys sorted recursively, no whitespace, integers only). The result goes in signature: {kid, sig, ts, nonce} on the message (or on a PATCH edit, with edit_of set to the message id).
4. The instance fetches the key from /bonfire/keys/kid/:kid, checks the owner, that the key was not revoked before ts, that ts is within five minutes, and the signature. A failure is 400 bad_signature with a reason; a signature from a session without the sign scope is 403 insufficient_scope and a local-account session gets 400 signing_unavailable. Messages come back with signature and verified: true, false or null (unsigned). Bots, webhooks and system messages never carry signatures. Editing without a signature clears it.

velora = Client(os.environ["VELORA_TOKEN"])         # Chat 2048, plus Sign Messages 32768 if allowed
chat = Instance("https://chat.ikelene.net")
chat.login_with_velora(velora, sign="auto")         # signs only when the person allowed it

sent = chat.send_message(chat.channel_id("general"), "Signed from Python")
print(sent["message"]["verified"])                  # True
ok, reason = chat.verify_message(sent["message"])   # check it yourself against Nookara's public key
chat.send_message(chat.channel_id("general"), "No signature on this one", sign=False)

Verify for yourself instead of trusting the verified flag. Rebuild the payload from the message (server, channel, author.velora_id, signature.ts and nonce, body, the attachment hashes, reply_to, and edit_of = the message id when it was edited and still carries a signature), fetch the public key from the public route GET /bonfire/keys/kid/:kid, require that user_id equals the author and that revoked_at is null or not earlier than ts, then check the Ed25519 signature. Signing needs the optional extra: python -m pip install "velora-api-client[signing]" (the cryptography package). Without it everything else works and sign=True raises ImportError. Rotating the key (POST /bonfire/signing-key/rotate, website session only) does not invalidate old messages. A signing failure after a rotation is solved by fetching the key again, which enable_signing(velora) does.

Names and pictures stay current

Nookara members' names and pictures follow their Nookara profile. The instance refreshes them from GET /bonfire/profiles?ids=1,2,3 and sends chat_identity_update {user, previous_username} to every community the person is in. Patch every cached author, reply, mention and member whose id equals user.id. Welcome, leave and pin notices carry subject: {id, username} and body_parts so a rename updates old lines without rewriting history; a deleted subject shows as "Deleted account". After a reconnect, resolve ids you do not know with GET /api/v1/identities?ids=v:1,b:2. Nookara's own equivalent is GET /chat/identities?ids= (Chat, up to 200 ids).

Live profile changes: when someone changes their picture, banner, colour, pronouns, bio, website, country or username, Nookara sends user_update {user, changed, previous_username?, v} on the home socket (user = {id, username, display_name, pfp_url, pfp_animated, banner_url, banner_animated, color, rank, pronouns, bio, website, country_code, bot?}; changed lists what moved, e.g. ["pfp"]). It goes to the person's own sessions, their friends, people they have a DM or group chat with and members of the same Nookara-hosted servers, never to anyone blocked either way. Friends-only profiles send everyone who is not a friend only {id, username, display_name, pfp_url, pfp_animated, color, rank, limited: true}. Rapid edits arrive as one event. Patch every cached copy of user.id (members, authors, friends, DM list). Pictures get a new URL on every upload; if the URL is the same as before, add ?v=<v> to bypass the cache. For members of instance servers (v:<id>) the instance still refreshes its own copy on its normal schedule, so apply user_update to those too.

Read-only servers

When a hosted server's paid time runs out, or a legacy server has moved, every write answers 403 {"error":"read_only"} (instances) or server_read_only with moved_to (legacy Nookara servers). Signing in and every GET still work, including exports. Show a banner and hide write controls; discovery reports read_only: true.

What Nookara adds for Ember

Direct messages, groups, friends, push, credits and presence stay on Nookara and are unchanged. Instances forward offline mentions to Nookara push for people with Nookara accounts; push needs the per-server consent in the instance list.

Hosting, plans and backups

Nookara can run an Ember server for you at https://SLUG-bonfire.ikelene.net. It is an ordinary instance (Nookara accounts, one community) started in managed mode, so everything in the Ember section applies. Nookara keeps no session on it: you sign in there and create the community yourself.

GET /bonfire/hosting/plans is public and returns the live numbers (null means unlimited), so read it instead of hard-coding this table.

What happens when time runs out

Plus never renews by itself. Weeks are bought in advance (1 to 52). When the paid time ends:

1. Overdue for 2 days: the server keeps working normally.
2. Read-only for the next 7 days: nobody can post or change anything, but members can still sign in and read. Buying weeks switches writing back on at once.
3. Archived: Nookara saves a backup of the community, then removes the server and frees its container. The name stays yours for 30 days, and you can restore the backup into a new server.

Owners are notified two days before the end, and at each step. Starter servers never expire. With Nookara Pro, Plus is covered for free: remaining paid time is banked while Pro lasts and resumes afterwards (no saved time means overdue right away). Account backups are kept for 180 days, 10 per account.

Hosting routes

All need a Nookara token. Buying weeks needs Spend Credits (1024); the rest need Chat Messaging (2048). A person who declined either scope gets insufficient_scope. The server object has slug, url, name, plan, status (provisioning, running, stopped, suspended, deleted, error), billing (pro, active, overdue, read_only, archived), paid_until, read_only_at, archive_at and voice usage.

Errors you will see: slug_taken (409), slug_reserved, invalid_slug, starter_limit_reached, insufficient_balance with cost and balance, pro_covers (409, Plus is already free for you), use_weeks, backup_not_found and hosting_unavailable (503).

from velora_api import Client

velora = Client(token)
print(velora.hosting_plans()["plans"])
if velora.hosting_slug_available("camp")["available"]:
    created = velora.create_hosting_server("camp", "Camp", "starter")
    print(created["url"])                         # https://camp-bonfire.ikelene.net

# Restoring an account backup into an existing server (owner session on the instance):
blob = velora.download_hosting_backup(backup_id)
open("restore.zip", "wb").write(blob)
chat = Instance(created["url"])
chat.login_with_velora(velora)
chat.restore_from_file("restore.zip")

To start a new server from a saved backup instead, pass restore_backup=ID when creating it; the instance imports it on first boot and members who sign in again get their roles back.

Instance administration and Nookara relays

For people who run an Ember server and for tools that manage one. Everything here uses an instance session (never a Nookara token) unless it says Nookara. Administration needs the instance admin or owner flag from GET /api/v1/me. Instance admins have no special power inside the community: they only manage the instance, and may delete the community. Roles decide the rest.

Claiming and settings

A fresh instance prints a setup code (XXXX-XXXX) on first boot. Someone signed in claims it with POST /api/v1/instance/claim {code} and becomes the owner and an admin; then the owner or an admin sets up the community once with POST /api/v1/servers or imports one. GET and PATCH /api/v1/instance/settings (admins) cover name, description, icon_url, registration (open/closed, local mode), max_upload_mb, max_backups, voice (Cloudflare keys, write-only), youtube, velora_registration (auto/off), listed and tags (up to 8, for the directory). accounts_mode, public_url and velora_url need a restart. POST /api/v1/instance/restart (admins) returns 202 and exits for the supervisor to start again. GET /api/v1/instance/update (admins) says whether the server can update itself and whether a newer build exists; POST /api/v1/instance/update asks the host agent to rebuild and recreate the container (only on servers started with BONFIRE_UPDATE_URL and BONFIRE_UPDATE_SECRET, never on Nookara-hosted ones). Ember shows this as Server settings, Danger zone, Update. GET/PUT/DELETE /api/v1/instance/admins[/:uid] (PUT and DELETE owner only) manage admins. Switching accounts_mode from velora to local answers 409 local_admin_required until a local account is an admin, so nobody is locked out; the owner makes one with POST /api/v1/instance/local-admin {username, password} (an instance admin with an admin role on the server; the settings list them in local_admins). POST /media/upload takes an optional expires_in_days.

Build, version and updates

Every instance reports the build it is running in discovery (build) and in GET /api/v1/instance/info: version, commit, commit_short, commit_date, built_at, dirty and a build_id. A server built by the release script has the commit baked in; a plain checkout reports nulls. With an admin session the same call adds runtime (Node version, uptime, platform), stats (members, channels, messages, uploads and their bytes, database size, bots, emoji, sounds; cached 30 seconds) and update: {outdated, latest, checked_at}, or null when it cannot tell. The comparison is against GET https://nookara.cc/bonfire/server-latest.json (public; {version, commit, commit_short, commit_date, built_at, build_id, dirty, message, published_at}), which the instance caches for an hour. outdated is true when the build ids differ and the published build is newer. Nookara-hosted servers are updated by the host, one at a time with a health check and rollback.

info = chat.instance_info()
print(info["version"], info["build"]["commit_short"])
print(chat.update_available())          # True / False for admins, None when unknown
print(velora.server_latest()["build_id"])

Backups, export and import

Every instance, self-hosted or hosted, can back up its community as a portable bonfire-export-v1 zip (settings, channels, roles, emoji, members, messages and files). Admins use an instance session, never a Nookara token.

backup = chat.create_backup("before the update")   # POST /api/v1/instance/backups
for item in chat.backups():                        # newest first: id, created_at, size, by, note
    print(item["id"], item["size"], item["note"])
open("backup.zip", "wb").write(chat.download_backup(backup["id"]))
# Owner only: chat.restore_backup(backup["id"]) or chat.restore_from_file("backup.zip")

The instance keeps at most max_backups (10 by default, 1 to 50), oldest first. Restoring replaces the community inside one transaction after taking a safety backup first, then answers {ok, sid}, sends instance_restarting and closes gateway sockets with 4010. Ids are remapped, so reconnect and refetch. Errors: 404 backup_not_found, 403 owner_only, 409 no_community. The community owner can also GET /api/v1/servers/:sid/export and an admin can create the community from a zip with POST /api/v1/import (only while there is none). A Nookara-hosted instance refuses to change accounts_mode, public_url, velora_url and velora_registration (403 managed_setting).

Bringing a Discord or Fluxer server over. Nookara builds the bundle, the instance imports it. With your Nookara token (Chat): GET /bonfire/import/platforms, GET /bonfire/import/:platform/guilds and .../guilds/:gid (the preview), then POST /bonfire/import {platform, guild_id, channels, roles, options?, instance} returns {job_id, ticket, expires_at} and builds the zip in the background (one job per person; poll GET /bonfire/import/:job_id). The bundle holds channels with categories, per-role view/send/attach settings, roles, emoji, icon and banner, never members or messages. The ticket (bit_...) is a one-time secret bound to that instance; give it to POST /api/v1/import/velora {ticket} on the instance (admin, only while it has no community). Errors pass through with a message: ticket_invalid, ticket_wrong_instance, not_ready (retry), ticket_expired, velora_not_registered, velora_off.

What an instance asks Nookara for

Unless an admin sets velora_registration to off, an instance registers with Nookara (it proves control of its address with its own key) and then uses a few relays, all authenticated by the instance's key, never by a person's token. A local-account instance can use them too. Banned instances get 403 instance_banned everywhere, get no tickets and are not listed.

Bridges and extras

• Discord and Fluxer. The owner connects their own bot token per platform (PATCH /api/v1/bridge/settings, admins; tokens are write-only). People with Manage server then link the community to one server per platform (PUT /api/v1/bridge/servers/:sid {platform, guild_id, automap?}) and individual channels (PUT /api/v1/bridge/servers/:sid/channels/:cid). Messages are mirrored both ways through a webhook named "Ember bridge"; nothing from a bridge pings anyone. GET /api/v1/bridge/platforms, GET /api/v1/bridge/:platform/guilds and GET /api/v1/bridge/servers/:sid show the state. Not available on the Starter plan (403 plan_limit).
• YouTube player. Optional, needs yt-dlp on the server; discovery shows features.youtube. POST /yt/:id/prepare, GET /yt/:id/status, POST /yt/:id/save (needs the media scope), signed stream links.
• Link previews. GET /unfurl?url= is fetched by the instance with an SSRF-safe fetcher (public addresses only, ports 80 and 443).
• Maintenance. While Nookara is in maintenance, /health, the JWKS and /bonfire/relay/* stay up, so instances keep working; new sign-in tickets wait (503 maintenance).

Managed (hosted) instances

Discovery's managed object is {plan, limits, host} on Nookara-hosted servers. Limits are enforced by the instance: member_cap_reached (with cap), plan_limit (with what: emojis, sounds, bots, bridges, custom_voice_keys and limit), upload size (file_too_large) and managed_setting. See Hosting, plans and backups.

Legacy Nookara-hosted chat

1. GET /chat/servers returns {"servers":[...]} with an opaque sid, a read_only flag, and moved_to for servers that moved.
2. GET /chat/servers/:sid returns server, categories, roles, voice and the visible channels.
3. Owners can save a legacy server with POST /chat/servers/:sid/export-to-account (3 per hour; the zip lands in your account backups with reason legacy) or download it with GET /chat/servers/:sid/export (owner only), then import it into an instance (POST /api/v1/import) or a new hosted server (restore_backup).

Account-level chat features did not move: presence and activity (/chat/presence/*), /chat/settings, /chat/notify, /chat/identities, DM calls, GIF routes, the developer bot accounts (/chat/bots, used by the bot gallery) and modmail stay on Nookara and keep working. Direct messages are not part of Ember servers either: they are Nookara's Instant Messages (/im; /mail is an alias). The user websocket frames chat_* on Nookara's socket only concern legacy servers.

Game servers (Minecraft, Ember Link)

Ember Link connects a Minecraft server (Paper, Spigot, Fabric or a Velocity proxy running the Ember plugin) to an Ember server. A linked server appears in channels of the game type. On an Ember instance the routes are under INSTANCE/api/v1/game with the same shapes as the /chat/game routes written below; use the instance session instead of a Nookara token. The Nookara /chat/game routes are legacy and read-only. All routes need a session with the chat scope and obey the member and permission checks of the Ember server, except GET /game/downloads (public; an instance does not host plugin builds, so it returns empty values).

Linking

On an instance there are two ways, both started from the Minecraft server:

1. Connect and pick. The server owner runs bonfire server https://chat.example.com in the game console. The plugin keeps one outbound websocket to wss://chat.example.com/game-gateway?v=1 (no open ports needed) and prints a pairing tag such as ABC-123. In the community, create a channel with type: "game" (Manage channels; it starts "not set up" and is visible to managers only), then list waiting servers with GET /api/v1/game/connected (Manage server; filter with q, tag, page) and link one with POST /api/v1/game/connected/:iid/link {cid}. Pick the purpose (info, console, chat) in the channel config.
2. Claim code. POST /api/v1/game/claims with {"cid":"GAME_CHANNEL_CID"} returns {code, command, expires_at} (10 minutes, 10 per hour). Someone with console access runs bonfire link CODE. Poll GET /api/v1/game/claims/CODE, or wait for the game_linked event on the instance gateway.

List linked servers with GET /api/v1/game/servers/SID/instances (Manage channels). Unlink with DELETE /api/v1/game/servers/SID/instances/IID (Manage server), or run bonfire unlink confirm on the game server. The legacy Nookara flow was GET /chat/game/unclaimed plus /chat/game/claims.

One Minecraft server can be linked to only one Ember community, and a community has a limit of 10 linked servers (too_many_instances). A server that stays unlinked and unseen for 30 days is forgotten.

Game channel config

Status, console and audit

Realtime events

These arrive on the instance gateway (wss://INSTANCE/gateway) after chat_hello, only for channels the user can see (a console channel's events reach Manage server only). The legacy Nookara socket sends the same frames for legacy servers.

Messages from Minecraft

Messages relayed from a game server have author.bridge: "minecraft" and author.webhook: true. When the source is a backend behind a proxy, author.bridge_from is its name. Event lines are system messages whose sys_kind is one of mc_join, mc_leave, mc_death, mc_adv, mc_switch, mc_start, mc_stop, mc_unlink or mc_skip.

for server in chat.game_connected()["instances"]:     # servers waiting to be linked
    print(server["iid"], server["pairing_tag"], server["motd"])
chat.game_link("g0123456789abcdef", cid="GAME_CHANNEL_CID")
card = chat.game_status("GAME_CHANNEL_CID")
print(card["online"], card["status"]["players"]["online"])
lines = chat.get_api_v1_game_channels_by_cid_console(cid="CONSOLE_CHANNEL_CID")["lines"]

Integration protocol (for plugin authors)

The Minecraft plugins talk to wss://INSTANCE/game-gateway?v=1, the instance they were pointed at with bonfire server URL (the old hard-coded wss://nookara.cc/chat/game-gateway is legacy). This is not a user or bot API and the Python library does not implement it. Each text frame is a JSON object {"op":"name","d":{...},"id":optional}, at most 64 KiB. Nookara sends hello with a nonce and a heartbeat interval; the plugin answers identify within 15 seconds with a signature made by its own key pair (the instance id is derived from that key), and Nookara replies ready. After that the plugin sends status snapshots, heartbeat, chat, event, console.log, console.result and console.command; Nookara sends config, chat, console.exec, link_result, linked, unlinked and error. Close codes 4003 (bad signature), 4004 (banned), 4005 (rate limited), 4006 (replaced), 4007 (unsupported version) and 4008 (IP limits) tell the plugin how to back off. Unlinked servers are purged after 30 days. A new game identity is trusted on first use: its Ed25519 key defines the instance id, and an address may register only 5 new ones per day.

Roles and channel permissions

Token scopes and chat role permissions are different bitfields. For example, role permission 1024 means View Channel; token scope 1024 means Currency Pay. Never use one mask as the other.

The default everyone role permits Send + Attach (257). A server owner and Administrator have all server permissions. The official server also grants staff special moderation access. View (1024) is channel-level, rather than part of the server permission mask 1023.

On an Ember instance (members are identified by principal id such as v:123; the legacy Nookara /chat routes use usernames):

POST /api/v1/servers/SID/roles
{"name":"Reader","permissions":0,"color":"#c084fc","hoist":false,"mentionable":false}

PUT /api/v1/servers/SID/members/v:123/roles/RID

PUT /api/v1/channels/CID/perms
{"overwrites":[{"rid":"EVERYONE_ROLE_RID","allow":0,"deny":1024},
               {"rid":"READER_ROLE_RID","allow":1024,"deny":1}]}

The overwrites endpoint takes the replacement list. Channel overrides affect View (1024), Send (1) and Attach (256). The server combines base roles, applies everyone deny/allow, then combines member-role denies and allows. Allow wins within the final combined role overrides. Owners/admins bypass overrides; Manage Channels users can see channels to repair settings. Other hierarchy checks still apply to role edits and moderation.

Instance administrators (the instance owner and admins) have no implicit power inside a community: only the community owner, Administrator roles and role permissions count. The one exception is that instance admins may delete the community, which returns the instance to setup.

Read roles and everyone-role identifiers from server details. Do not guess an ID or assume a user with a valid Chat token can manage a server.

User realtime protocol

Connect a websocket to wss://nookara.cc/ and send UTF-8 JSON:

{"type":"auth_token","token":"YOUR_USER_TOKEN"}
// Wait for {"type":"auth_success", ...} before sending anything else.
{"type":"chat_hello"}
// Server replies {"type":"chat_ready","you":{...}}.
{"type":"chat_send","channel":"CHANNEL_CID","message":"Hello!","nonce":"unique-1"}
// Success: {"type":"chat_ack","nonce":"unique-1","message":{...}}
// Failure: {"type":"chat_error","nonce":"unique-1","request":"chat_send","error":"..."}

Comments above are explanatory and are not part of a JSON frame. Never send application commands merely because the TCP/websocket connection opened. Authentication is a separate asynchronous step. Check tos_required and granted scopes in auth_success.

REST DM sending uses message, while websocket im_send uses body. These are intentionally different wire formats. Send operations with a nonce are not automatically idempotent; the nonce correlates replies rather than deduplicating writes.

Important inbound events include chat_message, chat_message_update, chat_message_delete, chat_member_update, presence_update, im_received, im_sent, im_unread, notification_new, notifications_updated (see Notifications), group_update, group_removed, restrictions, game_status, game_console, game_linked, game_unlinked and voice/call events. See the exact observed type names and fields in the catalogue below.

Reconnect correctly

1. Reconnect with bounded exponential backoff and jitter.
2. Authenticate again and rejoin subscriptions/rooms.
3. Refetch server state and unread/history using REST. Dedupe messages by ID.
4. Restore your activity and negotiate voice again if the user still intends to join.

The user websocket has no durable sequence resume or message replay guarantee. Group room history and legacy global/room messages are held in memory. Do not use them as durable storage. Legacy username/password websocket auth and global chat frames exist for compatibility; new clients should use scoped token auth and server channels.

Activity and presence

REST works well for tools without a persistent websocket:

POST /chat/presence/activity
{"key":"my-client","name":"My game","type":"playing","state":"In the menu","ttl":600}

DELETE /chat/presence/activity/my-client

POST /chat/presence/status
{"status":"dnd"}

POST /chat/presence/custom
{"text":"Working on a client"}

REST activities accept a key, name, type, details, state, icon, image, url, app, since, duration, progress, progress_at and ttl. Name is required and limited to 80 characters; details/state to 128. Type is playing, listening, watching, competing, streaming or custom. Images/links require HTTPS. Timing fields are milliseconds. The project token's name can determine the source app label.

Activity TTL defaults to 600 seconds and clamps to 30 through 3600. Refresh before expiry. An account can have up to five keyed HTTP activities. DELETE without a key clears all its HTTP activities; use a key to avoid clearing another integration.

Websocket rich presence is scoped to that socket and clears when it disconnects. HTTP activities live until cleared or their TTL expires. Offline/invisible status, privacy and share_activity can hide activity from other users. GET /chat/presence/:username or /chat/users/:username to refetch; do not assume a cached presence is current.

Mobile presence. Every presence object (the presence_update event, chat_ready you.presence, member lists, GET /chat/presence/:username and the bot gateway) carries a boolean mobile next to status. It is true only when the account is online, idle or do-not-disturb and every connected session is a phone; any desktop, web or bot session makes it false, and offline or invisible accounts are always false. Clients report it by adding "mobile": true to the auth_token frame (omit it or send false otherwise); the Ember desktop app never reports mobile. The public profile response (GET /account/lookup/:username) also includes mobile. Ember shows a small phone icon in place of the square status dot when it is true.

Console presence. Presence objects also carry a boolean console (additive; older clients can ignore it). It is true when the account is online, idle or do-not-disturb and at least one of its live websocket connections is a game console, that is a connection that sent {"type":"arcade_join","platform":"3ds"} (the Nintendo 3DS Nookara Arcade client) and has not sent arcade_leave or closed. Console wins over desktop, web, phone and bot sessions, and when it is true mobile is false. Offline and invisible accounts are always false, so a console never reveals an invisible user. Friends-only profiles expose the flag like status. The public profile response (GET /account/lookup/:username) also includes console. Ember shows a small gamepad icon in place of the status dot when it is true.

Connected clients and last online. Presence objects can also carry sessions (the account's connected clients: state, via, version, platform, device, connected_at), last_online and last_login. They are additive and only sent to the account itself and to people with Manage users in a server they share (never to anyone else, and blocked or friends-only profiles are not widened). last_online is a millisecond timestamp of when the account last went fully offline, that is when its last active websocket closed (so null means unknown); while status is not offline the account is online now and clients show that instead. last_login is the older field and keeps its meaning (when the account last connected to the chat); new clients should use last_online.

Console activity. Activity objects (presence activities, member lists, GET /chat/presence/:username, GET /account/lookup/:username and the bot gateway) carry an additive platform field: "3ds" or absent/null. While an account has a live console socket (arcade_join with "platform":"3ds", not yet arcade_leave or closed) the server adds an automatic activity {"type":"playing","name":"Nookara Badge Arcade","platform":"3ds","source":"console","app":"Nookara","details":"<machine>"}, where details is the last arcade_where machine value (empty until sent) and since is when the console joined. Clients should render it as "Playing on 3DS" with a small 3DS icon instead of "Playing <name>". Ordering: it is listed first, ahead of any Hyperfocus game, websocket rich presence or HTTP integration activity, which stay in the list after it (so one-line subtitles show "Playing on 3DS" while the console is connected). It follows the same rules as every activity: offline or invisible accounts and share_activity: false hide it from other users, and friends-only profiles show it only to friends. It cannot be set or cleared through set_rich_presence or the REST activity routes; those ignore platform.

Auto-idle. Presence objects also carry auto_idle. When it is true, status is idle even though the account's saved status is online. It is computed, never saved: it applies only when the chosen status is online, every connected session is an Ember client with no activity for about ten minutes (the same window that routes notifications to other devices), and no game, launcher, extension or bot session is connected. Offline, invisible, do-not-disturb and a manually chosen idle are never changed. Any activity (the Ember client sends chat_active at most every 30 seconds while in use) or a new non-Bonfire session clears it and the saved status returns by itself. Both changes arrive as normal presence_update events.

Voice and video signaling

Voice media uses WebRTC through a Cloudflare SFU. A JSON join request alone does not transmit audio. Your client needs microphone capture, WebRTC peer connections, remote audio playback and device controls. Request Chat and Voice scopes, then authenticate the user websocket.

The frames below are the same on a Nookara socket (legacy servers and DM calls) and on an Ember instance gateway: on an instance, send them to wss://INSTANCE/gateway with a session that holds the voice scope (the person's Nookara Voice permission, which they may decline). The instance uses its own Cloudflare keys or Nookara's voice broker, and answers voice_unavailable or voice_cap_reached when neither is possible. DM calls (bfc_... rooms) always stay on Nookara.

A voice channel room is bf_ plus its user API cid, such as bf_c0123456789. Server membership, channel visibility, Send permission and the configured user limit determine entry. DM calls use the room returned by POST /chat/calls with {"to":"username"}; do not construct call-room identifiers yourself.

1. Send chat_rtc_join with room and unique nonce. Await chat_rtc_joined, containing iceServers and current people.
2. Create two WebRTC connections with those ICE servers: one for publishing and one for receiving. Keep them separate.
3. Add microphone audio to the publishing connection. Create/set a local SDP offer and wait for ICE gathering to finish. For each transceiver include its mid and a trackName.
4. Send chat_rtc_publish with room, nonce, sessionDescription:{type,sdp} and tracks:[{mid,trackName:"audio"}]. Apply the returned SDP from chat_rtc_published as the remote description. If it is an offer, create a local answer and send chat_rtc_answer with session:"publish".
5. Wait for the publisher's WebRTC connection state to become connected. Only then send chat_rtc_connected with room. This is what announces an actually connected participant.
6. Handle chat_rtc_room snapshots. Build the complete desired subscription list from other participants' tracks: sources:[{userId,trackName}]. Send it as chat_rtc_subscribe with room and nonce. It replaces the desired set; sending only newly added tracks can unsubscribe earlier peers.
7. If the reply is chat_rtc_offer, apply its SDP to the receiving connection, create/set an answer, wait for gathering, then send chat_rtc_answer with session:"receive". Await chat_rtc_ready. A subscription with no new allocations can return ready directly.
8. Play receiver tracks when they arrive. On departures or a peer rejoining, rebuild the desired snapshot, including any new SFU session mapping. Serialize SDP renegotiations to avoid overlapping offers.
9. To stop one producer track, send chat_rtc_close with tracks:["camera"]. To leave, send chat_rtc_leave, stop capture, close both peer connections and release playback resources.

{"type":"chat_rtc_join","room":"bf_CHANNEL_CID","nonce":"join-1"}
{"type":"chat_rtc_publish","room":"bf_CHANNEL_CID","nonce":"pub-1",
 "sessionDescription":{"type":"offer","sdp":"GENERATED_SDP"},
 "tracks":[{"mid":"0","trackName":"audio"}]}
{"type":"chat_rtc_connected","room":"bf_CHANNEL_CID"}
{"type":"chat_rtc_subscribe","room":"bf_CHANNEL_CID","nonce":"sub-1",
 "sources":[{"userId":123,"trackName":"audio"}]}

Allowed producer track names are audio, camera, screen, and screen_audio, up to four per publish. The server returns only accepted tracks. Use chat_rtc_ice for refreshed ICE credentials. There is no separate trickle-candidate frame in this protocol, so send gathered SDP. Never expose SFU app secrets; the server holds those.

In Chromium, start decoding remote audio through an active media element. The existing extension uses a muted audio element for decoding plus Web Audio gain for playback/volume. Resume the AudioContext from a user gesture. A negotiated track with no audible output is not proof that audio transport failed.

Calls and soundboard

To ring a user into a room you joined, send voice_call with to and room. Retain the callId from voice_call_ringing or voice_call_incoming. Answer with voice_call_answer (callId, accept); the original caller cancels with voice_call_cancel (callId). Calls time out after 30 seconds. Handle incoming, accepted, answered, ended and failed events and clean up signaling and media state. Channel call-in settings and user preferences can reject a call. Legacy call_user/call_end peer signaling is a different protocol with recipient fields.

voice_sound takes sound, a sound ID from /chat/sounds. Playback is relayed to participants in the same voice/call room, with a per-user cooldown. Clients play the returned sound locally and honor deafen/output volume.

Legacy Nookara Voice relay frames (voice_connect, voice, voice_disconnect) remain in the frame inventory for existing projects. Use the RTC sequence above for Ember-compatible voice channels. The Python library transports signaling but deliberately makes no claim that a signaling-only client has joined audible voice.

Direct messages, groups and friends

Direct messages are Nookara's Instant Messages and are separate from Ember servers; they are the same whichever Ember server you are looking at. They use /im; /mail is a compatibility alias with the same router (the old vMail name). Read requires Read Instant Messages (64), send/edit/delete requires Send Instant Messages (128); a person may decline either. A recipient's friends-only privacy still applies.

POST /im/send
{"to":"username","message":"Hello!"}

GET /im/status-reply/username
POST /im/send
{"to":"username","message":"Same!","status_reply":{"text":"their current custom status"}}

GET /im/conversations
GET /im/with/username?before=123&limit=50
POST /im/with/username/read

POST /groups
{"name":"Project group","members":["alice","bob"]}

POST /groups/ROOM/messages
{"message":"Hello everyone!"}

POST /friends/request
{"username":"alice"}

DM history is chronological; limit defaults to 50 and clamps to 200. The send response includes message and delivered; false means saved but the recipient was not online for immediate delivery. Websocket im_send supports reply_to; the current HTTP send route does not forward that field. Both routes accept status_reply.

Replying to a status. Ember can answer someone's custom status. Call GET /im/status-reply/:username first: it returns {"can":true,"text":"..."}, or {"can":false,"reason":"own|bot|no_status|friends_only|not_found"}. Then send the DM with status_reply: {"text": <that status>} (REST POST /im/send or websocket im_send). The server checks the text against the person's status right now and that you can see it (offline, invisible and friends-only profiles hide it) and answers status_changed (HTTP 409) if it does not match; cannot_reply_own_status and dm_privacy (HTTP 403, see DM privacy) also apply. The saved message carries status_reply: {"text"} (or null) in DM history, im_received/im_sent events and conversation lists. Push and notification text for such a message is "NAME replied to your status: MESSAGE".

Blocking users

Blocking is mutual in effect: if A blocks B, neither can see the other's profile, message, call, pay, subscribe to or friend the other, and each looks offline to the other. Only the blocker can unblock. Nookara staff (owner, admin, mod) cannot be blocked. Blocks never remove anyone from a shared Ember server, and channel messages keep flowing there, but a blocked pair get no mention, reply or push notifications from each other.

GET    /account/blocks                 -> {"blocks":[{"username","pfp_url","color","created_at"}]}   (needs Friends read)
POST   /account/blocks                 {"username":"alice"}   -> {"success":true,"blocked":"alice"}   (needs Friends manage)
DELETE /account/blocks/alice           -> {"success":true,"was_blocked":true}

Blocking removes any friendship and pending friend requests between the two accounts and ends any DM call. Errors: cannot_block_self (400), cannot_block_staff (403), user_not_found (404). A websocket blocks_changed event ({"blocked","on"}) tells your other sessions that your block list changed.

GET /chat/users/:username (the profile card behind Ember) includes blocked_by_me, true when you have blocked that account; it is how a client picks Block or Unblock. Python (0.5.6): velora.get_blocks(), velora.block_user("alice"), velora.unblock_user("alice"). PenguinMod extension (1.7.1): block user, unblock user, blocked users (JSON) and is [user] blocked? in the Blocking section.

DM privacy: who can message you

GET   /account/dm-privacy              -> {"dm_privacy":"everyone","options":["everyone","friends","servers"]}   (needs Chat)
PATCH /account/dm-privacy              {"dm_privacy":"servers"}   -> {"success":true,"dm_privacy":"servers"}

everyone is the default. friends lets only your friends message or call you. servers also lets in people who share at least one Ember server with you. It is the same value as the dm_privacy chat setting (/chat/settings). Nookara staff (owner, admin, mod), bot accounts and system messages always get through. It applies to starting a DM, sending a DM message (POST /im/send, websocket im_send) and DM calls (POST /chat/calls). A sender it stops gets dm_privacy (HTTP 403) with the message "Failed to send this message due to the users privacy settings"; the websocket answers im_error with the same error and message. This replaces the old dms_friends_only error. An invalid value gets invalid_dm_privacy (400). Python (0.5.6): velora.get_dm_privacy(), velora.set_dm_privacy("friends"). PenguinMod extension (1.9.3): set DM privacy to and DM privacy.

What a blocked pair see. GET /account/lookup/:username, /hyperfocus/profile/:username, /badges/user/:username, /arcade/profile/:username and the user searches answer exactly like a username that does not exist (404), so a block is never revealed to the person it was set on. Direct messages, group-chat adds, DM reactions and DM calls answer 403 {"error":"user_blocked","message":"You can't message this user"}; websocket im_send sends im_error with user_blocked, and a voice call attempt fails with voice_call_failed reason blocked. Payments (/currency/transfer, /currency/transfer-request and its confirmation, subscriptions, Bot payments, the chat bots' send commands and store purchases from a blocked seller) answer 403 {"error":"user_blocked","message":"You can't send credits to this user"}. A friend request to someone who blocked you answers user_not_found; if you blocked them it is user_blocked. Existing conversations with a blocked account disappear from /im/conversations, the inbox and the thread routes until it is unblocked.

Account notices

One-time "what's new" popups. Each notice has an id; a client shows it once and then marks it seen, which dismisses it for the account on every surface (the dashboard and all Ember clients). Some notices only go to accounts created before a cutoff.

GET  /account/notices                   -> {"notices":["privacy-settings-2026-10"]}
POST /account/notices/privacy-settings-2026-10/seen   -> {"success":true}

Any signed-in token works. Marking seen is idempotent; an unknown id answers 404 {"error":"unknown_notice"}. Current ids: privacy-settings-2026-10 (blocking and DM privacy; accounts created before 2026-10-29).

Free received-message capacity is 100; Pro capacity is 50,000. A full inbox evicts older messages when new ones arrive. Design clients to reflect server state rather than assuming permanent infinite history.

Group REST endpoints require Chat. Owners control renaming/member additions/deleting the group; ordinary members can leave. Group messages use in-memory room history, so they do not have the persistence guarantees of server messages or DMs. Use the group room returned by the API. Friend request acceptance uses its request id, not a username.

Media and uploads

Ember chat attachments are uploaded to the instance, not to Nookara: POST INSTANCE/api/v1/media/upload and /media/import (see Uploads and media import). The routes below are Nookara's own media storage (profile pictures, saved media, projects).

Use multipart/form-data for files. Let your HTTP library generate the boundary; do not set a bare multipart Content-Type yourself. Send scalar form fields before file parts for chunk uploads.

Temporary storage (/t/)

Files sent in DMs and group chats with "Temporary storage" live at https://nookara.cc/t/ID/NAME (ID = 22 random letters and digits; NAME is only for people). No sign-in is needed to open one. Every load resets the file's expiry to now + its time to live (it never adds on top), so a file people keep opening stays and one nobody opens is deleted:

Nookara Pro: files sent by a Pro member (Pro at the time of the upload) live twice as long in every row and with the popularity bonus, up to 120 days instead of 60 (TEMP_FILES_PRO_MULT / TEMP_FILES_PRO_MAX_DAYS on the server). Pro members can also send expires_in_days with the upload to pick a fixed expiry instead; that date is final, loading the file never moves it. The full table, for free and Pro, is at /temp-files and as JSON at GET /t/policy: { kinds: [{ kind, max_mb, free: { base, popular_3, popular_10 }, pro: { ... } }], popular_bonus, free_max_days, pro_mult, pro_max_days, manual: { pro_only, presets, min_days, max_days, resets_on_view }, max_file_mb, daily_mb, store_gb, ... }.

Popular files live longer: x1.5 once 3 different people loaded it in the last 7 days, x2 at 10, never more than 60 days (120 with Pro). The expiry is written at most once every 10 minutes per file. When the store (8 GB) is full, the files nobody loaded for the longest go first. Pictures, videos, sounds and plain text open in the browser; everything else (HTML, SVG, scripts, PDFs, archives...) always downloads, and every response is sandboxed (Content-Security-Policy: sandbox, X-Content-Type-Options: nosniff). Add ?dl=1 to force a download. GET /t/info/ID returns { id, name, mime, size, expires_in, ttl_days, fixed, pro } without counting as a load (ttl_days is null when fixed). Expired or missing files answer 404 (temp_file_expired / not_found).

import uuid
from pathlib import Path

path = Path("video.webm")
chunk_size = 10 * 1024 * 1024
total = (path.stat().st_size + chunk_size - 1) // chunk_size
session = uuid.uuid4().hex
with path.open("rb") as source:
    for index in range(total):
        api.post_media_video_chunk(
            data={"sessionId": session, "chunkIndex": index, "totalChunks": total},
            files={"chunk": ("chunk.bin", source.read(chunk_size), "application/octet-stream")},
        )
result = api.post_media_video_finalize(json={
    "sessionId": session, "mimeType": "video/webm", "originalName": path.name,
})

Create a fresh random session ID, use zero-based chunk indices, keep totalChunks constant, and finalize only after all chunks succeed. Sessions expire after two hours. The API checks ownership of an existing session. Large direct base64 uploads can hit the 60 MiB HTTP JSON-body limit even when the media limit is larger.

Media and cloud storage share account quota: 250 MiB for Free and 2 GiB for Pro. GET /storage-info/info/usage returns usage and limits. Delete only your own upload IDs with /media/:id. External Catbox files have different ownership/deletion behavior; deleting a Nookara message does not delete a public third-party file.

Other upload endpoints include server/role/channel icons, bot avatars, emoji, webhook avatars and soundboard clips. Their authorization, file field and error keys are listed per route. Images can be resized/re-encoded by the server; do not assume original byte preservation.

Storage, accounts and achievements

Storage is private to the token's account and divided by your chosen storageId. It is not a globally shared bucket. Keys and values count toward the account's shared quota. Values are strings.

PUT /storage/my-client/save
{"value":"{\"level\":3,\"coins\":40}"}

GET /storage/my-client/save
// {"value":"{\"level\":3,\"coins\":40}"}

GET /storage/my-client/keys
GET /storage-info/info/usage

Use JSON serialization for structured saves. DELETE /storage/:storageId/:key removes one key; DELETE /storage/:storageId clears that entire namespace. Storage Read is 16 and Write is 32.

Account routes cover the current account, public lookup/search, profile updates, username/password changes, export, sessions and deletion. Profile privacy can limit lookup. PATCH /account/update accepts bio, pronouns, timezone, country_code, color, profile_visibility and website. pronouns is plain text of up to 40 characters (control characters and line breaks are removed; an empty string or null clears it). The public profile response (GET /account/lookup/:username), GET /account/me (profile.pronouns) and the bot REST user object (GET /bot/user/:username) return it as pronouns (a string, or null when unset). Like the bio, it is left out of lookup for friends-only profiles you cannot see. Do not assume a token with profile access should receive email or session history; sensitive fields use separate scopes and server checks.

Friends on profiles. PATCH /account/update also accepts show_friends (boolean, default on) and friends_public_notice (only true: marks the one-time "your friends list is now public" notice as seen). GET /account/me returns both in profile (show_friends, and friends_public_notice where true means the notice was already seen). When a profile is fully visible and show_friends is on, GET /account/lookup/:username adds friends (up to 200 of { username, pfp_url, pfp_animated, color }, sorted by name) and friends_count (the true total). With it off the response has friends_hidden: true and no list, except for the account itself, which still gets the list plus friends_hidden: true. Friends-only profiles you cannot see never include friends.

Hyperfocus library and joining. GET /hyperfocus/profile/:username adds library: an array of the games in the user's Hyperfocus library (the launcher stores the ids in hyperfocus/library storage, and purchases count too). Each entry has the same fields as games entries (without achievements) plus owned (bought), seconds (playtime) and play; it is sorted by playtime then name, and is [] for profiles you cannot see. When the running game allows friends to join, playing gets joinable: true; playing.joinCode is only returned to the user's friends (and the user) and never in any public output. The same joinable / joinCode pair appears in activity of friend_activity pushes and GET /hyperfocus/friends, which are friends-only.

Achievements are game-scoped. GET /achievements?game=GAME_ID lists the account's state; POST /achievements/:id/grant or /revoke uses JSON {"game":"GAME_ID"} and Project Auth scope. Badge routes describe profile badges separately from game achievements.

Credits, payments and subscriptions

Currency Read (8192) is separate from Currency Pay (1024). Balance/transactions do not authorize transfers. Payment requests provide a browser approval page for programs that cannot embed CAPTCHA.

1. POST /currency/transfer-request with {"to":"recipient","amount":10,"note":"Example purchase"}.
2. Open the returned url for the user. The response includes the request id and expiresIn.
3. Poll GET /currency/transfer-request/:id and display pending, paid, cancelled, expired or failed.
4. If the user cancels your UI while the request is pending, POST /currency/transfer-request/:id/cancel.

Requests expire after ten minutes. The confirmation endpoint requires the correct signed-in account and CAPTCHA approval. Never bypass CAPTCHA or automatically confirm on behalf of the user. Direct transfer requires captcha_token unless the server recognizes a current CAPTCHA pass. Treat payment request IDs as sensitive capabilities.

The reference also covers outgoing/incoming recurring subscriptions, cancellation, daily claim, credit-purchased Pro, role shops, and store purchase/refund endpoints. Subscription periods are weekly, biweekly, monthly, bimonthly or yearly. Recurring payments and purchases change real account balances; obtain the user's intent for each appropriate action and do not retry uncertain writes blindly.

Bots, gateway and webhooks

from velora_api import Instance
import os

bot = Instance("https://chat.ikelene.net", bot_token=os.environ["BONFIRE_BOT_TOKEN"])
print(bot.bot_discovery())                  # {"api_code_version", "endpoints": {api, gateway, ...}}
print(bot.bot_me())                         # the bot's own user object
for guild in bot.bot_guilds():              # the one community it is in
    for channel in bot.bot_channels(guild["id"]):
        print(channel["id"], channel["name"])
bot.bot_send("NUMERIC_CHANNEL_ID", "Hello from my bot!")

Bot routes use content, not the user API's message. Guild, channel, message and user ids in bot representations are numeric row ids serialized as strings; role ids have a compatibility mapping (@everyone is the guild id). Read them from bot responses and do not transform ids yourself. Bots do not hold DMs through this API. A bot posts as a member, so Send permission, locked channels and no-chat channels apply; the limit is 150 requests per bot per 10 seconds.

Bot aliases

A bot can post a message under another name and avatar, for example a narrator, a character or a relayed speaker. The alias is only how the message is shown. The real bot stays the author: author is still the bot: mentions, moderation and reports always use the real bot. Only bots can set an alias. A user or session token that sends alias gets 403 alias_bots_only; this covers POST, PATCH (even "alias": null) and the websocket chat_send.

Send it with the call that posts the message: bot REST POST /bot/v1/channels/:cid/messages (with content). Interaction responses (types 4 and 7), followups and edits of @original or a followup take it as data.alias; ephemeral interaction messages ignore it. The bot gateway has no message send. To change it later, PATCH /bot/v1/channels/:cid/messages/:mid on the bot's own message: leaving alias out keeps the existing one, an object replaces it and "alias": null clears it (content may be left out when only the alias changes). A bot can edit only its own messages. A value that breaks a rule above is refused with 400; through the bot API the body is {"message":"alias.name must be 1-32 characters","code":0} (the internal error code is invalid_alias).

curl -X POST "https://INSTANCE/bot/v1/channels/NUMERIC_CHANNEL_ID/messages" \
  -H "Authorization: Bot BOT_TOKEN" -H "Content-Type: application/json" \
  -d '{"content":"The door creaks open.","alias":{"name":"Narrator","avatar_url":"https://example.com/narrator.png"}}'

# clear the alias again
curl -X PATCH "https://INSTANCE/bot/v1/channels/NUMERIC_CHANNEL_ID/messages/MESSAGE_ID" \
  -H "Authorization: Bot BOT_TOKEN" -H "Content-Type: application/json" -d '{"alias":null}'

// JavaScript (Node 18+ or a browser; keep the bot token on a server)
const api = "https://INSTANCE/bot/v1/channels/NUMERIC_CHANNEL_ID/messages";
const headers = { Authorization: "Bot " + process.env.BOT_TOKEN, "Content-Type": "application/json" };
const sent = await (await fetch(api, { method: "POST", headers, body: JSON.stringify({
  content: "The door creaks open.",
  alias: { name: "Narrator", avatar_url: "https://example.com/narrator.png" },
}) })).json();
console.log(sent.alias);   // { name: "Narrator", avatar_url: "https://example.com/narrator.png" }
await fetch(api + "/" + sent.id, { method: "PATCH", headers, body: JSON.stringify({ alias: { name: "Storyteller" } }) });

from velora_api import Instance, make_alias      # velora-api-client 0.5.8 or newer
import os

bot = Instance("https://chat.ikelene.net", bot_token=os.environ["BONFIRE_BOT_TOKEN"])
sent = bot.bot_send("NUMERIC_CHANNEL_ID", "The door creaks open.",
                    alias={"name": "Narrator", "avatar_url": "https://example.com/narrator.png"})
bot.bot_edit("NUMERIC_CHANNEL_ID", sent["id"], alias=make_alias("Storyteller"))   # change it
bot.bot_edit("NUMERIC_CHANNEL_ID", sent["id"], alias=None)                        # clear it

Reading it. Every message object (history, search, pins, starboard, the websocket chat_message and chat_message_update, and the Discord-shaped MESSAGE_CREATE and MESSAGE_UPDATE of the bot gateway and Bot REST), and so do reply.alias and referenced_message.alias has alias: {"name","avatar_url","unmarked"} (plus member_id on a matched unmarked alias) or null. Messages from before the feature, from people, webhooks and the system, have null; avatar_url inside an alias can itself be null. Bots that react to messages should check author, not the alias, to tell who really wrote something.

What people see. Clients show the alias name and avatar in place of the bot's, with a small mask icon next to the name, and a tooltip "Posted by BOT as ALIAS" so nobody is misled about who is behind the message. Mentions, moderation and reports always use the real bot. In the PenguinMod extension, send [TEXT] as bot [TOKEN] to channel id [CHANNEL] on [URL] with alias [NAME] and avatar [AVATAR] posts one, and the alias name, alias avatar and alias unmarked? choices of the latest-message reporter read it. A project that includes a bot token should never be shared.

Unmarked aliases (risky, off by default)

An Ember server's owner can let bots post aliases that look exactly like a member's message. It is buried on purpose: Server settings, Danger zone, Advanced, "Allow unmarked aliases". Only the owner can change it (anyone else gets 403 owner_only), turning it on asks for confirmation, and every change is in the audit log as unmarked_aliases_update. It is the advanced.unmarked_aliases key of GET / PATCH /api/v1/servers/:sid/settings, and it is never exported or imported with a server. A bot also needs the Use unmarked aliases role permission (bit 4096, Ember servers only) or Administrator.

While both hold, the bot's aliases carry "unmarked": true. The server then looks the alias name up among that server's members only, trimmed and in any case: one member whose username matches, or else one member whose display name matches. Two or more matches count as none. A match adds member_id. It is worked out every time a message is read, so turning the setting (or the permission) off marks old messages again, and turning it on unmarks old ones. Clients show an unmarked alias with no mask, no tooltip and no BOT tag, in the matched member's name colour; the avatar is avatar_url, else the member's picture, else the bot's; clicking the name opens the member's profile (the bot's when nobody matched).

The real bot is still author and still what mentions, notifications, blocks, mutes, reports, moderation and the audit log use. People with Manage messages see the real sender under "Message info" in the message menu. Messages only ever exist in that server's channels, so an unmarked alias never reaches DMs or another server.

// is this alias pretending to be a member? check author, never the alias
if (msg.alias && msg.alias.unmarked) console.log(msg.author.username, "posted as", msg.alias.name, "matched member", msg.alias.member_id || "none");

GET /bot/discovery advertises the endpoints and GET /bot/v1/gateway returns the gateway URL without authentication; /gateway/bot needs a Bot token.

Bot gateway sequence

1. Connect to wss://INSTANCE/bot/gateway. Receive {"op":10,"d":{"heartbeat_interval":...}}.
2. Send Identify {"op":2,"d":{"token":"BOT_TOKEN"}} within 20 seconds. A bad token closes with 4004.
3. Send opcode 1 heartbeats on the interval and track opcode 11 acknowledgements.
4. Read dispatch frames {"op":0,"t":"MESSAGE_CREATE","s":1,"d":{...}}. READY is followed by GUILD_CREATE (the whole community, also when a manager adds the bot), then GUILD_UPDATE, GUILD_DELETE, GUILD_MEMBER_ADD and GUILD_MEMBER_REMOVE, MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, MESSAGE_REACTION_ADD and MESSAGE_REACTION_REMOVE. A bot only receives events for channels it can see.

The server accepts opcode 6 by re-identifying; it does not implement durable Discord-style event replay. Resync guild, channel and message state after reconnect. A missed-heartbeat session can close with 4009. Bot gateway transport is documented here and is wrapped by the Python BotGateway (one instance) and BotProgram (every instance the bot is installed on), not by RealtimeClient.

Bot presence (the status dot)

A bot is online in each community it belongs to while at least one authenticated connection to that instance's /bot/gateway has been sent READY; otherwise it is offline. Other connections and REST requests do not count, several gateway connections count independently, and the last one closing, erroring, being revoked or timing out makes the bot offline. Heartbeats expire after 2.5 times the advertised interval (41250 ms), checked every 15 seconds. Presence lives in memory on the instance and starts offline after a restart. A bot installed on several instances has one presence per instance.

• Member payload. GET /api/v1/servers/:sid/members and the member of chat_member_update (including change: "joined") carry presence: "online" or "offline" for bots, and null for people (instances do not relay human presence).
• Event. Changes arrive on the instance websocket as {"type":"chat_presence","server":"SID","user_id":"b:N","username":"BOT NAME","presence":"online"} (or "offline"). They are coalesced for 2 seconds and sent only to current members of that community; an unchanged status sends nothing, so a quick reconnect may produce no event. Update the matching member's presence to draw the dot.
• The bot gateway does not support presence in Identify or opcode 3 (Update Presence): statuses such as idle, dnd or invisible are ignored, there is no invisible mode, and a live READY connection is online. Presence is not exposed through profiles or the Discord-shaped Bot REST user objects, only in the community member view.

Incoming webhooks

Create and list webhooks with the instance routes under /api/v1/channels/:cid/webhooks (Manage channels). Execute the returned secret URL without any token:

curl --fail-with-body -X POST "$BONFIRE_WEBHOOK_URL?wait=true" \
  -H "Content-Type: application/json" \
  --data '{"content":"Build finished","username":"Build service"}'

Supported body keys include content, username, avatar_url and embeds. Multipart uploads use file parts and a JSON-string payload_json field. ?wait=true returns the posted message; otherwise success is empty 204. Webhooks also support GET info and DELETE by secret URL. Never publish that URL or treat it as a harmless identifier.

Bot payments

A bot can ask a Nookara user for credits and learn whether they paid. The bot calls the Nookara API with its bot token, gets an official payment link, and sends the buyer there. The buyer signs in on nookara.cc with their normal login and presses Pay. They do not authorize the bot, no scopes are involved, and the bot never receives a user token or any access to the buyer's account. There is no webhook: the bot polls.

Money model

• The recipient is the bot's owner (the Nookara account that owns the developer bot). It is fixed on the request when you create it and cannot be changed or redirected. Bots hold no credits themselves; payments land in the owner's normal Nookara balance and appear as a normal transfer with the note BOT: order ORDER_ID [bp:REQUEST_ID], and a credits notification.
• The owner cannot pay their own bot (self_payment). The owner must not be banned or suspended and the bot must not be banned from the gallery.
• Fulfil an order only when status is paid, and compare amount and buyer.id with your own order.

Authentication and base URL

Authorization: Bot BOT_TOKEN on every call to https://nookara.cc/bot/payment-requests. This is the same token an Ember bot uses (create or reset it in the bot settings). A user or session token is refused with 401 invalid_bot_token. Every request you make is scoped to your bot: bot A cannot read, cancel or list the requests of bot B (404 not_found).

Create a payment request

POST /bot/payment-requests with a JSON body:

The answer is 201 with the request:

{ "id": "bpr_9f2c...", "order_id": "ord-1001", "amount": 20, "status": "pending",
  "description": "Premium pack", "metadata": null, "return_url": "https://shop.example/done",
  "pay_url": "https://nookara.cc/pay/bp_<32 hex>",
  "buyer": { "id": "260", "username": "alice" },
  "created_at": "...Z", "expires_at": "...Z", "paid_at": null, "transaction_id": null }

Idempotency. The same order_id with the same buyer and amount returns the existing request with 200 and "idempotent_replay": true, whatever its status, so a retry after a network error is safe. The same order_id with a different buyer or amount is 409 order_id_conflict. To retry an order that expired, was cancelled or was declined, create a new order_id.

Read, find, list and cancel

• GET /bot/payment-requests/:id returns the same object.
• GET /bot/payment-requests?order_id=ORDER finds a request by your order id (the same object, 404 not_found if none).
• GET /bot/payment-requests?limit=25&status=paid lists your latest requests as {"requests":[...]}.
• POST /bot/payment-requests/:id/cancel cancels a request that is still pending. 409 payment_in_progress if the buyer is paying right now, 409 not_cancellable once it is paid, declined or expired. Cancelling an already cancelled request is a no-op 200.

Statuses

A payment claim left half-done by a server crash is settled after about 60 seconds: paid if the transfer exists, otherwise back to pending.

The hosted pay page (buyer side)

The public payment URL has the format https://nookara.cc/pay/bp_ followed by 32 random hex characters (unguessable). That is all a bot needs to know about the page; the page's own API is internal and is not part of the bot API.

1. The page shows the bot (name, avatar, Verified badge from the bot gallery), the seller account (the bot owner), the amount, description, order id and expiry.
2. Not signed in: "Sign in to continue" leads to the normal Nookara login and back to the page. No app or scope authorization is involved.
3. Signed in as somebody other than the request's buyer: "This request is for another account". The buyer's identity is never shown to other viewers.
4. Signed in as the buyer: "You are paying N credits to BOT (owner NAME)" with Decline and Pay. Pay uses the standard Nookara payment check (CAPTCHA unless the current 2-day pass is active) and moves the credits from the buyer to the owner.
5. The success page shows a button, and redirects automatically after about 3.5 seconds, to return_url?order_id=ORDER&status=paid (or status=declined) when you gave a return_url. The buyer sees the host of that URL on the button. The status in the URL is informational only: always confirm with the API.

Polling

There are no webhooks. After you send the buyer to pay_url, poll GET /bot/payment-requests/:id every few seconds while they are on the page and back off over time (reads are limited to 300 per minute per bot). Stop at any status other than pending. The Python library has BotClient.wait_for_payment for this.

Errors

Errors are {"error":"code"}.

Limits

60 creates per minute and 300 reads per minute per bot, 300 requests per minute per IP. At most 500 open (pending) requests per bot, 5 open per bot and buyer, and 20 open per buyer across all bots.

Security notes

• Recipient: chosen by the server from the bot's owner; a request cannot be redirected to another account.
• Paying needs the buyer's own signed-in session, a single-use CAPTCHA check, and Currency Pay not switched off by an admin; the signed-in account must equal the request's buyer.
• Double clicks and two tabs cannot charge twice: the request is claimed atomically before any credits move, and a repeated confirm after payment only returns the paid result.
• Expired, cancelled and declined requests refuse payment.
• There is no webhook to trust: never rely on return_url query strings, only on the API.
• The request id and pay_url are capabilities. Keep the bot token server-side; the PenguinMod extension has no payment blocks for this reason.

Examples

BOT="Authorization: Bot $BOT_TOKEN"
curl -sS -X POST https://nookara.cc/bot/payment-requests -H "$BOT" -H 'Content-Type: application/json' \
  -d '{"buyer":"alice","amount":20,"order_id":"ord-1001","description":"Premium pack","return_url":"https://shop.example/done","expires_in":900}'
# 201 {"id":"bpr_...","pay_url":"https://nookara.cc/pay/bp_...","status":"pending",...}   send the buyer to pay_url

curl -sS "https://nookara.cc/bot/payment-requests?order_id=ord-1001" -H "$BOT"
# {"status":"paid","paid_at":"...","transaction_id":"1234","buyer":{"id":"260",...},...}

curl -sS -X POST https://nookara.cc/bot/payment-requests/bpr_.../cancel -H "$BOT"

import os
from velora_api import BotClient, BuyerError, OrderConflict, PaymentTimeout, is_paid

bot = BotClient(os.environ["BOT_TOKEN"])           # velora-api-client 0.5.8
try:
    request = bot.create_payment_request("alice", 20, "ord-1001", description="Premium pack",
                                         return_url="https://shop.example/done", expires_in=900)
except BuyerError as error:                        # buyer_not_found, buyer_is_bot, self_payment, buyer_banned, ...
    raise SystemExit("cannot charge: " + error.error)
except OrderConflict:                              # same order_id, different buyer or amount
    raise SystemExit("use a new order_id")
print("send the buyer to", request["pay_url"])
try:
    final = bot.wait_for_payment(request["id"], timeout=900, poll=3)
except PaymentTimeout:
    bot.cancel_payment_request(request["id"])
else:
    if is_paid(final) and final["amount"] == 20:   # fulfil ONLY when paid
        print("paid, transaction", final["transaction_id"])
    else:
        print("not paid:", final["status"])

Other Python helpers: get_payment_request(id), find_payment_request(order_id) (None if unknown), list_payment_requests(status=None, limit=None) and cancel_payment_request(id). Errors are PaymentError subclasses (InvalidBotToken, MerchantUnavailable, InvalidPaymentRequest, BuyerError, OrderConflict, PaymentInProgress, NotCancellable, PaymentNotFound, PaymentRateLimited), all still APIError. The four routes are also in the REST reference under Bot payments.

These routes are not the user-token payment requests of /currency/transfer-request, where a program asks the signed-in user to confirm a transfer from their own account.

Bot gallery (Discovery > Bots)

The bot gallery lists reviewed bots that anybody can add to an Ember server. A listed bot is verified and shows a checkmark next to its BOT tag, plus "trusted in N servers". Bot ids are the Nookara user id of the bot account as a string (the id from GET /chat/bots, which lists the developer bots you own; create one with POST /chat/bots). Errors are {"error":"code"}.

States

Public routes (no sign-in)

• GET /bonfire/bots/gallery?q=&tag=&page= lists approved bots, 24 per page, most trusted first: {"page","page_size","has_more","results":[{id,username,description,avatar_url,owner,verified,trusted_in,tags,support_url,listed_at}]}. q matches name, descriptions and tags; tag is exact. Limit: 120 per minute per IP.
• GET /bonfire/bots/gallery/tags returns the top 50 tags: {"tags":[{"tag":"music","count":3}]}.
• GET /bonfire/bots/gallery/:id returns the card plus long_description, links (up to 5 of {label,url}) and permissions. A bot that is not approved answers 404 bot_not_found, unless the request carries the bearer token of its owner or of staff; then you also get state, review_message, submitted_at, reviewed_at, can_submit and can_withdraw.

Bot owner routes (bearer, Chat scope)

The owner of the bot (or a Nookara owner-rank account) may use these.

• GET /chat/bots/:id/gallery returns {"gallery":{...detail, state, review_message, submitted_at, reviewed_at, can_submit, can_withdraw},"log":[{by,action,message,at}]} (last 20 log entries).
• PUT /chat/bots/:id/gallery saves listing fields without changing the state: long_description (4000 characters), tags (up to 6, a-z 0-9 and -, 2 to 20 characters), support_url (https), links (up to 5 of {label up to 30, url https}) and permissions (from send_messages, attach_files, manage_channels, manage_server, manage_roles, kick_members, ban_members, manage_messages, mention_everyone, administrator). Errors: invalid_tags, invalid_support_url, invalid_links, invalid_permissions.
• POST /chat/bots/:id/gallery/submit (optionally with the same fields; 10 per minute) moves private, rejected or delisted to pending. The bot needs a description of at least 10 characters and an avatar (description_required, avatar_required), set with PATCH /chat/bots/:id and POST /chat/bots/:id/avatar. Other errors: already_pending and already_listed (409), gallery_banned (403). Resubmitting after a rejection or delisting uses the same route.
• POST /chat/bots/:id/gallery/withdraw returns the bot to private; servers that already have it keep it.

GET /chat/bots entries also carry verified, trusted_in and gallery: {state, verified, review_message, trusted_in}.

Adding a listed bot to a server

1. The person signs in with Nookara (Chat scope) and calls POST /bonfire/bots/gallery/:id/ticket with {"instance":"https://chat.ikelene.net"} (30 per minute). The instance must be registered and not banned. The answer is {"ticket":"JWS","expires_in":300,"bot":{id,username},"test":false}. Errors: invalid_instance, unknown_instance, instance_banned, bot_is_private, gallery_banned, bot_not_found.
2. The ticket is an EdDSA JWS (typ: bonfire-botadd+jwt) signed with Nookara's key (JWKS at /.well-known/bonfire/jwks.json), valid 5 minutes, single use, and bound to that instance and that person.
3. Send it to the instance: POST https://INSTANCE/api/v1/bots/gallery/add with {"ticket":"...","sid":"COMMUNITY_SID"} (instance session, Chat scope). The person needs Manage server there. Errors include ticket_invalid, ticket_expired (410), ticket_used (409), ticket_wrong_audience, ticket_wrong_user (403), already_in_server, not_allowed (403) and gallery_needs_velora_account.

Who may add a bot: its owner (any state except banned), anybody with Manage server when it is approved, and admins for review. Everybody else gets 403 bot_is_private.

How a listed bot runs inside a server

Each instance creates its own bot account for it (BOT tag, verified checkmark, a normal member subject to roles and channel permissions). Its profile and token hash come from Nookara, so the developer connects with the same token: REST https://INSTANCE/bot/v1 and gateway wss://INSTANCE/bot/gateway with Authorization: Bot TOKEN. The bot's code needs one connection per instance it serves (in the PenguinMod extension and the Python library that is the instance URL option). Instances re-check every 10 minutes: a token reset, a delisting or a ban takes effect within about 10 minutes. On the instance, editing a gallery bot, its avatar and its token answer 403 gallery_bot_managed; managers can still remove or kick it. trusted_in counts distinct servers that have the bot.

Python

from velora_api import Client, Instance

velora = Client(token)                                     # needs Chat (2048)
print(velora.list_gallery("music", tag="fun")["results"])  # public
velora.save_gallery_listing("258", long_description="What it does", tags=["music"], permissions=["send_messages"])
velora.submit_to_gallery("258")                            # state: pending
print(velora.gallery_status("258")["gallery"]["state"])
# velora.withdraw_from_gallery("258")

ticket = velora.gallery_ticket("258", "https://chat.ikelene.net")["ticket"]
chat = Instance("https://chat.ikelene.net")
chat.login_with_velora(velora)
chat.add_gallery_bot(ticket)                               # or sid="COMMUNITY_SID"

Bot programs: where is my bot installed?

A bot added from the gallery runs on many instances with one token. GET /bonfire/bots/self/installs with Authorization: Bot TOKEN (120 per minute per IP) answers {"instances":[{"origin":"https://x.example","name":"Server","test":false,"added_at":1792444301439,"seen_at":1792444301439}]} from the instances' 10-minute sync reports. Banned instances are left out and a banned bot gets an empty list. Open one INSTANCE/bot/gateway per origin (discovery: origin + /bot/discovery) and poll again every few minutes; skip test installs. Staff can try a bot before it is listed by adding it to a server as a test install: test installs exist, are returned here with "test":true, and are not counted (they never add to "trusted in N servers"). A bot program should not treat them as real customers. Errors: 401 invalid_bot_token.

from velora_api import BotProgram

async with BotProgram(os.environ["VELORA_BOT_TOKEN"]) as bot:
    async for event in bot:      # {"instance": origin, "type": "MESSAGE_CREATE", "data": {...}}
        ...

Staff review routes exist but are not part of this public guide.

Settings and notifications

These are account-level Nookara settings. Instances have their own per-server version: GET and PATCH /api/v1/settings and GET /api/v1/notify, PUT /api/v1/notify/:target with the same bodies.

Instances also tell you about people through GET /api/v1/identities; Nookara's /chat/identities?ids= (Chat, up to 200 ids) does the same for Nookara accounts.

GET /chat/settings returns settings and defaults. PATCH it with only the properties the user changed. Settings include show_typing, share_typing, share_activity, sounds, notifications, dm_privacy, compact, animations, link_images, server_order, daily_notice, developer_mode, allow_vc_calls, yt_mode, notify_sound, radio_enabled, radio_url and strip_tracking.

Removing tracking from links: strip_tracking is null until the user has been asked (Ember asks the first time a pasted or sent link has tracking junk in it), then true (clean links automatically) or false. When it is true, Ember removes known tracking parameters (utm_*, fbclid, gclid, YouTube/Spotify si, and similar) from links before sending; the server does not change message text, so a client that wants the same behaviour does it before it posts.

Credit balances need CURRENCY_READ: GET /chat/channels/:cid/shop (and the shop responses of the buy and take-off calls) return balance: null when the token lacks the Viewing Subscriptions scope (CURRENCY_READ); the rest of the shop works. account.credits in GET /account/me is null without that scope as well.

Internet Radio (an easter egg from ScratchCord): with radio_enabled on, Ember plays radio_url and draws a visualizer behind the chat. The audio goes through Nookara so the browser may analyse it: POST /chat/radio/ticket with {"url":"..."} returns {"src":"/chat/radio/stream?t=..."}, a signed link for an audio element that is valid for 2 minutes to start. The proxy only fetches public http(s) addresses (ports 80, 443 or 1024 and up), only passes audio content types, and allows 2 streams per account. Errors: bad_radio_url, bad_ticket, too_many_streams, private_address, not_audio, radio_unreachable.

GET /chat/notify and PUT /chat/notify/:target manage per-server/channel preferences. Body: {"level":"mentions","mute_minutes":0,"push":true}. Levels are default, all, mentions or none; mute_minutes is 0 to unmute, -1 forever, or a duration in minutes. Use the server sid or channel cid as target.

Notifications (the bell)

Friend requests, credits, store sales and refunds, badges, membership, hosting and messages from the Nookara team arrive as notifications: the bell next to the account on the site and in Ember, with the full list at /me#notifications. They are separate from direct messages, message history and browser subscription state. The routes live under /account and need only a signed-in token:

GET    /account/notifications?unread=1&category=friends&cursor=LAST_ID&limit=30
GET    /account/notifications/unread-count          -> {"unread": 3}
POST   /account/notifications/read                  {"ids": [1234, 1235]}  or  {"all": true}
POST   /account/notifications/unread                {"ids": [1234]}
DELETE /account/notifications/:id

The list is newest first, up to 50 per page (30 by default). Pass the next_cursor you got back as cursor for the next page; it is null on the last one. All filters are optional.

{"notifications":[{"id":1234,"category":"friends","kind":"friend_request",
  "title":"Friend request","body":"**alice** wants to be your friend","link":"/me#people",
  "icon":"user-plus","actor":{"username":"alice","pfp_url":"https://..."},
  "data":{"from_username":"alice"},"read":false,"read_at":null,"created_at":"2026-10-29T15:04:05.000Z"}],
 "next_cursor":null,"unread":1}

title and body are plain text with one piece of markup, **bold**. Render it yourself and never insert either as HTML. link is a site path such as /me#credits or an https URL (or null); actor is the account that caused it, or null, in which case draw icon (a lucide icon name). kind is a finer type inside the category and may grow new values. The read, unread and delete calls return {"success":true,"unread":N} so a badge can update straight away; deleting an unknown id (or one of another account) is 404 not_found.

Categories and settings. GET /account/notification-settings returns {"categories":[{key, label, description, icon, locked, staff, email, list}]} in the order the settings page shows them. list means it lands in the bell and on the account's devices (browser push, the Ember apps); email means it is also emailed, at most one email per category every ten minutes and 20 a day. The categories are system (announcements from Nookara), moderation, credits, friends, store, membership, badges and hosting, plus staff_signups, staff_feedback and staff_alerts, which only exist for staff accounts (staff: true; other accounts never see them). system and moderation are locked: always on, and shown checked but disabled. Change switches by sending only the keys that changed:

PATCH /account/notification-settings
{"prefs":{"friends":{"list":true,"email":false},"credits":{"email":true}}}

Locked and unknown categories are ignored; the reply is {"success":true,"categories":[...]} like the GET. Any key from that list also works as the category filter of the list.

Live updates. The user websocket delivers two events to every open session of the account, so several tabs and devices stay in step:

{"type":"notification_new","notification":{ ...same shape as the list... },"unread":4}
{"type":"notifications_updated","unread":2,"read":[1234,1235]}
// read is a list of ids or "all"; instead of read you may get "unread_ids":[...] or "deleted":[...]

Apply the change to what you show and use unread as the new badge count. After a reconnect, refetch the list and the count over REST; there is no replay. The Ember Android app's notification-only socket gets notification_new as it is when its auth_token frame includes "capabilities":["notification_new"]; older builds without it get a bonfire_notice copy instead.

System DMs are gone. Nookara no longer creates direct messages from "System" (from_system): everything that used to arrive that way is a notification now, mostly in the locked system category. Old system messages stay in DM history and can still be read.

The older feed. GET /notifications (unread, up to 50), GET /notifications/count ({"count"}), PATCH /notifications/read-all and DELETE /notifications/:id still exist for the Scratch and PenguinMod extension. They read the same notifications with the ** markers removed, as {id, type, category, title, body, data, created_at}. New clients should use the /account routes above.

The /push API is for browser Web Push subscriptions and VAPID. Its switches (GET /push/state, PATCH /push/prefs) cover chat-type events such as messages, calls, mentions and achievements; friends, credits and announcements are notifications and follow the notification settings above instead. A desktop client should use its OS notification settings and display notifications from the relevant events. Do not show browser-permission controls as desktop notification settings. Respect privacy, per-conversation mute and the user's global notification choice.

Featured projects

Featured projects lists apps and games built with Nookara's services. Staff add projects by hand, and anyone signed in can submit their own; every submission waits for review. The homepage shows the same list as a carousel. The listing is public and needs no sign-in, so a launcher, website or bot can show it too.

Reading the list

GET /api/projects returns approved projects, featured ones first (then the staff order, then newest). Query: q (searches the name, tagline and creator), service (one key from GET /api/projects/services), featured=1 (only featured ones), limit (1-100, default 60) and offset. The response is { "total": 12, "limit": 60, "offset": 0, "projects": [...] }. GET /api/projects/<slug> returns { "project": {...} } for one project, or 404 not_found.

{
  "id": 7, "slug": "star-racer", "title": "Star Racer", "tagline": "A racing game with Nookara sign-in",
  "description": "Plain text, may contain newlines", "url": "https://example.com/star-racer",
  "icon_url": "https://nookara.cc/uploads/projects/....webp", "cover_url": null, "show_logo": true, "logo_size": 40,
  "services": ["login", "storage"], "featured": true,
  "creator": { "username": "nat", "pfp_url": "...", "color": "#7c5cff", "profile_url": "https://nookara.cc/u/nat" },
  "by": "Team Star", "page_url": "https://nookara.cc/projects/star-racer", "created_at": "2026-10-29T18:00:00.000Z"
}

show_logo is true by default: when the project has both an icon and a cover, the icon is drawn in the middle of the cover. Send false to show the cover alone. logo_size (10-90, default 40) is the logo's width as a percent of the cover's width; the logo is centered on the cover, keeps its own shape and has no background. creator is the linked Nookara account (or null) and by a free-text credit (or null); a project can have either or both. Every text field is plain text: show it as text, never as HTML. Service keys: login, storage, credits, chat, messages, friends, voice, media, cloudlink, hyperfocus, embed.

curl "https://nookara.cc/api/projects?service=login&limit=12"

from velora_api import Client

velora = Client()  # no token needed to read the list
page = velora.request("GET", "/api/projects", query={"service": "login", "limit": 12}, auth=False)
for project in page["projects"]:
    print(project["title"], "-", project["creator"]["username"] if project["creator"] else project["by"])

Submitting a project

POST /api/projects with a user Bearer token and { "title", "tagline", "url", "services": [...], "description"?, "icon"?, "cover"?, "show_logo"?, "logo_size"? }. The account that sends it is shown as the creator, and the project starts as pending. url has to be a full https address. Names, taglines and descriptions are plain text (anything shaped like an HTML tag is removed). icon and cover are a data:image/...;base64, upload or an https image link (PNG, JPG, WebP or GIF, 5 MB at most); Nookara re-hosts them. Limits: 3 submissions a day per account, 6 a day per connection, and 5 waiting or rejected at once (429 submit_limit, with a readable message).

GET /api/projects/mine lists your submissions in every state, with status (pending, approved, rejected or hidden) and the reject_reason staff gave. PATCH /api/projects/<id> edits a pending or rejected one (send only the fields you change) and puts it back in the queue; DELETE /api/projects/<id> withdraws it. Approved projects can only be changed by staff (409 not_editable). When staff approve or reject a submission, the submitter gets a notification in the projects category (see Settings and notifications), with the reason for a rejection.

Errors are { "error": "invalid", "message": "a readable sentence" }: invalid, rate_limited, submit_limit, bad_image, image_too_large, image_fetch_failed, not_found, not_editable. Staff review submissions in the staff panel; those routes (/admin/projects) need the Featured projects staff permission.

Other integrations and privileged routes

The endpoint inventory also includes OAuth linking, Spotify linking/profile visibility, reports/feedback, Hyperfocus profiles and achievements statistics, the embedded video-player API, desktop sign-in, child tokens, store access and Badge Arcade.

• OAuth and Spotify: start/link opens an interactive provider flow; callbacks are browser endpoints, not ordinary JSON GET requests. Use returned redirect URLs and official approval UI.
• Desktop sign-in: /bonfire/app-code and /app-exchange are the official client's one-use code/deep-link protocol. Generic Python clients should use scoped /auth/ext-code, which does not assume the Ember URL handler.
• Child tokens: /auth/child-token is restricted to approved Hyperfocus Launcher parent sessions, and narrows the parent's grant. It is not a general token-minting endpoint.
• Arcade: game requests depend on server-issued state, physics revision and account eligibility. Staff routes additionally need the configured rank. Treat the catalogue as a protocol inventory, not a way to bypass game state or payment approval.
• Staff: /admin and other staff routes require actual server-side rank checks, often with owner-only restrictions. A user token or scope mask does not grant staff access. Destructive controls must be used only by authorized staff.
• Staff notifications: POST /admin/notifications/send sends a system notification (locked, so nobody can turn it off). Body {"usernames":["a","b"],"title":"...","body":"...","link":"/me","email":false} for up to 200 accounts, or {"all":true,"confirm":"ALL", ...} for everyone, which only admins and the owner may do, once every ten minutes (429 too_soon). title is up to 128 characters, body up to 2000 with **bold**, link a site path or an https URL. The reply is {"success":true,"sent":N,"emailed":false}; unknown names give 404 user_not_found with missing. The older POST /admin/send-vmail ({username, subject, message}) still works and now creates a system notification instead of a DM.

Private service-to-service interfaces are not public client APIs: /bot (except the public bot payment API under /bot/payment-requests), the legacy external-service bot bridges, /store/internal, Hyperfocus internal mail/log callbacks, Ko-fi/payment delivery callbacks, deployment webhooks, and account-link completion callbacks. They require service credentials or trusted integration context. Those credentials, signing secrets and operational deployment interfaces are not included in the downloads.

The old /mail paths alias the documented /im routes. /storage-info mounts the same storage router; /storage-info/info/usage is its intended usage URL. Trailing-slash aliases are counted once.

Errors, limits and compatibility

Instances use the same shape, {"error":"snake_code"}, plus codes such as read_only, member_cap_reached (with cap), plan_limit (with what and limit), managed_setting, bad_signature (with reason), signing_unavailable, insufficient_scope, not_a_member, no_send_permission, community_exists, file_too_large (with max_mb), invalid_media_url, media_import_failed, gallery_bot_managed and the sign-in errors wrong_accounts_mode, token_expired, token_replayed, invalid_audience and banned. Nookara can be in maintenance: 503 {"error":"maintenance"} with Retry-After, which also pauses instance sign-in tickets. Instance rate limits include 30 webhook posts per minute per webhook and 150 bot requests per 10 seconds.

User REST commonly returns {"error":"insufficient_scope","required_scope":2048}, which only means the person did not grant that scope, since none is required: ask them to approve it, or hide the feature. Admin-disabled scopes return scope_disabled with disabled_by_admin. Bot/webhook errors often use {"message":"Missing Permissions","code":50013} instead. A response need not be JSON when it comes from a proxy or an upload middleware.

The current global HTTP limiter allows 150 requests per visitor/IP in 15 seconds; exceeding it causes a five-minute temporary API ban. Bot REST also limits 150 requests per bot per ten seconds. Webhook execution limits 30 per webhook per minute; external uploads 150 per account per hour. Other routes and realtime operations have additional limits. These are current implementation values, not guaranteed service capacity.

Use pagination, debounce typing, cache stable data and back off on errors. Keep IDs as strings and tolerate unknown fields/types. Most user endpoints are unversioned, so review changes when updating your client.

What was verified

The route inventory was checked against the live source snapshot of 19 October 2026 (Nookara and bonfire-server). The SDK is tested with local HTTP/websocket servers for authentication ordering, uploads, encoding, errors, nonce routing and all named REST method dispatches (Nookara and instance), including the instance login flows, the rule that a Nookara token never reaches an instance, scope handling (requested scopes, ScopeError, instance scopes from the ticket), gateway ordering and reconnect, the bot program across several instances, webhooks, invites, media import and the signing format with independent verification. Public live read-only smoke checks verify the deployed API and downloads. The notifications routes and events (29 October 2026) were added from the Nookara source before they went live. That does not mean every staff route, paid flow, provider callback or Python WebRTC implementation was exercised live. The earlier extension audit provides broader authenticated endpoint coverage; it is not a substitute for testing your application's inputs and permissions.

REST endpoint reference

Filter by feature, route, method, scope, body key or Python method name. The catalogue includes privileged and client-specific routes, labeled below. These examples never send requests from this page.

No matching operations. Clear the search or choose another category.

curl --fail-with-body -X POST "https://nookara.cc/auth/ext-code" \
  -H "Content-Type: application/json" \
  --data '{"permissions_integer":2049,"project_name":"My client"}'

api.post_auth_ext_code(json={'permissions_integer': 2049, 'project_name': 'My client'})

curl --fail-with-body -X GET "https://nookara.cc/auth/ext-code/heartbeat"

api.get_auth_ext_code_heartbeat(query=query_values)

curl --fail-with-body -X GET "https://nookara.cc/auth/ext-code/info"

api.get_auth_ext_code_info(query=query_values)

curl --fail-with-body -X POST "https://nookara.cc/auth/ext-code/complete" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_ext_code_complete(json=payload)

curl --fail-with-body -X GET "https://nookara.cc/auth/ext-code/status"

api.get_auth_ext_code_status(query=query_values)

curl --fail-with-body -X POST "https://nookara.cc/auth/register" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_register(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/register/verify" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_register_verify(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/register/verify-link" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_register_verify_link(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/register/status" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_register_status(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/register/resend" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_register_resend(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/login" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_login(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/verify-new-ip" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_verify_new_ip(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/verify-email-link" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_verify_email_link(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/verify-ip-link" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_verify_ip_link(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/resend-new-ip" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_resend_new_ip(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/validate" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_validate(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/accept-tos" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_accept_tos(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/logout" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.post_auth_logout()

curl --fail-with-body -X POST "https://nookara.cc/auth/set-email" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_set_email(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/verify-email" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.post_auth_verify_email()

curl --fail-with-body -X POST "https://nookara.cc/auth/resend-verification" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_resend_verification(json=payload)

curl --fail-with-body -X DELETE "https://nookara.cc/auth/sessions/YOUR_SESSIONID" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_auth_sessions_by_sessionid(sessionId="YOUR_SESSIONID")

curl --fail-with-body -X GET "https://nookara.cc/auth/sessions" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_auth_sessions()

curl --fail-with-body -X GET "https://nookara.cc/auth/login-history" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_auth_login_history()

curl --fail-with-body -X POST "https://nookara.cc/auth/forgot-password" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_forgot_password(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/reset-password" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_reset_password(json=payload)

curl --fail-with-body -X GET "https://nookara.cc/api/tos/current"

api.get_api_tos_current()

curl --fail-with-body -X GET "https://nookara.cc/auth/oauth/providers"

api.get_auth_oauth_providers()

curl --fail-with-body -X GET "https://nookara.cc/auth/oauth/YOUR_P/start"

api.get_auth_oauth_by_p_start(p="YOUR_P", query=query_values)

curl --fail-with-body -X POST "https://nookara.cc/auth/oauth/YOUR_P/link" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.post_auth_oauth_by_p_link(p="YOUR_P")

curl --fail-with-body -X GET "https://nookara.cc/auth/oauth/YOUR_P/callback"

api.get_auth_oauth_by_p_callback(p="YOUR_P", query=query_values)

curl --fail-with-body -X POST "https://nookara.cc/auth/oauth/exchange" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_oauth_exchange(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/auth/oauth/signup" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_oauth_signup(json=payload)

curl --fail-with-body -X GET "https://nookara.cc/auth/oauth/linked" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_auth_oauth_linked()

curl --fail-with-body -X PATCH "https://nookara.cc/auth/oauth/YOUR_P" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.patch_auth_oauth_by_p(p="YOUR_P", json=payload)

curl --fail-with-body -X DELETE "https://nookara.cc/auth/oauth/YOUR_P" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_auth_oauth_by_p(p="YOUR_P")

curl --fail-with-body -X POST "https://nookara.cc/auth/child-token" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_auth_child_token(json=payload)

curl --fail-with-body -X GET "https://nookara.cc/bonfire/app-login"

api.get_bonfire_app_login(query=query_values)

curl --fail-with-body -X GET "https://nookara.cc/bonfire/scopes.json"

api.get_bonfire_scopes_json()

curl --fail-with-body -X GET "https://nookara.cc/bonfire/session" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_bonfire_session()

curl --fail-with-body -X POST "https://nookara.cc/bonfire/app-exchange" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_bonfire_app_exchange(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/bonfire/replace-token" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_bonfire_replace_token(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/bonfire/sign-out" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.post_bonfire_sign_out()

curl --fail-with-body -X POST "https://nookara.cc/bonfire/app-code"

api.post_bonfire_app_code()

curl --fail-with-body -X GET "https://nookara.cc/account/me" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_account_me()

curl --fail-with-body -X POST "https://nookara.cc/account/change-username" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_account_change_username(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/account/onboarding/complete" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.post_account_onboarding_complete()

curl --fail-with-body -X GET "https://nookara.cc/account/export" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_account_export()

curl --fail-with-body -X DELETE "https://nookara.cc/account/sessions/YOUR_TOKENID" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_account_sessions_by_tokenid(tokenId="YOUR_TOKENID")

curl --fail-with-body -X GET "https://nookara.cc/account/search"

api.get_account_search(query=query_values)

curl --fail-with-body -X GET "https://nookara.cc/account/lookup/YOUR_USERNAME"

api.get_account_lookup_by_username(username="YOUR_USERNAME")

curl --fail-with-body -X PATCH "https://nookara.cc/account/update" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.patch_account_update(json=payload)

curl --fail-with-body -X POST "https://nookara.cc/account/change-password" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_account_change_password(json=payload)

curl --fail-with-body -X DELETE "https://nookara.cc/account/me" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.delete_account_me(json=payload)

curl --fail-with-body -X GET "https://nookara.cc/account/cursor-ticket" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_account_cursor_ticket()

curl --fail-with-body -X GET "https://nookara.cc/storage/info/usage" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_storage_info_usage()

curl --fail-with-body -X GET "https://nookara.cc/storage/YOUR_STORAGEID" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_storage_by_storageid(storageId="YOUR_STORAGEID")

curl --fail-with-body -X GET "https://nookara.cc/storage/YOUR_STORAGEID/keys" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_storage_by_storageid_keys(storageId="YOUR_STORAGEID")

curl --fail-with-body -X GET "https://nookara.cc/storage/YOUR_STORAGEID/values" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_storage_by_storageid_values(storageId="YOUR_STORAGEID")

curl --fail-with-body -X GET "https://nookara.cc/storage/YOUR_STORAGEID/YOUR_KEY" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_storage_by_storageid_by_key(storageId="YOUR_STORAGEID", key="YOUR_KEY")

curl --fail-with-body -X PUT "https://nookara.cc/storage/YOUR_STORAGEID/YOUR_KEY" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"value":"My saved value"}'

api.put_storage_by_storageid_by_key(storageId="YOUR_STORAGEID", key="YOUR_KEY", json={'value': 'My saved value'})

curl --fail-with-body -X DELETE "https://nookara.cc/storage/YOUR_STORAGEID/YOUR_KEY" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_storage_by_storageid_by_key(storageId="YOUR_STORAGEID", key="YOUR_KEY")

curl --fail-with-body -X DELETE "https://nookara.cc/storage/YOUR_STORAGEID" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_storage_by_storageid(storageId="YOUR_STORAGEID")

curl --fail-with-body -X GET "https://nookara.cc/storage-info/info/usage" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_storage_info_info_usage()

curl --fail-with-body -X GET "https://nookara.cc/storage-info/YOUR_STORAGEID" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_storage_info_by_storageid(storageId="YOUR_STORAGEID")

curl --fail-with-body -X GET "https://nookara.cc/storage-info/YOUR_STORAGEID/keys" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_storage_info_by_storageid_keys(storageId="YOUR_STORAGEID")

curl --fail-with-body -X GET "https://nookara.cc/storage-info/YOUR_STORAGEID/values" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_storage_info_by_storageid_values(storageId="YOUR_STORAGEID")

curl --fail-with-body -X GET "https://nookara.cc/storage-info/YOUR_STORAGEID/YOUR_KEY" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_storage_info_by_storageid_by_key(storageId="YOUR_STORAGEID", key="YOUR_KEY")

curl --fail-with-body -X PUT "https://nookara.cc/storage-info/YOUR_STORAGEID/YOUR_KEY" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.put_storage_info_by_storageid_by_key(storageId="YOUR_STORAGEID", key="YOUR_KEY", json=payload)

curl --fail-with-body -X DELETE "https://nookara.cc/storage-info/YOUR_STORAGEID/YOUR_KEY" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_storage_info_by_storageid_by_key(storageId="YOUR_STORAGEID", key="YOUR_KEY")

curl --fail-with-body -X DELETE "https://nookara.cc/storage-info/YOUR_STORAGEID" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_storage_info_by_storageid(storageId="YOUR_STORAGEID")

curl --fail-with-body -X POST "https://nookara.cc/im/send" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"to":"USERNAME","message":"Hello!"}'

api.post_im_send(json={'to': 'USERNAME', 'message': 'Hello!'})

curl --fail-with-body -X GET "https://nookara.cc/im/status-reply/YOUR_USERNAME" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_im_status_reply_by_username(username="YOUR_USERNAME")

curl --fail-with-body -X GET "https://nookara.cc/im/conversations" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_im_conversations()

curl --fail-with-body -X GET "https://nookara.cc/im/with/YOUR_USERNAME" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_im_with_by_username(username="YOUR_USERNAME", query=query_values)

curl --fail-with-body -X POST "https://nookara.cc/im/with/YOUR_USERNAME/read" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.post_im_with_by_username_read(username="YOUR_USERNAME")

curl --fail-with-body -X GET "https://nookara.cc/im" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_im()

curl --fail-with-body -X GET "https://nookara.cc/im/inbox" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_im_inbox()

curl --fail-with-body -X GET "https://nookara.cc/im/sent" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_im_sent()

curl --fail-with-body -X GET "https://nookara.cc/im/unread-count" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_im_unread_count()

curl --fail-with-body -X PATCH "https://nookara.cc/im/YOUR_ID/read" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.patch_im_by_id_read(id="YOUR_ID")

curl --fail-with-body -X PATCH "https://nookara.cc/im/YOUR_ID/edit" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.patch_im_by_id_edit(id="YOUR_ID", json=payload)

curl --fail-with-body -X DELETE "https://nookara.cc/im/YOUR_ID" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_im_by_id(id="YOUR_ID")

curl --fail-with-body -X DELETE "https://nookara.cc/im" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_im()

curl --fail-with-body -X GET "https://nookara.cc/friends" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_friends()

curl --fail-with-body -X GET "https://nookara.cc/friends/requests" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_friends_requests()

curl --fail-with-body -X POST "https://nookara.cc/friends/request" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"username":"USERNAME"}'

api.post_friends_request(json={'username': 'USERNAME'})

curl --fail-with-body -X PATCH "https://nookara.cc/friends/request/YOUR_ID/accept" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.patch_friends_request_by_id_accept(id="YOUR_ID")

curl --fail-with-body -X PATCH "https://nookara.cc/friends/request/YOUR_ID/decline" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.patch_friends_request_by_id_decline(id="YOUR_ID")

curl --fail-with-body -X DELETE "https://nookara.cc/friends/YOUR_USERNAME" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_friends_by_username(username="YOUR_USERNAME")

curl --fail-with-body -X GET "https://nookara.cc/friends/status/YOUR_USERNAME" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_friends_status_by_username(username="YOUR_USERNAME")

curl --fail-with-body -X GET "https://nookara.cc/groups" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_groups()

curl --fail-with-body -X POST "https://nookara.cc/groups" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Project group","members":["USERNAME"]}'

api.post_groups(json={'name': 'Project group', 'members': ['USERNAME']})

curl --fail-with-body -X GET "https://nookara.cc/groups/YOUR_ROOM" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_groups_by_room(room="YOUR_ROOM")

curl --fail-with-body -X GET "https://nookara.cc/groups/YOUR_ROOM/messages" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_groups_by_room_messages(room="YOUR_ROOM", query=query_values)

curl --fail-with-body -X POST "https://nookara.cc/groups/YOUR_ROOM/messages" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"message":"Hello group!"}'

api.post_groups_by_room_messages(room="YOUR_ROOM", json={'message': 'Hello group!'})

curl --fail-with-body -X POST "https://nookara.cc/groups/YOUR_ROOM/members" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.post_groups_by_room_members(room="YOUR_ROOM", json=payload)

curl --fail-with-body -X DELETE "https://nookara.cc/groups/YOUR_ROOM/members/YOUR_USERNAME" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_groups_by_room_members_by_username(room="YOUR_ROOM", username="YOUR_USERNAME")

curl --fail-with-body -X PATCH "https://nookara.cc/groups/YOUR_ROOM" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.patch_groups_by_room(room="YOUR_ROOM", json=payload)

curl --fail-with-body -X DELETE "https://nookara.cc/groups/YOUR_ROOM" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_groups_by_room(room="YOUR_ROOM")

curl --fail-with-body -X GET "https://nookara.cc/chat/invite/YOUR_CODE"

api.get_chat_invite_by_code(code="YOUR_CODE")

curl --fail-with-body -X GET "https://nookara.cc/chat/identities" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_chat_identities(query=query_values)

curl --fail-with-body -X GET "https://nookara.cc/chat/server-creation-policy" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_chat_server_creation_policy()

curl --fail-with-body -X GET "https://nookara.cc/chat/servers" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_chat_servers()

curl --fail-with-body -X GET "https://nookara.cc/chat/discover" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_chat_discover()

curl --fail-with-body -X POST "https://nookara.cc/chat/servers" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"My server","description":"","discoverable":false}'

api.post_chat_servers(json={'name': 'My server', 'description': '', 'discoverable': False})

curl --fail-with-body -X GET "https://nookara.cc/chat/servers/YOUR_SID" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.get_chat_servers_by_sid(sid="YOUR_SID")

curl --fail-with-body -X PATCH "https://nookara.cc/chat/servers/YOUR_SID" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.patch_chat_servers_by_sid(sid="YOUR_SID", json=payload)

curl --fail-with-body -X PUT "https://nookara.cc/chat/servers/YOUR_SID/layout" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.put_chat_servers_by_sid_layout(sid="YOUR_SID", json=payload)

curl --fail-with-body -X POST "https://nookara.cc/chat/servers/YOUR_SID/roles" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Reader","permissions":0,"color":"#c084fc"}'

api.post_chat_servers_by_sid_roles(sid="YOUR_SID", json={'name': 'Reader', 'permissions': 0, 'color': '#c084fc'})

curl --fail-with-body -X PUT "https://nookara.cc/chat/servers/YOUR_SID/roles/order" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.put_chat_servers_by_sid_roles_order(sid="YOUR_SID", json=payload)

curl --fail-with-body -X PATCH "https://nookara.cc/chat/servers/YOUR_SID/roles/YOUR_RID" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @payload.json

api.patch_chat_servers_by_sid_roles_by_rid(sid="YOUR_SID", rid="YOUR_RID", json=payload)

curl --fail-with-body -X DELETE "https://nookara.cc/chat/servers/YOUR_SID/roles/YOUR_RID" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_chat_servers_by_sid_roles_by_rid(sid="YOUR_SID", rid="YOUR_RID")

curl --fail-with-body -X PUT "https://nookara.cc/chat/servers/YOUR_SID/members/YOUR_USERNAME/roles/YOUR_RID" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.put_chat_servers_by_sid_members_by_username_roles_by_rid(sid="YOUR_SID", username="YOUR_USERNAME", rid="YOUR_RID")

curl --fail-with-body -X DELETE "https://nookara.cc/chat/servers/YOUR_SID/members/YOUR_USERNAME/roles/YOUR_RID" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_chat_servers_by_sid_members_by_username_roles_by_rid(sid="YOUR_SID", username="YOUR_USERNAME", rid="YOUR_RID")

curl --fail-with-body -X POST "https://nookara.cc/chat/servers/YOUR_SID/roles/YOUR_RID/icon" \
  -H "Authorization: Bearer $VELORA_TOKEN" \
  -F "file=@path/to/file"

api.post_chat_servers_by_sid_roles_by_rid_icon(sid="YOUR_SID", rid="YOUR_RID", files={'file': "path/to/file"})

curl --fail-with-body -X DELETE "https://nookara.cc/chat/servers/YOUR_SID/roles/YOUR_RID/icon" \
  -H "Authorization: Bearer $VELORA_TOKEN"

api.delete_chat_servers_by_sid_roles_by_rid_icon(sid="YOUR_SID", rid="YOUR_RID")