{ "openapi": "3.1.0", "info": { "title": "ServaDiscord API", "description": "API for ServaDiscord \u2014 a visual Discord bot builder Every /api/v1 response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy headers; exceeding the limit returns 429 with Retry-After.", "version": "1.0.0", "contact": { "name": "ServaDiscord", "url": "https://www.servadiscord.com" } }, "servers": [ { "url": "https://www.servadiscord.com", "description": "Production" } ], "security": [ { "BetterAuthSession": [] } ], "paths": { "/api/v1/billing/subscription": { "get": { "summary": "Get subscription status", "description": "Returns the current subscription status for the authenticated user", "operationId": "getSubscription", "tags": [ "Billing" ], "responses": { "200": { "description": "Subscription status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "isPremium": { "type": "boolean", "description": "Whether the user has an active or trialing subscription" } }, "required": [ "isPremium" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "401": { "description": "User is not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/affiliate/claim": { "post": { "summary": "Claim referral bonus", "description": "Claims a referral bonus using a referral code from cookies", "operationId": "claimReferral", "tags": [ "Affiliate" ], "responses": { "200": { "description": "Referral claim processed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "claimed", "invalid", "already_claimed" ] } }, "required": [ "status" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/discord/bot/token": { "post": { "summary": "Validate and save Discord bot token", "description": "Validates a Discord bot token and saves it for bot operations", "operationId": "saveBotToken", "tags": [ "Discord", "Bot" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "guildId": { "type": "string", "description": "Discord guild ID" }, "token": { "type": "string", "description": "Discord bot token" } }, "required": [ "guildId", "token" ] } } } }, "responses": { "200": { "description": "Token validated and saved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "description": "Bot user ID" }, "name": { "type": "string", "description": "Bot username" }, "avatar": { "type": [ "string", "null" ], "description": "Bot avatar URL" }, "description": { "type": "string", "description": "Bot application description" } }, "required": [ "success", "id", "name", "avatar", "description" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "400": { "description": "Invalid token or missing fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "User is not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/discord/guild/data": { "post": { "summary": "Get Discord guild data", "description": "Retrieves guild roles and channels for bot permission planning", "operationId": "getGuildData", "tags": [ "Discord", "Guild" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "guildId": { "type": "string" } }, "required": [ "guildId" ] } } } }, "responses": { "200": { "description": "Guild data retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "description": "Guild roles" }, "channels": { "type": "array", "description": "Guild channels" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "400": { "description": "Missing guildId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Bot missing permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/discord/guild/admin": { "get": { "summary": "Check guild admin status", "description": "Checks if the authenticated user is an admin of a guild", "operationId": "isGuildAdmin", "tags": [ "Discord", "Guild" ], "parameters": [ { "name": "guildId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Admin status retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "isAdmin": { "type": "boolean" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/discord/invite/{code}": { "get": { "summary": "Resolve Discord invite", "description": "Gets info about a Discord invite code", "operationId": "getInviteInfo", "tags": [ "Discord" ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invite information retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "guildId": { "type": "string" }, "guildName": { "type": "string" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "400": { "description": "Invalid invite code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Invite not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Discord API temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/discord/sync": { "post": { "summary": "Sync Discord guild configuration", "description": "Plan or apply role/channel changes to a Discord guild", "operationId": "syncGuild", "tags": [ "Discord", "Sync" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "guildId": { "type": "string" }, "action": { "type": "string", "enum": [ "roles", "channels" ] }, "mode": { "type": "string", "enum": [ "plan", "apply" ], "default": "plan" }, "allowDeletes": { "type": "boolean", "default": false }, "data": { "type": [ "array", "object" ] } }, "required": [ "guildId", "action" ] } } } }, "responses": { "200": { "description": "Sync plan or result", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "object" }, "result": { "type": "object" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing permissions or invalid token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/discord/webhook": { "post": { "summary": "Process webhook", "description": "Processes a webhook request from Discord or other services", "operationId": "processWebhook", "tags": [ "Discord" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Webhook URL" }, "payload": { "type": "object", "description": "Webhook payload" } } } } } }, "responses": { "200": { "description": "Webhook processed successfully", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "400": { "description": "Invalid webhook URL or payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/auth/{...all}": { "get": { "summary": "Better Auth endpoints", "description": "Auth endpoints for login, signup, and OAuth flows. Proxies to better-auth on Convex.", "operationId": "authProxy", "tags": [ "Auth" ], "parameters": [ { "name": "...all", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Auth response" }, "302": { "description": "Redirect" } } }, "post": { "summary": "Better Auth endpoints", "operationId": "authProxyPost", "tags": [ "Auth" ], "responses": { "200": { "description": "Auth response" }, "302": { "description": "Redirect" } } } } }, "components": { "securitySchemes": { "BetterAuthSession": { "type": "apiKey", "name": "Cookie", "in": "header", "description": "Session cookie from better-auth" }, "OAuth2": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://www.servadiscord.com/api/auth/signin/discord", "scopes": { "identify": "Access user ID and username", "email": "Access user email address", "guilds": "Access list of user's Discord guilds" } } } } }, "schemas": { "Error": { "type": "object", "description": "Error body returned by every 4xx/5xx JSON response of the v1 API. `error` is the human-readable text (kept for backward compatibility), `code` is a stable machine-readable identifier, and `message` repeats the text for clients that expect that field. Routes may add context fields such as `retryAfter` or `reason`.", "properties": { "error": { "type": "string", "description": "Human-readable error text" }, "code": { "type": "string", "description": "Stable machine-readable code, e.g. unauthorized, bad_request, forbidden, not_found, rate_limited, internal_error, bad_gateway, or a route-specific snake_case code such as invalid_code", "examples": [ "unauthorized" ] }, "message": { "type": "string", "description": "Human-readable error text" } }, "required": [ "error", "code", "message" ], "additionalProperties": true } }, "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (60).", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying (on 429).", "schema": { "type": "integer" } } }, "responses": { "RateLimited": { "description": "Rate limit exceeded (60 requests per 60 seconds per client). Wait Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "tags": [ { "name": "Auth", "description": "Authentication endpoints" }, { "name": "Billing", "description": "Subscription and billing endpoints" }, { "name": "Affiliate", "description": "Referral and affiliate endpoints" }, { "name": "Discord", "description": "Discord integration endpoints" }, { "name": "Bot", "description": "Bot management endpoints" }, { "name": "Guild", "description": "Guild/server endpoints" }, { "name": "Sync", "description": "Guild sync and configuration" }, { "name": "Tools", "description": "Utility endpoints" } ] }