Public alerts API

Quick start

Connect your bot or server application to Alatic’s public region alerts.

Base URL: https://api.alatic.store

• Save your API key in the server-side ALATIC_API_KEY environment variable.
• Request /v1/alerts with the Authorization header shown below.
• Poll every 30 seconds and update your existing messages when an alert changes.

API keys are separate from Discord rank keys. Monthly access lasts 30 days from the first authenticated request, including /v1/me. Lifetime keys have no scheduled expiry. To renew monthly access, replace the expired key with a new one.

Authentication

Send your complete, case-sensitive key in the header:

Authorization: Bearer ALATIC-YOUR_RANDOM_STRING

ALATIC-YOUR_RANDOM_STRING is a placeholder. New keys start with ALATIC-; previously issued keys still work unchanged.

export ALATIC_API_KEY='ALATIC-YOUR_RANDOM_STRING'
curl --fail-with-body https://api.alatic.store/v1/alerts \
  -H "Authorization: Bearer $ALATIC_API_KEY"

Keep your key private and server-side. Never include it in a URL, browser code or public repository. Do not share or resell your key.

Rate limit

Each key allows 5 requests per minute, shared across all authenticated endpoints and clients using that key. Poll the alert list every 30 seconds (2 requests per minute). Use the remaining budget for individual alert checks or pagination; spread additional checks across later minutes.

Responses include X-RateLimit-Limit and X-RateLimit-Remaining. If you receive HTTP 429, wait the number of seconds in Retry-After before retrying. Avoid overlapping polling loops.

GET /v1/alerts

Returns public alerts, newest first.

• limit: page size, 1–100; defaults to 50.
• before: use the previous response’s next_cursor to fetch the next page. Stop when it is null.

{
  "data": [{
    "id": "018af922-9842-4c07-a7af-47f56de7a239",
    "region": "EU West",
    "status": "active",
    "published_at": "2026-10-19T12:00:00.000Z",
    "ended_at": null,
    "notification_sent_at": null
  }],
  "next_cursor": null
}

• id: stable alert identifier. Use it to update the same message instead of creating duplicates.
• region: Asia, NA East, NA West, EU Central, EU West or Oceania.
• status: active, patched or ended. Active means the alert has not ended; it does not guarantee a Minecraft bot is online.
• published_at: alert publication timestamp.
• ended_at: closure timestamp, or null.
• notification_sent_at: notification timestamp, or null while a notification is not yet available.

All timestamps are UTC ISO 8601 strings. The API does not provide Goliath IDs, coordinates, Minecraft usernames, teleports or private alerts.

Updating alerts and pings

Post new alerts without a ping. Ping once only when notification_sent_at becomes non-null and status is still active. This follows Alatic’s delayed recheck; do not replace it with your own five-minute timer.

When status becomes patched or ended, update the existing message. Save alert IDs, message IDs and sent-ping state so restarts do not create duplicate posts or pings. On first setup, baseline existing alerts instead of announcing old history.

GET /v1/alerts/{id}

Fetch one alert using its ID. The response is {"data": {...}} with the same alert fields.

Recheck tracked active alerts even if they leave the first list page, within your shared request budget. A 404 means the alert is unknown or no longer public: remove its details or mark it unavailable. Do not label it patched unless its returned status is patched.

GET /v1/me

Check your key’s plan and expiry. This request activates an unused monthly key and counts toward the rate limit.

{
  "id": "your-key-id",
  "plan": "monthly",
  "activated_at": "2026-10-19T12:00:00.000Z",
  "expires_at": "2026-11-18T12:00:00.000Z"
}

Lifetime keys return expires_at: null.

Errors

• 400: invalid query or cursor. Check parameters; restart pagination if the cursor is invalid.
• 401: missing, invalid, expired or revoked key. Check your configuration or renew access.
• 404: endpoint or public alert not found.
• 405: use GET; other methods are unsupported.
• 429: request limit reached. Wait for Retry-After.
• 503: temporary issue. Retry with backoff.

Network failures, rate limits and server errors do not mean an alert has ended. Keep the last known state marked as stale until a successful response. If access is blocked with HTTP 403, contact support. API v1 uses polling, not webhooks or streaming.

Node.js example

const key = process.env.ALATIC_API_KEY;
if (!key) throw new Error('Set ALATIC_API_KEY');

const response = await fetch('https://api.alatic.store/v1/alerts?limit=50', {
  headers: { Authorization: `Bearer ${key}` },
  signal: AbortSignal.timeout(10000)
});

if (!response.ok) {
  // On 429, wait response.headers.get('Retry-After') seconds.
  throw new Error(`Alatic API returned HTTP ${response.status}`);
}

const { data, next_cursor } = await response.json();
for (const alert of data) {
  console.log(alert.id, alert.region, alert.status);
  // Create or update your message using the saved alert ID.
}

This example makes one request. For continuous updates, use one sequential polling loop and keep all requests within the 5-per-minute limit.