API Reference

Build integrations with the GuildCraft API

Authentication

All API requests require Discord OAuth2 authentication

OAuth2 Flow

Authenticate users via Discord OAuth2. The access token is stored in an httpOnly cookie and automatically included in API requests.

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=identify%20guilds

Base URL

https://guildcraft.site/api

Endpoints

GET/api/discord/guilds

Get all guilds the authenticated user is in where the bot is present

Authentication: Required

Response:

{
  "guilds": [
    {
      "id": "1234567890",
      "name": "My Guild",
      "icon": "hash123",
      "permissions": [
        "admin",
        "officer"
      ]
    }
  ]
}

GET/api/discord/user

Get the currently authenticated Discord user

Authentication: Required

Response:

{
  "id": "1234567890",
  "username": "username",
  "discriminator": "0001",
  "avatar": "hash123"
}

GET/api/guilds/:id/professions

Get all professions configured for a specific guild

Authentication: Required

Response:

{
  "professions": [
    {
      "id": "prof123",
      "name": "Alchemy",
      "description": "Potion crafting",
      "crafters": [
        "user1",
        "user2"
      ]
    }
  ]
}

POST/api/guilds/:id/requests

Create a new crafting request

Authentication: Required

Request Body:

{
  "profession": "Alchemy",
  "item": "Greater Healing Potion",
  "quantity": 5,
  "notes": "Urgent"
}

Response:

{
  "requestId": "req123",
  "status": "pending",
  "createdAt": "2025-11-21T12:00:00Z"
}

Rate Limiting

API requests are rate limited to prevent abuse:

60 requests per minute for authenticated users
10 requests per minute for unauthenticated users

Rate limit information is included in response headers.