Zyron
Get an API key

Guild API

Guild API overview

Everything Zyron does in your Discord server — settings, registration, custom games, tournaments, teams, dropmap, stats — exposed as a REST API under a single guild-scoped base path.

Base URL

All guild endpoints live under the versioned base URL, scoped to one guild:

text
https://api.zyron.pro/api/v1/guilds/:guildId

Paths in the reference pages are relative to this base — e.g. GET /settings means GET https://api.zyron.pro/api/v1/guilds/:guildId/settings.

Key scoping

Guild API keys are bound to exactly one guild. Server admins create them self-serve on the Zyron dashboard: open your server, then Settings → API access. Send the key as Authorization: Bearer zyr_... (or X-API-Key) — see Authentication.

Legacy keys

Keys without a guild binding work for the Replay Parser only. Calling guild endpoints with a legacy key — or with a key bound to a different guild — returns 403 forbidden.

Premium gate

The Guild API requires the guild to be on the Premium or Pro plan. If the guild's plan lapses, every guild endpoint returns 403 with the error code premium_required:

json
{
  "error": "premium_required",
  "message": "This guild needs the Premium or Pro plan to use the Guild API."
}

Guild keys are minted at the pro rate tier — 600 requests/minute and 200,000/day against the Guild API (the tighter budget is reserved for the MB-heavy replay parser). See Rate limits.

Idempotent retries

Any POST may carry an Idempotency-Key header so a timed-out request is safe to retry without duplicating the action (creating two customs sessions, sending two DMs, and so on). Use a fresh unique value — a UUID — per logical operation.

  • The first request is processed and its response is stored for 24 hours.
  • A retry with the same key and the same request replays the stored response and adds X-Idempotency-Replayed: true.
  • The same key with a different body or path returns 422 invalid_request.
  • A duplicate that arrives while the first is still in flight returns 409 conflict — wait and retry.
bash
curl -X POST https://api.zyron.pro/api/v1/guilds/:guildId/customs/sessions \
  -H "Authorization: Bearer zyr_your_guild_key" \
  -H "Idempotency-Key: 5f3c…-unique-per-operation" \
  -H "Content-Type: application/json" \
  -d '{ "hostDiscordId": "…", "gameMode": "solo" }'

Idempotency is optional — omit the header and each request is processed independently.

Error envelope

Every error, on every endpoint, uses the same JSON envelope:

json
{
  "error": "<code>",
  "message": "<human text>"
}

Possible codes: unauthorized, forbidden, premium_required, not_found, invalid_request, conflict, rate_limited, busy, internal_error. Branch on error, never on message. Full table on the Errors page.

IDs

  • guildId is the Discord server ID — a snowflake like 123456789012345678. Discord IDs (guilds, channels, roles, users) are always strings, never numbers.
  • Zyron resource IDs (tournamentId, sessionId, teamId, presetId, webhookId, claimId) are opaque strings — store them as-is and do not parse structure out of them.
  • Epic account IDs are lowercase 32-character hex strings, e.g. a1b2c3d4e5f60718293a4b5c6d7e8f90.

Pagination

List endpoints use one of two conventions:

StyleParametersUsed by
Page-basedpage (1-based) and limit; responses include total, page, limit.Links, customs sessions.
Cursor-basedbefore (opaque cursor) and limit; responses include nextCursor (pass it as before for the next page; null when done).The logbook.

Quickstart

Fetch your guild's settings to confirm your key and plan are set up correctly:

curl https://api.zyron.pro/api/v1/guilds/123456789012345678/settings \
  -H "Authorization: Bearer zyr_your_guild_key"

A 200 means you are ready to go. A 403 forbidden means the key is legacy or bound to another guild; a 403 premium_required means the guild needs the Premium or Pro plan.

What is covered