Organizer API

Connect your organizer bot to Hatenna to manage reserves, change supported server settings, and create ready-up checklists across the servers you run.

Base URL: https://res.hatenna.xyz · Version: v1 · Access: approved integrations with an API key.

Before you start

Ask the Hatenna team for an organizer API key bound to your bot's Discord user ID and the scopes your integration needs. This is a Hatenna API key, not your Discord bot token. One organizer key works across multiple servers.

For every request, both Hatenna and your organizer bot must be in the target server. Your organizer bot must have Administrator, Manage Server, or a role authorized through h!roles there. Reading or changing settings additionally requires Manage Server or Administrator. Hatenna checks membership and permissions against Discord for each request. Removing the bot or its permissions stops access to that server. A key never grants permissions the bot does not already have.

Some integrations may instead receive a single-server key; that key accepts only its assigned server ID. Confirm your key type, expiry and scopes with its issuer.

Choose the server for each request

Every authenticated endpoint includes the target server ID:

https://res.hatenna.xyz/v1/servers/{server_id}/{resource}

When processing a Discord command, use ctx.guild.id; for an interaction, use interaction.guild_id in discord.py. Scheduled jobs should store the intended server ID with the job. Reject commands in DMs, where no server ID exists.

Use the same organizer key for requests in server A and server B. Set the URL's server ID to A or B as appropriate. Hatenna looks up your key's bot in that server and checks its permissions there. It does not guess the server from an IP address, a channel name, or the key alone. Sending an unrelated server ID grants no access.

Send all Discord IDs in JSON as decimal strings, including user and channel IDs. This avoids JavaScript rounding large Discord IDs.

Authenticate securely

Authorization: Bearer YOUR_HATENNA_API_KEY
Content-Type: application/json

Store the key in your backend's secret environment, for example HATENNA_CONTROL_KEY. Use HTTPS. Never put it in a URL, client-side website code, source control, public Discord messages, or logs. No Discord token is sent to this API. Browsers are not supported through CORS; call from your bot/backend.

Keys expire and can be revoked. If a key is lost or exposed, ask the Hatenna team to revoke it and issue a replacement. To rotate without downtime, switch to a replacement before revoking the old key. Keep the public key ID for support; never include the full secret in a support message. An already-running request may finish after revocation.

Endpoints and scopes

All paths below follow /v1/servers/{server_id}. A valid key must include the endpoint's scope as well as passing the server permission checks.

Read reserves

GET /v1/servers/123456789012345678/reserves

Example response:

{
  "reserves": [
    {"pokemon": "pikachu", "user_ids": ["234567890123456789"]}
  ]
}

Names are canonical lowercase names. An empty server returns {"reserves":[]}. Assignments belong to this server; profile-linked alts are not automatically added to the public reserve list.

Add or remove reserves

POST /v1/servers/123456789012345678/reserves

{
  "action": "add",
  "pokemon": "Pikachu",
  "user_ids": ["234567890123456789"]
}

Example response:

{"ok": true, "pokemon_count": 1, "user_count": 1}

Use "action":"remove" with the same payload shape to remove assignments. Repeating an identical add or remove is safe. Counts describe the requested expanded Pokémon and distinct users, rather than newly changed assignments.

• Supply 1–25 user IDs and at most 100 expanded Pokémon per request.
• The pokemon string accepts comma-separated names, existing server categories, and the normal reserve form syntax, such as Pikachu, all Flabebe.
• Unknown names reject the request before writes. Use exact names for predictable integrations; a category can change as the server edits it.
• All users must be current server members when adding. Removal also accepts IDs of departed users so old assignments can be cleaned up.
• Changes feed Hatenna's existing reserve pings. Copy, transfer, exchange and server-wide clear endpoints are not available in v1.

Read and change settings

Read current supported defaults with:

GET /v1/servers/123456789012345678/settings

The response wraps the supported fields in a settings object. To change only specific fields:

PATCH /v1/servers/123456789012345678/settings

{"reserve_ping": true, "naming_mode": "assisted", "assisted_embed": true}

The response returns the supported settings after the update. Unspecified fields retain their values. Repeating the same PATCH is safe. Use JSON booleans true and false, not the strings "true" or "false".

These are server defaults. Existing channel overrides still apply. Unknown fields or invalid values reject the whole payload before any field is changed. Roles, log-channel selection, modules, appearance, channel overrides and deletion of server data are not exposed through this API version. Configure those through Hatenna's Discord commands.

Create a ready-up checklist

POST /v1/servers/123456789012345678/readyup

{
  "channel_id": "345678901234567890",
  "user_ids": ["234567890123456789", "456789012345678901"]
}

Example response:

{
  "message_id": "567890123456789012",
  "url": "https://discord.com/channels/123456789012345678/345678901234567890/567890123456789012"
}

• Supply 1–25 members of the requested server.
• channel_id must identify a text channel in that server. Your organizer bot must have View Channel and Send Messages there. Hatenna needs permissions to send the message and embeds.
• Hatenna sends the normal mentions and interactive checklist. Each user marks themselves ready using Discord buttons; the API cannot mark users ready.
• The checklist expires after one hour. There is one active checklist per organizer bot across all servers, matching the existing Discord flow.
• The normal completion DM goes to the organizer principal. API bots should not depend on receiving a DM; this version has no completion webhook/status API.
• Checklists are held in memory and stop working after a bot restart.
• A conflict returns 409. The existing flow can also send explanatory feedback into the requested Discord channel when it cannot create a checklist.

Do not automatically retry ready-up POSTs after a timeout. The message may already exist even if your HTTP client did not receive the response. Inspect the channel first. This version does not support idempotency keys.

Python integration example

Use an asynchronous client inside your Discord bot so API requests do not block its event loop. This example uses aiohttp and takes the server ID from context:

import os
import aiohttp

async def set_reserve_pings(ctx, enabled: bool):
    if ctx.guild is None:
        raise ValueError("Run this command inside a server")
    url = f"https://res.hatenna.xyz/v1/servers/{ctx.guild.id}/settings"
    headers = {
        "Authorization": "Bearer " + os.environ["HATENNA_CONTROL_KEY"]
    }
    timeout = aiohttp.ClientTimeout(total=120)
    async with aiohttp.ClientSession(timeout=timeout) as session:
        async with session.patch(
            url, headers=headers, json={"reserve_ping": enabled}
        ) as response:
            result = await response.json()
            if response.status != 200:
                raise RuntimeError(
                    f"Hatenna API {response.status}: {result.get('error', 'Request failed')}"
                )
            return result["settings"]

Your bot must also authorize its own users before making API calls. The key represents your bot's server permissions, not those of whichever user invoked your command. Do not let an unrestricted command delegate your bot's management access to everyone. For a production integration, reuse a client session and handle timeouts and rate limits without logging the key.

Limits and errors

The request body limit is 16 KiB. Each key allows 60 authenticated requests per fixed UTC minute, shared across all its servers. A 429 response includes Retry-After: 60 from the application; edge limits can also return 429. Respect Retry-After when supplied and otherwise wait at least 60 seconds. Do not create retry bursts. Discord delivery can queue behind Hatenna's shared outbound limiter.

Application errors use {"error":"description"}. The reverse proxy may return its own text/HTML error response, so robust clients also handle non-JSON errors.

Reads and identical reserve/settings writes can be retried with bounded backoff. Multi-Pokémon writes and multi-field setting changes are not transactions: a storage failure can leave partial changes. Read the current state, repeat the idempotent write if needed, and verify. Ready-up POSTs need manual inspection after ambiguous failures. API audit entries retain operation metadata for about 90 days, without keys or request bodies. API reserve mutations do not emit the Discord add/exchange command logs.

Help and downloads

Contact the Hatenna support server for key access, scope changes, expiry, revocation, or integration issues. Include your public key ID, server ID, endpoint, timestamp and HTTP status. Never send the key secret.

Download the Markdown guide, plain-text guide, or Discord message pack. Each message in the Discord pack is under 2,000 characters and can be pasted separately in order.