Guilds

Guilds are the top-level organizational unit in Zlikord, similar to Discord servers.

List Guilds

GET /api/v1/guilds

Returns all guilds the authenticated user is a member of.

Headers: Authorization: Bearer <token>

Response 200 OK:

[
  {
    "id": 1,
    "name": "My Guild",
    "owner_id": 1
  }
]

Create Guild

POST /api/v1/guilds

Create a new guild. The authenticated user becomes the owner.

Headers: Authorization: Bearer <token>

Request body:

{
  "name": "New Guild"
}

Response 201 Created:

{
  "id": 2,
  "name": "New Guild",
  "owner_id": 1
}

Get Guild Channels

GET /api/v1/guilds/:id/channels

List all channels in a guild.

Headers: Authorization: Bearer <token>

Response 200 OK:

[
  {
    "id": 1,
    "guild_id": 1,
    "name": "general",
    "kind": "text",
    "category_id": null
  },
  {
    "id": 2,
    "guild_id": 1,
    "name": "voice-chat",
    "kind": "voice",
    "category_id": 1
  }
]

Channel kind is either "text" or "voice".

Create Channel

POST /api/v1/guilds/:id/channels

Create a new channel in a guild.

Headers: Authorization: Bearer <token>

Request body:

{
  "name": "new-channel",
  "kind": "text",
  "category_id": 1
}

Response 201 Created: Returns the created channel object.

Get Guild Categories

GET /api/v1/guilds/:id/categories

List all categories in a guild. Categories group channels.

Headers: Authorization: Bearer <token>

Response 200 OK:

[
  {
    "id": 1,
    "guild_id": 1,
    "name": "General"
  }
]

Create Category

POST /api/v1/guilds/:id/categories

Headers: Authorization: Bearer <token>

Request body:

{
  "name": "Voice Channels",
  "position": 2
}

Response 201 Created: Returns the created category object.

Update Category

PATCH /api/v1/guilds/:id/categories/:category_id

Headers: Authorization: Bearer <token>

Request body (all fields optional):

{
  "name": "Renamed Category",
  "position": 1
}

Response 200 OK: Returns the updated category object.

Search Guild Messages

GET /api/v1/guilds/:id/search?q=keyword

Search messages across all channels in a guild.

Headers: Authorization: Bearer <token>

Query parameters:

Parameter	Description
q	Search query (required)
limit	Max results, default 20, max 100 (optional)

Response 200 OK: Returns an array of matching messages.

Get Guild Members

GET /api/v1/guilds/:id/members

List all members of a guild. Includes online presence status.

Headers: Authorization: Bearer <token>

Response 200 OK:

[
  {
    "id": 1,
    "username": "alice",
    "avatar_url": "https://cdn.example.com/avatar.png",
    "online": true
  }
]

Add Guild Member

POST /api/v1/guilds/:id/members

Add a user to the guild.

Headers: Authorization: Bearer <token>

Request body:

{
  "user_id": 3
}

Response 204 No Content