REST API

Every endpoint of the public Guild API.

The Guild REST API lets your own code read a guild's roles and members, check a user's memberships, and grant or deduct points. Use it for integrations that run without a person in the loop: a game server that awards points, a bot that checks whether someone holds a role, a dashboard of members.

REST API or an agent

If you want to manage a guild by asking in plain language, or let an AI agent set up roles, requirements and rewards, use the Guild MCP server instead. It's free on every plan and can do much more than the REST API's endpoints. The REST API is for programs you write yourself, calling a fixed set of endpoints.

Get an API key

API keys belong to a guild.

1. In the admin panel, open Agents.
2. At the bottom of the page, open For developers.
3. Press Create key, give it a Key name, and optionally limit it to the endpoints it needs.
4. Copy the key. It's shown in full only once.

Send the key as a Bearer token in the Authorization header. Keep it secret: anyone with the key can call the API as your guild.

API keys need the Pro plan or above. Growth and Enterprise get higher rate limits. See Plans.

Interactive reference

The live, interactive reference, where you can try requests, is at https://api.guild.xyz/docs. The endpoints are also listed below.

Verified person (staff)

The review queue

GET https://api.guild.xyz/admin/person-verification/queue

Superadmins only. Oldest first. status is PENDING, IN_REVIEW, NEEDS_INFO or DECIDED.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: A page. (QueuePageBody)

• 401 Signed out.
• 403 Not staff.
• 422 Validation failed.

A request with the reviewer signals

GET https://api.guild.xyz/admin/person-verification/requests/{requestId}

Superadmins only. refresh=1 recomputes the signals, at most once every 10 minutes (a newer stored report is returned instead).

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The detail. (RequestDetailBody)

• 401 Signed out.
• 403 Not staff, or SELF_REVIEW.
• 404 No such request.

Claim a request

POST https://api.guild.xyz/admin/person-verification/requests/{requestId}/claim

Sets IN_REVIEW with a 30-minute soft lock. Another reviewer's live claim gives 409 CLAIMED with claimedBy and claimedUntil.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The request. (object)

• 401 Signed out.
• 403 Not staff, or SELF_REVIEW.
• 404 No such request.
• 409 CLAIMED or NOT_CLAIMABLE.

Decide a request

POST https://api.guild.xyz/admin/person-verification/requests/{requestId}/decision

APPROVED grants the badge for 365 days and pushes it to the protocol. staffNote is required (1 to 2000 characters); NEEDS_INFO also requires memberMessage. Every outcome writes an audit row and notifies the member.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (DecisionBody):

Returns 200: The request. (object)

• 401 Signed out.
• 403 Not staff, or SELF_REVIEW.
• 404 No such request.
• 409 CLAIMED or NOT_OPEN.
• 422 Validation failed.

A member's badge, requests and audit

GET https://api.guild.xyz/admin/person-verification/users/{userId}

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The member's verification. (UserVerificationBody)

• 401 Signed out.
• 403 Not staff.

Grant a badge

POST https://api.guild.xyz/admin/person-verification/users/{userId}/grant

For staff cases. Writes a GRANTED audit row and pushes the badge.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (GrantBody):

Returns 200: The badge. (object)

• 401 Signed out.
• 403 Not staff, or SELF_REVIEW.
• 422 Validation failed.

Revoke a badge

POST https://api.guild.xyz/admin/person-verification/users/{userId}/revoke

Pushes verified = false (the protocol then removes the roles and rewards it gated) and notifies the member.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (RevokeBody):

Returns 200: The badge. (object)

• 401 Signed out.
• 403 Not staff, or SELF_REVIEW.
• 404 No active badge.
• 422 Validation failed.

Analytics

Search guild/user events

GET https://api.guild.xyz/analytics/events

Search the raw analytics event log. Provide userId to see one user's events (defaults to the caller; querying another user's userId without a guildId requires being a superAdmin), guildId to see one guild's events (requires being an admin, owner, or superAdmin of that guild), or both. SuperAdmins may omit both to query platform-wide; other callers default to their own userId when neither is given. roleId, requirementId, and rewardId further filter within a guildId search. hasMore indicates whether more rows exist beyond limit.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Matching events. (AnalyticsGuildEventsResponse)

• 400 userId or guildId is required unless the caller is a superAdmin; guildId is required when filtering by roleId, requirementId, or rewardId.
• 401 Not logged in.
• 403 userId names another user and guildId is absent and the caller is not a superAdmin; or guildId is present and the caller is not an admin, owner, or superAdmin of it.
• 404 No guild matches the requested guildId.
• 422 Request validation failed: userId/guildId/roleId/requirementId/rewardId is not a UUID, startDate/endDate/eventType is not a string, or limit is not a positive integer at most 10000.
• 429 Rate limit hit. See the Retry-After header.

Get a user's activity heatmap

GET https://api.guild.xyz/analytics/heatmap

Daily activity counts for a user between startDate and endDate (both default to the last 365 days — wider than the other analytics endpoints, which default to 7). Defaults to the authenticated user; pass userId to view another user's activity instead — requires being that user or a superAdmin. eventType is accepted for parity with /analytics/profile but is not currently applied to the query — every event type is counted.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Daily activity counts. (AnalyticsUserActivityHeatmapResponse)

• 400 No userId was given and no user is authenticated.
• 401 Not logged in.
• 403 userId names another user and the caller is not a superAdmin.
• 422 Request validation failed: userId is not a UUID, or startDate/endDate/eventType is not a string.
• 429 Rate limit hit. See the Retry-After header.

Get a user's profile activity

GET https://api.guild.xyz/analytics/profile

Metadata-enriched event history for a user (each event's guild, role, requirement, and reward is resolved to a short display record where still available) between startDate and endDate (both default to the last 7 days). Defaults to the authenticated user; pass userId to view another user's activity instead — requires being that user or a superAdmin. Never fails on an upstream data error — falls back to an empty events list.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The user's enriched event history. (AnalyticsUserProfileResponse)

• 400 No userId was given and no user is authenticated.
• 401 Not logged in.
• 403 userId names another user and the caller is not a superAdmin.
• 422 Request validation failed: userId is not a UUID, or startDate/endDate/eventType is not a string.
• 429 Rate limit hit. See the Retry-After header.

Search rewards across all guilds

GET https://api.guild.xyz/analytics/rewards

Search rewards platform-wide, filtered to a single type (required, for query performance) and to rewards created within the last days (default 90). Public endpoint; no authentication required.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: Matching rewards. (AnalyticsRewardSearchResponse)

• 422 Request validation failed: type is missing or not a valid reward type, sortBy/sortOrder is not one of the allowed values, limit is outside 0-100, offset is outside 0-10000000, or days is not a positive integer.
• 429 Rate limit hit. See the Retry-After header.

List trending guilds

GET https://api.guild.xyz/analytics/trending

Verified guilds ranked by join count over period. Public endpoint; no authentication required.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: Trending guilds, most joins first. (AnalyticsTrendingGuild[])

• 422 Request validation failed: period is missing or not one of today, week, month.
• 429 Rate limit hit. See the Retry-After header.

Get guild activity heatmap

GET https://api.guild.xyz/analytics/{guildIdLike}/activity-heatmap

Guild activity event counts (joins, leaves, role/reward grants and losses, identity connects/disconnects, form submits, points grants/revokes) bucketed by day of week and hour of day, between startDate and endDate (both default to the last 7 days). Requires the guild's subscription to include the analytics feature.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Activity heatmap buckets. (AnalyticsGuildActivityHeatmapResponse)

• 401 Not logged in.
• 403 Not a guild admin, owner, or superAdmin; or the guild's subscription lacks the "analytics" feature.
• 404 No guild matches guildIdLike.
• 422 Request validation failed: guildIdLike is not a UUID, or startDate/endDate is not a string.
• 429 Rate limit hit. See the Retry-After header.

Get guild activity summary

GET https://api.guild.xyz/analytics/{guildIdLike}/activity-summary

Event-type counts and total POINTS granted for the guild between startDate and endDate (both default to the last 7 days). Requires the guild's subscription to include the analytics feature.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Activity summary. (AnalyticsGuildActivitySummaryResponse)

• 401 Not logged in.
• 403 Not a guild admin, owner, or superAdmin; or the guild's subscription lacks the "analytics" feature.
• 404 No guild matches guildIdLike.
• 422 Request validation failed: guildIdLike is not a UUID, or startDate/endDate is not a string.
• 429 Rate limit hit. See the Retry-After header.

Get guild activity time series

GET https://api.guild.xyz/analytics/{guildIdLike}/activity-timeseries

Time series of total/joins/roles/rewards event counts, bucketed by interval (default minute) between startDate and endDate (both default to the last 7 days). Requires the guild's subscription to include the analytics feature.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Activity time series buckets. (AnalyticsGuildActivityTimeSeriesResponse)

• 401 Not logged in.
• 403 Not a guild admin, owner, or superAdmin; or the guild's subscription lacks the "analytics" feature.
• 404 No guild matches guildIdLike.
• 422 Request validation failed: guildIdLike is not a UUID, interval is not one of minute, hour, day, week, month, or startDate/endDate is not a string.
• 429 Rate limit hit. See the Retry-After header.

Compare native guild campaigns

GET https://api.guild.xyz/analytics/{guildIdLike}/campaigns

Campaigns are the guild's pages and current role assignments. Returns exact distinct role earners, grant/loss events, browser visitors, current membership snapshots, daily activity and safely attributable reward claims. The range is inclusive start, exclusive end, defaults to 30 days and is bounded to 90 days. Missing membership snapshots and shared reward claims are null. Requires guild administrator permissions and the analytics feature.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Campaign measurements with source and freshness notes. (CampaignAnalyticsResponse)

• 401 Not logged in.
• 403 Guild admin permissions or analytics subscription required.
• 404 Guild does not exist.
• 422 Invalid date range or campaign catalogue exceeds the bounded limits.
• 429 Rate limit hit.
• 500 Analytics unavailable; failed queries never become zero-valued measurements.

Get guild member count history

GET https://api.guild.xyz/analytics/{guildIdLike}/members

Time series of the guild's member count, bucketed by interval (default hour) between startDate and endDate (both default to the last 7 days). Requires the guild's subscription to include the analytics feature.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The guild's member-count snapshots. (AnalyticsGuildMembersResponse)

• 401 Not logged in.
• 403 Not a guild admin, owner, or superAdmin; or the guild's subscription lacks the "analytics" feature.
• 404 No guild matches guildIdLike.
• 422 Request validation failed: guildIdLike is not a UUID, interval is not one of hour, day, week, month, or startDate/endDate is not a string.
• 429 Rate limit hit. See the Retry-After header.

Get guild page view history

GET https://api.guild.xyz/analytics/{guildIdLike}/page-views

Time series of page visitors and active-member visitors, bucketed by interval (default hour) between startDate and endDate (both default to the last 7 days). Requires the guild's subscription to include the analytics feature.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The guild's page-view snapshots. (AnalyticsGuildPageViewsResponse)

• 401 Not logged in.
• 403 Not a guild admin, owner, or superAdmin; or the guild's subscription lacks the "analytics" feature.
• 404 No guild matches guildIdLike.
• 422 Request validation failed: guildIdLike is not a UUID, interval is not one of hour, day, week, month, or startDate/endDate is not a string.
• 429 Rate limit hit. See the Retry-After header.

Get guild reward claim counts

GET https://api.guild.xyz/analytics/{guildIdLike}/reward-claims

Per-reward claim counts (get_reward events) and the number of unique claimers for the guild between startDate and endDate (both default to the last 7 days). Requires the guild's subscription to include the analytics feature.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Reward claim counts. (AnalyticsGuildRewardClaimsResponse)

• 401 Not logged in.
• 403 Not a guild admin, owner, or superAdmin; or the guild's subscription lacks the "analytics" feature.
• 404 No guild matches guildIdLike.
• 422 Request validation failed: guildIdLike is not a UUID, or startDate/endDate is not a string.
• 429 Rate limit hit. See the Retry-After header.

Get guild role member count history

GET https://api.guild.xyz/analytics/{guildIdLike}/roles

Time series of member counts per role, bucketed by interval (default hour) between startDate and endDate (both default to the last 7 days). Requires the guild's subscription to include the analytics feature.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Per-role member-count snapshots. (AnalyticsGuildRolesResponse)

• 401 Not logged in.
• 403 Not a guild admin, owner, or superAdmin; or the guild's subscription lacks the "analytics" feature.
• 404 No guild matches guildIdLike.
• 422 Request validation failed: guildIdLike is not a UUID, roleIds is neither a string nor an array, interval is not one of hour, day, week, month, or startDate/endDate is not a string.
• 429 Rate limit hit. See the Retry-After header.

Chains

List all chains

GET https://api.guild.xyz/chains

Returns the fixed list of chains the Guild backend supports, including RPC URLs, contracts, and integration support flags for each. Static data — no database access — always the same 63 chains in the same order. Kept for legacy callers such as the billing service; internal Guild services should prefer the shared chains constant over calling this endpoint.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: Every supported chain. (ChainResponse[])

• 429 Rate limit hit — only reachable when the caller has an active Guild session, since this route has no per-route auth. See the Retry-After header.

Get a chain by id

GET https://api.guild.xyz/chains/{id}

Looks up a single chain from the same static list as GET /chains, by its string id — not its numeric chainId.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: The matching chain. (ChainResponse)

• 404 No chain matches id. Body: { "message": "Chain not found" }.
• 429 Rate limit hit — only reachable when the caller has an active Guild session, since this route has no per-route auth. See the Retry-After header.

Compliance

Delete a user's backend-owned data

DELETE https://api.guild.xyz/compliance/users/{userId}

Permanently deletes the user's backend-owned data — guild memberships, role progress, reward claims, point transactions, form submissions, and the user record itself — while retaining an audit log entry and billing records. Restricted to Guild's own internal privileged callers and superadmins; not a partner-integration endpoint.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Compliance delete completed. (ComplianceDeleteResponse)

• 401 Not logged in, or the Guild session token is invalid or expired.
• 403 Logged in, but the caller is neither a superadmin nor an internal privileged caller.
• 404 No user with this id.
• 409 The user still owns one or more guilds. Transfer or delete those guilds first.
• 422 userId is not a valid UUID.
• 429 Rate limit hit. See the Retry-After header.

Crm

Search guild members

GET https://api.guild.xyz/crm/{guildIdLike}

Search and filter a guild's members for the CRM view. campaignId selects current members with ANY native campaign role and cannot be combined with other filters. Campaign and role cohorts are bounded to 100,000 members and sorted by joinedAt then userId before pagination. roleIds and rewardIds are mutually-exclusive priority filters: a non-empty roleIds wins over everything else; else a non-empty rewardIds wins over search/locations; only when both are empty do search and locations apply. The total match count is reported in the X-Total-Items response header — see that header's own description for when it is exact vs. approximate vs. unknown.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Matching guild members. (CrmMemberResult[])

• 401 Not logged in.
• 403 Logged in, but not an admin of this guild.
• 404 No guild found for guildIdLike.
• 422 Request validation failed: an out-of-range guildIdLike, or an invalid query parameter.
• 429 Rate limit hit. See the Retry-After header.

Get the guild's activity feed

GET https://api.guild.xyz/crm/{guildIdLike}/activity

Get a chronological (newest-first) feed of activity across all of a guild's members: joins, leaves, role gains/losses, reward claims/revokes, points earned/deducted, identity connects/disconnects, and form submissions. Backed by ClickHouse analytics events; each event is enriched with the acting user's identity info under actor. Returns a 200 with an empty events array (not a 404) when nothing matches. Deliberately exempt from the global per-user rate limit — admin dashboards fire several concurrent chart requests — so this route never answers 429.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The guild's activity feed. (MemberTimelineActivityResponse)

• 401 Not logged in.
• 403 Logged in, but not an admin of this guild.
• 404 No guild found for guildIdLike.
• 422 Request validation failed: an out-of-range guildIdLike, or an invalid query parameter.

Queue a member export

POST https://api.guild.xyz/crm/{guildIdLike}/export/async

Queue an async CSV export of guild members matching the given filters (the same filters as GET /crm/{guildIdLike}, minus limit/offset — an export always covers the full matching set, not one page; a limit/offset sent here is ignored). Returns immediately with a job id; poll GET /crm/{guildIdLike}/export/status/{jobId} for progress and the eventual download URL.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 202: Export job created and queued. (CrmExportJobCreated)

• 401 Not logged in.
• 403 Logged in, but not an admin of this guild.
• 404 No guild found for guildIdLike.
• 422 Request validation failed: an out-of-range guildIdLike, or an invalid query parameter.
• 429 Rate limit hit. See the Retry-After header.

Cancel an export job

POST https://api.guild.xyz/crm/{guildIdLike}/export/cancel/{jobId}

Cancel a pending or processing member export job. Only the job's creator or a superadmin may cancel it. Cancelling an already-cancelled job is a no-op that still returns 200; a completed or failed job can no longer be cancelled and returns 400 instead.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The job was already cancelled, or was just cancelled. (CrmExportCancelResult)

• 400 The job already finished (completed or failed) and can no longer be cancelled.
• 401 Not logged in.
• 403 Not an admin of this guild, or (if the job exists) neither the job's creator nor a superadmin.
• 404 No guild found for guildIdLike, or no export job found for jobId.
• 422 Request validation failed: jobId is not a UUID, or an out-of-range guildIdLike.
• 429 Rate limit hit. See the Retry-After header.

Get export job status

GET https://api.guild.xyz/crm/{guildIdLike}/export/status/{jobId}

Get the status of a member export job. Only the job's creator or a superadmin may view it: the 403 response here can mean either that the caller isn't an admin of this guild, or (if the job exists) that the caller is neither the job's creator nor a superadmin. The stored query snapshot always shows limit: 0, offset: 0 since an export covers the full matching set.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The export job. (CrmExportJob)

• 401 Not logged in.
• 403 Not an admin of this guild, or (if the job exists) neither the job's creator nor a superadmin.
• 404 No guild found for guildIdLike, or no export job found for jobId.
• 422 Request validation failed: jobId is not a UUID, or an out-of-range guildIdLike.
• 429 Rate limit hit. See the Retry-After header.

List recent exports

GET https://api.guild.xyz/crm/{guildIdLike}/exports/recent

List the guild's completed member-export files, most recent first, with each file's export-job record resolved. Returns an empty exports array rather than an error when the guild has no exports yet.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Recent exports. (CrmExportsRecentResponse)

• 401 Not logged in.
• 403 Logged in, but not an admin of this guild.
• 404 No guild found for guildIdLike.
• 422 Request validation failed: an out-of-range guildIdLike.
• 429 Rate limit hit. See the Retry-After header.

Get a member's activity timeline

GET https://api.guild.xyz/crm/{guildIdLike}/members/{userId}/timeline

Get a chronological (newest-first) timeline of one guild member's activity: guild joins, identity connects, role gains/losses, reward claims/revokes, points earned/deducted, and form submissions. Returns a 200 with an empty events array when the member has no recorded activity. 404 when userId is not a current member of the guild (the timeline exposes the member's connected accounts).

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The member's activity timeline. (MemberTimelineResponse)

• 401 Not logged in.
• 403 Logged in, but not an admin of this guild.
• 404 No guild found for guildIdLike, or userId is not a current member of it.
• 422 Request validation failed: userId is not a UUID, an out-of-range guildIdLike, or an invalid query parameter.
• 429 Rate limit hit. See the Retry-After header.

Boosts

Boosted guilds for Explore

GET https://api.guild.xyz/guild-boosts/boosted

Level 1 and up.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Resolve a vanity alias

GET https://api.guild.xyz/guild-vanity/{alias}

404 below level 3.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Public boost status of a guild

GET https://api.guild.xyz/guilds/{guildIdLike}/boosts

Optional session adds viewer. Cached 60 seconds.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Set or clear the animated banner

PUT https://api.guild.xyz/guilds/{guildIdLike}/boosts/animated-banner

Level 2. Guild admins only.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Recreate the Booster role

POST https://api.guild.xyz/guilds/{guildIdLike}/boosts/booster-role

Guild admins only.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Is this member boosting the guild

GET https://api.guild.xyz/guilds/{guildIdLike}/boosts/members/{userId}

Public. since is unix seconds.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Release the vanity alias

DELETE https://api.guild.xyz/guilds/{guildIdLike}/boosts/vanity

Guild admins only.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Claim a vanity alias

PUT https://api.guild.xyz/guilds/{guildIdLike}/boosts/vanity

Level 3. 409 VANITY_TAKEN.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

A guild's custom emoji

GET https://api.guild.xyz/guilds/{guildIdLike}/custom-emoji

Public.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Add a custom emoji

POST https://api.guild.xyz/guilds/{guildIdLike}/custom-emoji

Level 2. 409 EMOJI_LIMIT.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Archive a custom emoji

DELETE https://api.guild.xyz/guilds/{guildIdLike}/custom-emoji/{emojiId}

Guild admins only.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

The caller's boost slots

GET https://api.guild.xyz/me/boosts

MyBoosts.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Release a boost slot

DELETE https://api.guild.xyz/me/boosts/{slot}

The cooldown still applies to the next assignment.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Assign or move a boost

PUT https://api.guild.xyz/me/boosts/{slot}

403 PLUS_REQUIRED, 422 BOOST_SLOT_INVALID, 409 BOOST_COOLDOWN.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Restore a slot after resubscribing

POST https://api.guild.xyz/me/boosts/{slot}/restore

Ignores the cooldown.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (BoostJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Guilds

Search guilds

GET https://api.guild.xyz/guilds

Public guild search/listing with optional filters. Unlike GET /guilds/{guildIdLike}, results are always returned at admin-level detail — system-visibility rewards and non-public platforms are not filtered out here, regardless of the caller.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: Matching guilds. (GuildsGuild[])

• 422 The query parameters failed validation (e.g. search is 1-2 characters, or limit/offset out of range).

Create a guild

POST https://api.guild.xyz/guilds

Create a guild owned by the logged-in user, along with a default "Home" page and "Member" role. If page/role creation fails, the guild is rolled back and deleted. urlName defaults to a slugified name when omitted.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (GuildsCreateGuildRequest):

Returns 201: The newly created guild. (GuildsGuild)

• 400 Malformed JSON in the request body.
• 401 Not logged in.
• 409 The (given or auto-derived) urlName is already taken by another guild.
• 422 Request body failed validation (e.g. missing name/contacts, or an empty contacts array).
• 429 Rate limit hit (600 requests/minute per user). See the Retry-After header.

Delete a guild

DELETE https://api.guild.xyz/guilds/{guildIdLike}

Delete a guild along with its roles, pages, rewards and platforms. Requires the current owner (or a superadmin). Any active Stripe subscription is cancelled on a best-effort basis — a Stripe failure is logged but does not block the delete.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 204: The guild was deleted.

• 401 Not logged in.
• 403 The caller is not the guild owner (or a superadmin).
• 404 No guild with this id/url name.
• 422 guildIdLike failed validation (must be a UUID or a 1-50 character url name).
• 429 Rate limit hit (600 requests/minute per user). See the Retry-After header.

Get a guild

GET https://api.guild.xyz/guilds/{guildIdLike}

Get a guild by id or url name. Public — no authentication required. Callers below admin access get a filtered view: system-visibility rewards and non-PUBLIC platforms are omitted. Also mounted at GET /v2/guilds/{guildIdLike} as a legacy alias.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: The guild. (GuildsGuild)

• 404 No guild with this id/url name.
• 422 guildIdLike failed validation (must be a UUID or a 1-50 character url name).

Update a guild

PUT https://api.guild.xyz/guilds/{guildIdLike}

Partially update a guild; only the fields present in the body are changed. Requires at least admin access. Changing isVerified, tags, featureFlags or subscription additionally requires superadmin rank; changing admins or owner additionally requires the current owner (or a superadmin).

Auth: your signed-in Guild session (x-guild-auth-token).

Body (GuildsUpdateGuildRequest):

Returns 200: The updated guild. (GuildsGuild)

• 400 mainPointsPlatformId is not a POINTS platform of this guild, a gated entry is missing/has an invalid role, or nested rewards/platforms belong to a different guild.
• 401 Not logged in.
• 403 Below admin access for this guild; the update touches a superadmin-only or owner-only field without that rank; or an admin addition exceeds the guild's included seats.
• 404 Guild not found, or (when changing admins/owner) the referenced user id does not exist.
• 422 guildIdLike or the request body failed validation.
• 429 Rate limit hit (600 requests/minute per user). See the Retry-After header.

Reorder a guild's pages

PUT https://api.guild.xyz/guilds/{guildIdLike}/pages/order

Set the display order of the guild's pages. pageIds must be exactly the guild's current page ids as a permutation (no additions, removals or duplicates); otherwise 400 with code PAGE_ORDER_MISMATCH naming the missing and extra ids. Page references are preserved as stored; only their order changes. Prefer this to sending pages in PUT /guilds/{guildIdLike}, which replaces the list and drops any page left out.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (GuildsPageOrderRequest):

Returns 200: The updated guild. (GuildsGuild)

• 400 pageIds is not a permutation of the guild's pages (PAGE_ORDER_MISMATCH).
• 401 Not logged in.
• 403 Below admin access for this guild.
• 404 Guild not found.
• 422 guildIdLike failed validation, or pageIds is not an array of UUIDs.
• 429 Rate limit hit. See the Retry-After header.

Get a guild (legacy v2 path)

GET https://api.guild.xyz/v2/guilds/{guildIdLike}

Deprecated alias of GET /guilds/{guildIdLike}, kept for v2 API consumers. Identical behaviour and response; prefer the canonical path in new integrations.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: The guild. (GuildsGuild)

• 404 No guild with this id/url name.
• 422 guildIdLike failed validation (must be a UUID or a 1-50 character url name).

Roles

Why members miss each role

GET https://api.guild.xyz/guilds/{guildIdLike}/access-insights

Guild admins only. Per requirement of each role, how many members pass, fail or have not been evaluated yet, read from the protocol's access tables. At most 1,000 members are examined; a larger guild is estimated and says sampled: true. "Not evaluated" is never counted as a failure. Cached for five minutes. 503 INSIGHTS_TIMEOUT when the data is too slow to read.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (AccessInsightsJson)

• 401 Signed out.
• 403 Not a guild admin.
• 404 No such guild.
• 503 Too slow to read right now.

List roles

GET https://api.guild.xyz/roles

List roles filtered by exactly one of 'guildIdLike', 'pageIdLike', or 'rewardId'. Non-admin callers should still pass 'guildIdLike' even when filtering by 'pageIdLike'/'rewardId' alone — omitting it can trigger an unrelated 400 from an internal visibility check that runs after a successful lookup. For non-admin callers, roles they can't see are silently dropped from 'data' and a 'secrets' count of the dropped roles is added to the response.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: The matching roles. (RolesRoleListResponse)

• 400 Thrown by an internal visibility check, not this handler's own validation: a non-admin caller filtered by only 'pageIdLike' or only 'rewardId' without also passing 'guildIdLike'.
• 404 Guild not found, or page not found.
• 422 None of 'guildIdLike'/'pageIdLike'/'rewardId' given, or a param fails validation.
• 503 Visibility filtering failed transiently; safe to retry.

Create a role

POST https://api.guild.xyz/roles

Create a role in a guild (optionally attaching it to a page) and its Protocol access role. Requires guild admin, owner, or super-admin access.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (RolesCreateRoleRequest):

Returns 201: The created role. (RolesRoleResponse)

• 400 Malformed JSON body.
• 401 Not logged in.
• 403 Caller isn't an admin, owner, or super-admin of the guild.
• 404 Guild not found, or 'pageIdLike' doesn't resolve to a page in the guild.
• 422 Invalid query params, or the body fails role validation (e.g. missing 'name').
• 429 Rate limit hit. See the Retry-After header.

Get role limits and member numbers

GET https://api.guild.xyz/roles/claims

For the asked-about roles that are limited ("the first N members") or numbered ("#1, #2, … in the order members got it"): the limit, how many numbers are given out, and the caller's own number when logged in. Roles that are neither are left out, as are roles of other guilds and roles that aren't public unless the caller holds a number in them.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: The limited or numbered roles. (RolesClaimSummariesResponse)

• 404 Guild not found.
• 422 Missing 'guildIdLike', or a role id isn't a UUID.
• 502 Protocol is unreachable.

Delete a role

DELETE https://api.guild.xyz/roles/{roleId}

Detach a role from a page; the role (and its Protocol access role) is only actually deleted once it has been removed from its last page. Requires guild admin, owner, or super-admin access.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 204: The role was detached from the page (and deleted, if this was its last page).

• 401 Not logged in.
• 403 Caller isn't an admin, owner, or super-admin of the guild.
• 404 Guild not found, page not found, or role not found.
• 422 Missing/invalid 'guildIdLike' or 'pageIdLike'.
• 429 Rate limit hit. See the Retry-After header.

Get a role

GET https://api.guild.xyz/roles/{roleId}

Fetch a single role by id. A 404 can mean the role truly doesn't exist, or that it exists but its visibility is restricted (SELF_REVEAL/SECRET/HIDDEN) and the caller lacks read access to it.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: The role. (RolesRoleResponse)

• 404 The guild or the role wasn't found, or the role isn't visible to the caller.
• 422 Missing/invalid 'guildIdLike', or 'roleId' isn't a UUID.
• 503 Visibility filtering failed transiently; safe to retry.

Update a role

PUT https://api.guild.xyz/roles/{roleId}

Partially update a role; only the fields present in the body are changed. Updating 'logic' also updates the role's Protocol access role, and can return 409 if the logic was changed concurrently by another request. Requires guild admin, owner, or super-admin access.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (RolesUpdateRoleRequest):

Returns 200: The updated role. (RolesRoleResponse)

• 400 Malformed JSON body.
• 401 Not logged in.
• 403 Caller isn't an admin, owner, or super-admin of the guild.
• 404 Guild not found, or role not found.
• 409 The role's logic changed concurrently while this request was updating it; retry.
• 422 Missing/invalid 'guildIdLike', 'roleId' isn't a UUID, or the body fails validation.
• 429 Rate limit hit. See the Retry-After header.

Get a role's member limit

GET https://api.guild.xyz/roles/{roleId}/claim-policy

The role's member limit and numbering, and how many numbers are given out. Requires guild admin, owner, or super-admin access.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The limit, or null. (RolesClaimPolicyResponse)

• 401 Not logged in.
• 403 Caller isn't an admin, owner, or super-admin of the guild.
• 404 Guild or role not found.

Set a role's member limit

PUT https://api.guild.xyz/roles/{roleId}/claim-policy

Limit the role to its first capacity members and/or number its members in the order they get it, optionally holding back the first reserved numbers for admins to assign (they count toward capacity, and members are numbered after them). A limit always numbers the members, and counts seats taken: a member who loses the role keeps their number and their seat, so a full role stays full. Turning numbering on numbers the current members in the order they got the role. Turning it off keeps every number. Requires guild admin, owner, or super-admin access.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (RoleClaimPolicy):

Returns 200: The role's limit after the change. (RolesClaimPolicyResponse)

• 400 Malformed JSON body.
• 401 Not logged in.
• 403 Caller isn't an admin, owner, or super-admin of the guild.
• 404 Guild or role not found.
• 422 The limit isn't between 1 and 1,000,000,000, or the body has unknown fields.

List a role's member numbers

GET https://api.guild.xyz/roles/{roleId}/claims

The role's members in number order, with when each got their number. Requires guild admin, owner, or super-admin access.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The members, lowest number first. (RolesClaimsResponse)

• 401 Not logged in.
• 403 Caller isn't an admin, owner, or super-admin of the guild.
• 404 Guild or role not found.

Free a reserved member number

DELETE https://api.guild.xyz/roles/{roleId}/claims/{number}

Take a reserved number back from its member. If they have the role they keep it, without a number. Requires guild admin, owner, or super-admin access.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 204: Freed (or it was already free).

• 401 Not logged in.
• 403 Caller isn't an admin, owner, or super-admin of the guild.
• 404 Guild or role not found.
• 422 Not one of the role's reserved numbers.

Assign a reserved member number

PUT https://api.guild.xyz/roles/{roleId}/claims/{number}

Give a member one of the numbers the role holds back for admins (see reserved on the claim policy). A member who already had a number moves, and their old one goes to the next member who gets the role. It doesn't grant the role: the member gets it, with this number, once they qualify. Requires guild admin, owner, or super-admin access.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (RolesAssignClaimRequest):

Returns 200: Assigned. (RolesAssignClaimResponse)

• 401 Not logged in.
• 403 Caller isn't an admin, owner, or super-admin of the guild.
• 404 Guild or role not found, or no member has that email, Discord name or wallet.
• 409 Another member has this number, or several members have used that Discord name.
• 422 Not one of the role's reserved numbers, or a bad body.

Get a role's member count

GET https://api.guild.xyz/roles/{roleId}/member-count

Member count for the role, read from Protocol. Protocol evaluates access, so it is the only store of this number; if it cannot be reached the endpoint fails rather than answering with a stale one.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: The role's member count. (RolesMemberCountResponse)

• 422 'roleId' isn't a UUID.
• 502 Protocol is unreachable or doesn't know this role.

List roles of a guild

GET https://api.guild.xyz/v1/guilds/{guildId}/roles

List roles of a guild, paginated. Unlike the public roles endpoint, this endpoint does not filter roles by visibility: SECRET/HIDDEN roles are included too, and each role's 'requirements' array is always present.

Auth: API key, as Authorization: Bearer <key>.

Returns 200: The guild's roles. (V1RolesRoleResponse[])

• 401 Missing or invalid API key.
• 403 API key not valid for this guild, or no subscription.
• 404 No guild matches 'guildId'.
• 422 'limit' or 'offset' failed validation (e.g. 'limit' above 10).
• 429 Rate limit hit. See the Retry-After header.

Get member addresses

GET https://api.guild.xyz/v1/guilds/{guildId}/roles/{roleId}/member-addresses

Get the addresses of role members, paginated. The response may contain null entries: some members have no EVM wallet connected to their guild account, and returning them is necessary so the caller knows when to stop paginating.

Auth: API key, as Authorization: Bearer <key>.

Returns 200: Addresses of role members. An entry is null when that member has no linked EVM address. (string[])

• 401 Missing or invalid API key.
• 403 API key not valid for this guild, or no subscription. Also returned as 'No access to this role' when the role resolved from 'roleId' belongs to a different guild than 'guildId'.
• 404 No guild matches 'guildId', or no role matches 'roleId'.
• 422 'limit' or 'offset' failed validation (e.g. 'limit' above 1000).
• 429 Rate limit hit. See the Retry-After header.

Audit Log

Record an admin panel entry

POST https://api.guild.xyz/guilds/{guildIdLike}/admin/entry

Records an admin_panel.enter audit log event for the caller entering this guild's admin panel. The audit write is fire-and-forget — it happens in the background and its outcome does not affect the response — so this endpoint returns 204 even if the write itself later fails.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 204: Entry accepted. The audit log write itself happens asynchronously.

• 401 Missing or invalid Guild session.
• 403 Caller is authenticated but is not an admin, owner, or super admin of this guild.
• 404 No guild matches guildIdLike.
• 429 Rate limit hit. See the Retry-After header.

List a guild's audit log

GET https://api.guild.xyz/guilds/{guildIdLike}/audit-log

Lists this guild's audit log entries, newest first, each enriched with the acting user's display name, avatar, and primary connected identity. The total number of matching rows (ignoring limit/offset) is returned in the X-Total-Items header.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The guild's audit log entries, newest first. (AuditLogEntryResponse[])

• 401 Missing or invalid Guild session.
• 403 Caller is authenticated but is not an admin, owner, or super admin of this guild.
• 404 No guild matches guildIdLike.
• 422 limit or offset failed validation (not an integer, or out of range).
• 429 Rate limit hit. See the Retry-After header.

Access

Claim roles in a guild

POST https://api.guild.xyz/guilds/{guildIdLike}/claim-roles

Evaluate and claim one or more roles in a guild for the authenticated user. The caller must already be a member of the guild. Pass userId in the body to claim on behalf of a different user, but this only takes effect when the authenticated caller is a superAdmin — everyone else always claims for themselves. Pass claimInvisibleRoles=true to instead claim every secret / self-reveal role the caller currently has access to (admin roles excluded); in that mode roleIds may be omitted.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (AccessClaimRolesRequest):

Returns 200: Roles claimed. Entries that were skipped (e.g. an admin role filtered out of an invisible-role claim) still appear in claimedRoles, but carry only roleId — the controller's skipped marker is not forwarded. (AccessClaimRolesResponse)

• 400 Malformed JSON request body, or roleIds was empty while claimInvisibleRoles was not true.
• 401 Not logged in.
• 403 The caller is not a member of this guild.
• 404 No guild matches guildIdLike.
• 422 A path/query/body value failed validation (invalid guildIdLike shape, a non-UUID entry in roleIds, an invalid userId, or claimInvisibleRoles not true/false).
• 429 Rate limit hit. See the Retry-After header.
• 504 The claim timed out, or the client disconnected before it finished. Safe to retry.

Join a guild

POST https://api.guild.xyz/join

Join an open guild as the authenticated user. Returns 200 with success: true both when the join succeeds and when the caller is already a member. Guilds whose entry type is private or gated currently reject the join with 403.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (AccessJoinGuildRequest):

Returns 200: Joined the guild, or the caller was already a member. (AccessJoinGuildResponse)

• 400 Malformed JSON request body.
• 401 Not logged in.
• 403 The guild's entry type is private or gated; joining via this endpoint is not currently supported for it.
• 404 No guild matches guildId.
• 422 Request body failed validation (missing/invalid guildId).
• 429 Rate limit hit. See the Retry-After header.

Leave a guild

POST https://api.guild.xyz/leave

Leave a guild as the authenticated user. The body's userId is validated but not otherwise used — the guild is always left on behalf of the authenticated caller, never on behalf of the supplied userId. Returns 200 with an empty body (no JSON) when the caller was not a member of the guild; this is not a 404.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (AccessLeaveGuildRequest):

Returns 200: Left the guild. When the caller was not a member, this is instead an empty body rather than this schema. (AccessLeaveGuildResponse)

• 400 Malformed JSON request body.
• 401 Not logged in.
• 404 No guild matches guildId.
• 422 Request body failed validation (missing/invalid userId or guildId).
• 429 Rate limit hit. See the Retry-After header.
• 504 The leave timed out, or was aborted before it finished. Safe to retry.

Get a user's guild memberships

GET https://api.guild.xyz/users/{userId}/memberships

List a user's enriched guild memberships, optionally scoped to a single guild via the guildId query param. Returns null (not an empty array or a 404) when the user has no memberships, or none matching guildId. Public endpoint — no authentication required, and exempt from the per-user rate limiter.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: The user's memberships, or null. (AccessMembership[])

• 404 guildId was supplied but no guild matches it.
• 422 A path or query param failed validation (userId not a UUID, an invalid guildId, or includeMetadata / includePoints / includeVisibility not one of their allowed values).
• 504 The lookup timed out, or the client disconnected before it finished. Safe to retry.

Launch

Cancel the launch

DELETE https://api.guild.xyz/guilds/{guildIdLike}/launch

Opens joins. Interest rows are kept.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (LaunchJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

The launch page of a coming-soon guild

GET https://api.guild.xyz/guilds/{guildIdLike}/launch

Optional session adds viewer. 404 when the guild has no launch.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (LaunchJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Create or edit the launch

PUT https://api.guild.xyz/guilds/{guildIdLike}/launch

Guild admins only. 409 GUILD_ALREADY_LIVE, 422 NUMBER_RANGE_NOT_RESERVED.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (LaunchJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Withdraw interest

DELETE https://api.guild.xyz/guilds/{guildIdLike}/launch/interest

Not for a pre-registration after launch.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (LaunchJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Notify me or pre-register

PUT https://api.guild.xyz/guilds/{guildIdLike}/launch/interest

PREREG needs Guild Plus.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (LaunchJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Launch now

POST https://api.guild.xyz/guilds/{guildIdLike}/launch/launch-now

Sets the launch time to now; the worker finishes within a minute.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (LaunchJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Pre-registered members

GET https://api.guild.xyz/guilds/{guildIdLike}/launch/preregistrations

Guild admins only. Notify-only members are a count.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (LaunchJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Pre-registered members as CSV

GET https://api.guild.xyz/guilds/{guildIdLike}/launch/preregistrations/export

Guild admins only. Columns: name, profile, reserved_number, status (joined or waiting), registered_at. At most 50,000 rows.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: CSV file.

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 503 Not available yet.

Upcoming launches

GET https://api.guild.xyz/launches/upcoming

Verified or boosted guilds. Cached 5 minutes.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (LaunchJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

The caller's launch interests

GET https://api.guild.xyz/me/launches

Signed in.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: Done. (LaunchJson)

• 401 Signed out.
• 403 Not allowed.
• 404 Not found.
• 409 Conflict.
• 422 Invalid input.
• 503 Not available yet.

Pin

Get a guild's Pin preview image CID

GET https://api.guild.xyz/guilds/{guildIdLike}/pin

Returns the IPFS CID of the Guild Pin preview image for guildAction, generating it (and Redis-caching the result for 24h) the first time it's requested. This is a preview only: it does not require authentication and does not check whether Guild Pin is enabled for the guild, unlike POST of the same path, which signs a mint authorization for the caller.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: The Pin preview image CID. (PinCidResponse)

• 400 The guild has no custom logo (still the default /guildLogos placeholder) or no customization.accentColor set, so a Pin image can't be generated.
• 404 No guild matches guildIdLike.
• 422 guildAction is present but not one of JOINED_GUILD, IS_OWNER, IS_ADMIN, or guildIdLike failed validation (must be a UUID or a 1-50 character url name).
• 429 Rate limit hit — only reachable when the caller has an active Guild session, since this route has no per-route auth. See the Retry-After header.
• 500 Unexpected error generating or pinning the preview image to IPFS.

Claim a guild Pin

POST https://api.guild.xyz/guilds/{guildIdLike}/pin

Builds and EIP-191-signs a mint payload for the caller's Guild Pin NFT for guildAction, against one of the caller's own linked EVM WALLET addresses. This does not submit an onchain transaction — the caller submits the returned signature in their own mint call. The caller must actually satisfy guildAction (guild membership for JOINED_GUILD/IS_ADMIN — admins get the same membership-gated Pin as regular members today, not an admin-specific check — or being the recorded guild owner for IS_OWNER), must not have already minted this action's Pin, and Guild Pin must be enabled and configured for a supported chain on this guild.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (PinClaimRequest):

Returns 200: The signed mint payload. (PinClaimResponse)

• 400 Malformed JSON body; the guild's configured Guild Pin chain is unrecognized or has no RPC endpoint, Multicall3 address, or Guild Pin contract configured; or the guild has no custom logo/accent color set so the Pin image can't be generated.
• 401 Not logged in.
• 403 userAddress is not one of the caller's own linked EVM WALLET identities.
• 404 No guild matches guildIdLike, or the signed-in session's own user record no longer exists.
• 422 userAddress is missing or not a 0x-prefixed 20-byte hex address, or guildAction is not one of JOINED_GUILD, IS_OWNER, IS_ADMIN.
• 429 Rate limit hit. See the Retry-After header.
• 500 Guild Pin is not enabled for this guild; the caller already minted this guildAction's Pin; the caller doesn't satisfy guildAction's requirement; the mint creation timestamp couldn't be determined; or an unexpected upstream/RPC/IPFS error occurred.

Point Transactions

Get a user's point balance

GET https://api.guild.xyz/guilds/{guildIdLike}/points/{platformId}/balance/{userId}

Get a user's current balance and leaderboard rank on a POINTS platform. Public: no session or API key is required for a visible platform. Hidden systems require the owning guild's admin access. The platform must belong to the requested guild; negative balances are preserved.

Auth: not declared in the OpenAPI document; endpoint permissions still apply.

Returns 200: The user's balance and rank. (PointTransactionsUserBalanceResponse)

• 404 Guild not found.
• 429 Rate limit hit. See the Retry-After header.

List point transactions

GET https://api.guild.xyz/guilds/{guildIdLike}/points/{platformId}/transactions

List the point_transaction ledger for a platform, newest first, optionally scoped to one user. Requires guild admin, owner, or super-admin access to guildIdLike. The target must be a POINTS platform belonging to that guild.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The transaction history, newest first. (PointTransactionsTransaction[])

• 400 The platform isn't a POINTS platform belonging to this guild.
• 401 Not logged in.
• 403 Caller isn't an admin, owner, or super-admin of the guild.
• 404 Guild not found.
• 422 userId isn't a UUID, or limit/offset isn't a number.
• 429 Rate limit hit. See the Retry-After header.

Grant or deduct points

POST https://api.guild.xyz/guilds/{guildIdLike}/points/{platformId}/transactions

Create a single admin points-ledger transaction on a POINTS platform: a positive amount grants points, a negative amount deducts them. Returns the user's new balance. Requires guild admin, owner, or super-admin access.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (PointTransactionsTransactionInput):

Returns 201: The transaction was recorded; body is the user's new balance. (PointTransactionsBalanceResponse)

• 400 Malformed JSON body, or platformId isn't a POINTS platform belonging to this guild.
• 401 Not logged in.
• 403 Caller isn't an admin, owner, or super-admin of the guild.
• 404 Guild not found.
• 422 userId isn't a UUID, amount isn't a non-zero integer, or note isn't a string.
• 429 Rate limit hit. See the Retry-After header.

Bulk grant or deduct points

POST https://api.guild.xyz/guilds/{guildIdLike}/points/{platformId}/transactions/bulk

Create up to 500 admin points-ledger transactions on a POINTS platform in one call; each entry grants (positive amount) or deducts (negative) points for its own userId. Requires guild admin, owner, or super-admin access.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (PointTransactionsBulkCreateRequest):

Returns 201: The transactions were recorded. (PointTransactionsBulkCreateResponse)

• 400 Malformed JSON body, or platformId isn't a POINTS platform belonging to this guild.
• 401 Not logged in.
• 403 Caller isn't an admin, owner, or super-admin of the guild.
• 404 Guild not found.
• 422 transactions isn't an array, has more than 500 entries, or one of its entries fails validation (invalid userId, non-zero-integer amount, or non-string note).
• 429 Rate limit hit. See the Retry-After header.

Member profiles

A guild's profile items

GET https://api.guild.xyz/guilds/{guildIdLike}/profile-items

Guild admins and owners. customSlots is 10 with the custom_profile_items feature plus the boost-level bonus (0, 5, 15 or 30).

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The GuildProfileItemList. (GuildProfileItemList)

• 401 Signed out.
• 403 Not a guild admin.
• 404 No such guild.
• 503 PROFILES_UNAVAILABLE.

Create a guild profile item

POST https://api.guild.xyz/guilds/{guildIdLike}/profile-items

Guild admins and owners. Built-in starter art is open to any guild (50 active items). Uploaded art needs a free custom slot: 403 GUILD_PLAN_REQUIRED when the guild has none, 409 ITEM_SLOTS_FULL (with limit) when all are used.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (GuildItemBody):

Returns 201: The item. (GuildProfileItem)

• 401 Signed out.
• 403 Not a guild admin, or GUILD_PLAN_REQUIRED.
• 409 ITEM_SLOTS_FULL.
• 422 Validation failed or INVALID_UPLOAD.
• 503 PROFILES_UNAVAILABLE.

Archive a guild profile item

DELETE https://api.guild.xyz/guilds/{guildIdLike}/profile-items/{itemId}

Guild admins and owners. The item stops being offered; members who hold it keep it equipped only until their next change.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 204: Archived.

• 401 Signed out.
• 403 Not a guild admin.
• 404 No such item.
• 503 PROFILES_UNAVAILABLE.

Edit a guild profile item

PATCH https://api.guild.xyz/guilds/{guildIdLike}/profile-items/{itemId}

Guild admins and owners. Replacing uploaded art with uploaded art keeps its slot.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (GuildItemPatchBody):

Returns 200: The item. (GuildProfileItem)

• 401 Signed out.
• 403 Not a guild admin, or GUILD_PLAN_REQUIRED.
• 404 No such item.
• 409 ITEM_SLOTS_FULL.
• 422 Validation failed or INVALID_UPLOAD.
• 503 PROFILES_UNAVAILABLE.

Whether a handle is free

GET https://api.guild.xyz/handles/{handle}/availability

available: false with reason INVALID, RESERVED or TAKEN.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The answer. (HandleAvailability)

• 503 PROFILES_UNAVAILABLE.

My per-guild profiles

GET https://api.guild.xyz/me/guild-profiles

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: GuildProfileEntry[]. (GuildProfileEntry[])

• 401 Signed out.

Remove my profile in a guild

DELETE https://api.guild.xyz/me/guild-profiles/{guildId}

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: All the caller's per-guild profiles. (GuildProfileEntry[])

• 401 Signed out.
• 503 PROFILES_UNAVAILABLE.

Set my nickname and avatar in a guild

PUT https://api.guild.xyz/me/guild-profiles/{guildId}

Plus, and the member must belong to the guild. Sending neither field removes it.

Auth: your signed-in Guild session (x-guild-auth-token).

Body (GuildProfileBody):

Returns 200: All the caller's per-guild profiles. (GuildProfileEntry[])

• 401 Signed out.
• 403 PLUS_REQUIRED or not a member.
• 422 Validation failed or INVALID_UPLOAD.
• 503 PROFILES_UNAVAILABLE.

My profile settings

GET https://api.guild.xyz/me/profile

Everything the editor needs: fields, privacy, accounts, entitlement and limits. Refreshes the X handle first (best effort). Falls back to the legacy profile until the profile tables are applied.

Auth: your signed-in Guild session (x-guild-auth-token).

Returns 200: The ProfileSettings. (ProfileSettings)