API reference

GET /guilds

List the guilds you belong to or can manage.

The /api/v1/guilds endpoint returns the Discord servers (“guilds”) that the owner of your API key is a member of, or has authority to manage, resolved across all of the owner’s linked identities. It is a read-only listing: each entry reports the guild’s id and name, an optional icon and member count, and two booleans — manageable and member — that tell you what the owner may do there.

Endpoint

Requires the guilds:read scope. This call is metered as a flat request against your app’s daily allowance (see Billing & rate limits). There are no query parameters and no pagination — the full matching set is returned in a single response.

Scope

The request must be authenticated with a bearer key that carries the guilds:read scope:

A key without guilds:read is rejected with 403 insufficient_scope, and the required scope is echoed back in error.required_scope. Grant scopes when you mint a key in the Developer console; see Scopes and Authentication for the full picture.

The guild object

Each element of the returned array is a guild object with the following fields:

Every guild returned satisfies manageable === true or member === true (often both). Guilds where the owner is neither a member nor able to manage are excluded from the response, not returned with both flags false.

Responses use the native Krallo envelope: the array is wrapped as { "data": […], "meta": { "request_id": … } }. Errors are { "error": { "code", "message", … }, "meta": … }. See Errors for the full contract.

List guilds

Returns a JSON array of guild objects. An owner with no eligible guilds receives "data": [] with a 200 status. The result set is deduplicated by guild id (a server hosting more than one Krallo bot appears once). Ordering is not guaranteed — do not rely on the array order; sort client-side if you need a stable order.

Request

curl https://exe.krallo.com/api/v1/guilds \
  -H "Authorization: Bearer krallo_live_..."

const res = await fetch("https://exe.krallo.com/api/v1/guilds", {
  headers: { Authorization: `Bearer ${process.env.KRALLO_API_KEY}` },
});
const { data: guilds } = await res.json();

const managed = guilds.filter((g) => g.manageable);
console.log(`You can manage ${managed.length} of ${guilds.length} guilds.`);

Response

{
  "data": [
    {
      "id": "784241093920145408",
      "name": "Krallo HQ",
      "icon_url": "https://cdn.discordapp.com/icons/784241093920145408/a1b2c3d4e5f6.png",
      "manageable": true,
      "member": true,
      "member_count": 1284
    },
    {
      "id": "902551730118443110",
      "name": "Indie Dev Lounge",
      "manageable": false,
      "member": true,
      "member_count": 57
    }
  ],
  "meta": { "request_id": "5f3a91c0-b2d4-4e6f-8a1c-7b9d0e2f4a68" }
}

Note the second guild in the example: it has no icon_url (the server has no custom icon) and manageable is false because the owner is a plain member with no administrative authority there.

How the fields are computed

For each candidate guild — that is, each guild hosting a Krallo bot — the two booleans are derived by examining every one of the owner’s linked identities. If any linked identity qualifies, the flag is set.

member

Set to true when at least one of the owner’s linked identities is a current member of the guild. Discord membership is matched against Discord identities, so a Google-only linked identity does not by itself confer membership — a linked Discord identity does.

manageable

Set to true when, for any linked identity, any of the following holds:

• the identity is the Discord owner of the guild; or
• the identity’s Discord member has the Manage Server or Administrator permission in the guild; or
• the identity holds a Krallo role that grants any effective permission scoped to that guild (Krallo’s own RBAC, independent of Discord permissions).

Because these are OR-ed together, a guild can be manageable through Krallo’s role system even when the underlying Discord member lacks Manage Server. Being the Discord owner implies both manageable and member.

Billing & rate limits

This endpoint is a flat metered request. Each call first draws down your app’s free daily allowance; once that allowance is exhausted, and if wallet billing is enabled, the call debits a small, fixed number of credit units from the owner’s balance. If the wallet cannot cover a billable call, the request returns 402 insufficient_credits with required_units and balance in the error body, and nothing is returned. A call that is refused or errors after being metered is refunded and does not burn quota. See Billing for the full model.

Requests are rate-limited per key according to your app’s tier. Every authenticated response carries advisory X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers; exceeding the limit returns 429 with a Retry-After header. See Rate limits.

Errors

In addition to the standard bearer-auth failures, this endpoint can return the errors below. Note that the guild enumeration itself is best-effort: if the backend cannot resolve part of the listing, that portion is silently skipped and you receive a partial (or empty) 200 rather than a server error.

All errors except the 429 share the native envelope shape (the rate limiter writes a flat { "error": "rate_limited", … } body — see Rate limits). For status semantics and retry guidance, see Errors. Related reading: Authentication, Scopes, and Billing.