{ "openapi": "3.1.0", "info": { "title": "Diyor Bot API", "version": "1.0.0", "description": "REST API for Diyor bots. Guide: https://diyor.chat/gelistirici/belgeler. Real-time events come over the gateway WebSocket (wss://app.diyor.chat/gateway?intents=...), documented in the guide.", "license": { "name": "MIT", "identifier": "MIT" } }, "servers": [ { "url": "https://app.diyor.chat/api/v1" } ], "security": [ { "BotToken": [] } ], "tags": [ { "name": "Users", "description": "The bot itself, or the user who signed in with OAuth2." }, { "name": "Servers", "description": "Servers the bot was installed in: channels and members." }, { "name": "Messages", "description": "Read, send, edit and delete messages; reactions; direct messages." }, { "name": "Commands", "description": "Slash commands of the application." }, { "name": "Interactions", "description": "Answering slash commands and button presses." }, { "name": "Webhooks", "description": "Incoming webhooks: post into a channel without a bot." }, { "name": "OAuth2", "description": "Sign in with Diyor (authorization code flow with PKCE)." }, { "name": "Directory", "description": "The public app directory." } ], "webhooks": { "interaction": { "post": { "operationId": "interactionWebhook", "summary": "Interaction sent to your interactions endpoint URL", "description": "Set in the developer portal. Verify X-Diyor-Signature (sha256=HMAC-SHA256(signing secret, \".\")) and reject timestamps older than 5 minutes. Answer within 3 seconds; the response body is the callback. The portal's Test button sends {\"type\":\"ping\"} and expects {\"type\":\"pong\"}.", "parameters": [ { "name": "X-Diyor-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Diyor-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Interaction" }, { "type": "object", "title": "Ping", "properties": { "type": { "const": "ping" }, "application_id": { "type": "string" } } } ] } } } }, "responses": { "200": { "description": "The callback", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InteractionResponse" }, { "type": "object", "title": "Pong", "properties": { "type": { "const": "pong" } } } ] } } } } } } } }, "paths": { "/users/@me": { "get": { "tags": [ "Users" ], "operationId": "getCurrentUser", "summary": "The bot user, or the signed-in user with an OAuth2 token", "security": [ { "BotToken": [] }, { "OAuth2": [ "identify" ] } ], "description": "With \"Authorization: Bot \": the bot. With \"Authorization: Bearer \": the user who signed in (email with the email scope).", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/User" }, { "$ref": "#/components/schemas/OAuthUser" } ] } } } }, "401": { "description": "Error (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/@me/servers": { "get": { "tags": [ "Users" ], "operationId": "listServers", "summary": "Servers the bot is in, or the signed-in user's servers (servers scope)", "security": [ { "BotToken": [] }, { "OAuth2": [ "servers" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ServerSummary" }, { "$ref": "#/components/schemas/OAuthServer" } ] } } } } }, "401": { "description": "Error (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (missing_scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth2/token": { "post": { "tags": [ "OAuth2" ], "operationId": "oauthToken", "summary": "Exchange an authorization code or a refresh token", "security": [ { "ClientBasic": [] }, {} ], "description": "RFC 6749. Client credentials in the Basic header or the body. Apps that created a client secret (confidential clients) must always send it; apps without one (public clients) must use PKCE (S256). Codes and refresh tokens are single use.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "description": "invalid_request, invalid_grant, unsupported_grant_type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } }, "401": { "description": "invalid_client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } } } } }, "/oauth2/revoke": { "post": { "tags": [ "OAuth2" ], "operationId": "oauthRevoke", "summary": "Revoke a token (RFC 7009)", "security": [ { "ClientBasic": [] }, {} ], "description": "Revoking a refresh token revokes every token of that grant. Unknown tokens also return 200.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "token", "client_id" ], "properties": { "token": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "invalid_client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } } } } }, "/directory": { "get": { "tags": [ "Directory" ], "operationId": "listDirectory", "summary": "Apps listed in the public directory", "security": [], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 60 } }, { "name": "category", "in": "query", "schema": { "$ref": "#/components/schemas/Category" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "applications": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryApp" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } } } } } }, "/directory/{id}": { "get": { "tags": [ "Directory" ], "operationId": "getDirectoryApp", "summary": "A listed app", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Application id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryAppDetails" } } } }, "404": { "description": "Error (unknown_application)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/servers/{server}/channels": { "get": { "tags": [ "Servers" ], "operationId": "listChannels", "summary": "Channels and categories the bot can see", "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id (12 characters)", "schema": { "type": "string", "pattern": "^[a-z0-9]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } } } } }, "401": { "description": "Error (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (unknown_server, unknown_channel, unknown_message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/servers/{server}/members": { "get": { "tags": [ "Servers" ], "operationId": "listMembers", "summary": "Members of the server", "description": "Needs \"Server members\" access (developer portal).", "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id (12 characters)", "schema": { "type": "string", "pattern": "^[a-z0-9]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } } } }, "401": { "description": "Error (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (missing_access)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (unknown_server, unknown_channel, unknown_message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/servers/{server}/channels/{channel}/messages": { "get": { "tags": [ "Messages" ], "operationId": "listMessages", "summary": "Message history (newest first)", "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id (12 characters)", "schema": { "type": "string", "pattern": "^[a-z0-9]{12}$" } }, { "name": "channel", "in": "path", "required": true, "description": "Text channel id", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "Messages older than this message id", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } }, "401": { "description": "Error (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (unknown_server, unknown_channel, unknown_message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Messages" ], "operationId": "createMessage", "summary": "Send a message", "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id (12 characters)", "schema": { "type": "string", "pattern": "^[a-z0-9]{12}$" } }, { "name": "channel", "in": "path", "required": true, "description": "Text channel id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageCreate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Error (invalid_json, empty_message, content_too_long, invalid_components, invalid_embeds)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (missing_permission)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (unknown_server, unknown_channel, unknown_message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/servers/{server}/channels/{channel}/messages/{message}": { "patch": { "tags": [ "Messages" ], "operationId": "editMessage", "summary": "Edit the bot's own message", "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id (12 characters)", "schema": { "type": "string", "pattern": "^[a-z0-9]{12}$" } }, { "name": "channel", "in": "path", "required": true, "description": "Text channel id", "schema": { "type": "string" } }, { "name": "message", "in": "path", "required": true, "description": "Message id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEdit" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Error (invalid_json, empty_message, content_too_long, invalid_components, invalid_embeds)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (cannot_edit, missing_permission)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (unknown_server, unknown_channel, unknown_message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Messages" ], "operationId": "deleteMessage", "summary": "Delete a message", "description": "Own messages, or other people's with manage_messages.", "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id (12 characters)", "schema": { "type": "string", "pattern": "^[a-z0-9]{12}$" } }, { "name": "channel", "in": "path", "required": true, "description": "Text channel id", "schema": { "type": "string" } }, { "name": "message", "in": "path", "required": true, "description": "Message id", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Error (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (missing_permission)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (unknown_server, unknown_channel, unknown_message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/servers/{server}/channels/{channel}/messages/{message}/reactions/{emoji}": { "put": { "tags": [ "Messages" ], "operationId": "addReaction", "summary": "Add a reaction", "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id (12 characters)", "schema": { "type": "string", "pattern": "^[a-z0-9]{12}$" } }, { "name": "channel", "in": "path", "required": true, "description": "Text channel id", "schema": { "type": "string" } }, { "name": "message", "in": "path", "required": true, "description": "Message id", "schema": { "type": "string" } }, { "name": "emoji", "in": "path", "required": true, "description": "URL-encoded emoji, e.g. %F0%9F%91%8D", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Error (invalid_emoji)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (missing_permission)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (unknown_server, unknown_channel, unknown_message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Messages" ], "operationId": "removeReaction", "summary": "Remove the bot's reaction", "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id (12 characters)", "schema": { "type": "string", "pattern": "^[a-z0-9]{12}$" } }, { "name": "channel", "in": "path", "required": true, "description": "Text channel id", "schema": { "type": "string" } }, { "name": "message", "in": "path", "required": true, "description": "Message id", "schema": { "type": "string" } }, { "name": "emoji", "in": "path", "required": true, "description": "URL-encoded emoji, e.g. %F0%9F%91%8D", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Error (invalid_emoji)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (missing_permission)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (unknown_server, unknown_channel, unknown_message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/servers/{server}/users/{user}/messages": { "post": { "tags": [ "Messages" ], "operationId": "createDirectMessage", "summary": "Direct message to a member of the server", "description": "Needs the send_direct_messages permission. People can turn off direct messages from bots.", "parameters": [ { "name": "server", "in": "path", "required": true, "description": "Server id (12 characters)", "schema": { "type": "string", "pattern": "^[a-z0-9]{12}$" } }, { "name": "user", "in": "path", "required": true, "description": "User id (UUID)", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectMessageCreate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Message" }, { "type": "object", "properties": { "dm_user_id": { "type": "string" } } } ] } } } }, "400": { "description": "Error (invalid_json, empty_message, content_too_long, invalid_components, invalid_embeds)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (missing_permission, dm_closed, cannot_message_user)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (unknown_user)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/applications/@me/commands": { "get": { "tags": [ "Commands" ], "operationId": "listCommands", "summary": "The app's slash commands", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Command" } } } } }, "401": { "description": "Error (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Commands" ], "operationId": "setCommands", "summary": "Replace all slash commands", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/Command" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Command" } } } } }, "400": { "description": "Error (invalid_commands)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/interactions/{id}/{token}/callback": { "post": { "tags": [ "Interactions" ], "operationId": "interactionCallback", "summary": "Answer an interaction", "security": [], "description": "The first answer must come within 3 seconds; the token is valid for 15 minutes. More \"message\" callbacks after the first are follow-ups.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Interaction id", "schema": { "type": "string" } }, { "name": "token", "in": "path", "required": true, "description": "Interaction token", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionResponse" } } } }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Error (invalid_type, empty_message, already_acknowledged, interaction_timeout, invalid_components, invalid_embeds)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (missing_permission)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (unknown_interaction, interaction_expired, unknown_message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/{token}": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhook", "summary": "The webhook itself (Discord compatible)", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id", "schema": { "type": "string" } }, { "name": "token", "in": "path", "required": true, "description": "Webhook token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "integer", "const": 1 }, "name": { "type": "string" }, "avatar_url": { "type": [ "string", "null" ] }, "channel_id": { "type": "string" }, "guild_id": { "type": "string", "description": "Server id" }, "token": { "type": "string" } } } } } }, "404": { "description": "Error (unknown_webhook)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhooks" ], "operationId": "executeWebhook", "summary": "Post a message through an incoming webhook", "security": [], "description": "Discord compatible: the same URL also works under /api/webhooks/... and /api/v10/webhooks/.... Slack format ({\"text\": \"...\"}) and form data (payload=) are accepted too. Files: send multipart/form-data with payload_json and files[0]..files[9] (also file, file1...); at most 10 files, the whole request up to 100 MB. The size of each file, the daily upload quota and how long files are kept follow the server owner's plan (25 MB / 250 MB / 1 GB per file). Embed images pointing to attachment://... are not supported and are dropped. 30 messages per minute per webhook; a JSON body up to 1 MB.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id", "schema": { "type": "string" } }, { "name": "token", "in": "path", "required": true, "description": "Webhook token", "schema": { "type": "string" } }, { "name": "wait", "in": "query", "required": false, "description": "true: respond 200 with the created message instead of 204", "schema": { "type": "boolean" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookMessage" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "payload_json": { "type": "string", "description": "WebhookMessage as JSON" }, "files[0]": { "type": "string", "format": "binary", "description": "files[0] .. files[9]" } } } } } }, "responses": { "200": { "description": "With ?wait=true: the created message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "204": { "description": "No Content" }, "400": { "description": "Error (invalid_json, invalid_form, empty_message, content_too_long, invalid_embeds, invalid_avatar_url, too_many_files)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (unknown_webhook, unknown_channel)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "411": { "description": "Error (length_required: a request with files needs Content-Length)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error (payload_too_large, file_too_large)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited or upload_quota_exceeded (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error (upload_failed: a file could not be stored, nothing was sent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "507": { "description": "Error (storage_full)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/{token}/messages/{message}": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookMessage", "summary": "A message this webhook sent", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id", "schema": { "type": "string" } }, { "name": "token", "in": "path", "required": true, "description": "Webhook token", "schema": { "type": "string" } }, { "name": "message", "in": "path", "required": true, "description": "Message id (only messages this webhook sent)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "404": { "description": "Error (unknown_webhook, unknown_message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Webhooks" ], "operationId": "editWebhookMessage", "summary": "Edit a message this webhook sent", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id", "schema": { "type": "string" } }, { "name": "token", "in": "path", "required": true, "description": "Webhook token", "schema": { "type": "string" } }, { "name": "message", "in": "path", "required": true, "description": "Message id (only messages this webhook sent)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 2000 }, "embeds": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/Embed" } } }, "description": "Fields left out stay as they are. Attachments cannot be changed." } } } }, "responses": { "200": { "description": "The message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Error (invalid_json, empty_message, content_too_long, invalid_embeds)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (unknown_webhook, unknown_message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhookMessage", "summary": "Delete a message this webhook sent (its files too)", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id", "schema": { "type": "string" } }, { "name": "token", "in": "path", "required": true, "description": "Webhook token", "schema": { "type": "string" } }, { "name": "message", "in": "path", "required": true, "description": "Message id (only messages this webhook sent)", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Error (unknown_webhook, unknown_message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/{token}/github": { "post": { "tags": [ "Webhooks" ], "operationId": "executeGithubWebhook", "summary": "GitHub webhook payload URL", "security": [], "description": "Use as the payload URL of a GitHub webhook (content type JSON). Events: push, pull_request, issues, issue_comment, pull_request_review, release, star, fork, workflow_run, ping.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id", "schema": { "type": "string" } }, { "name": "token", "in": "path", "required": true, "description": "Webhook token", "schema": { "type": "string" } }, { "name": "X-GitHub-Event", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Error (invalid_json)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (unknown_webhook)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "BotToken": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Bot " }, "ClientBasic": { "type": "http", "scheme": "basic", "description": "client_id:client_secret" }, "OAuth2": { "type": "oauth2", "description": "Sign in with Diyor. Access tokens can call /users/@me and /users/@me/servers.", "flows": { "authorizationCode": { "authorizationUrl": "https://diyor.chat/oauth2/authorize", "tokenUrl": "https://app.diyor.chat/api/v1/oauth2/token", "refreshUrl": "https://app.diyor.chat/api/v1/oauth2/token", "scopes": { "identify": "id, name and avatar (always included)", "email": "email address (not verified by Diyor)", "servers": "the servers the user is a member of" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "OAuthError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } }, "OAuthUser": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "bot": { "const": false }, "avatar_url": { "type": [ "string", "null" ] }, "email": { "type": "string", "description": "email scope" }, "email_verified": { "type": "boolean" } } }, "OAuthServer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "icon_url": { "type": [ "string", "null" ] }, "owner": { "type": "boolean" } } }, "TokenRequest": { "type": "object", "required": [ "grant_type", "client_id" ], "properties": { "grant_type": { "enum": [ "authorization_code", "refresh_token" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "code": { "type": "string" }, "redirect_uri": { "type": "string" }, "code_verifier": { "type": "string" }, "refresh_token": { "type": "string" } } }, "TokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "const": "Bearer" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "scope": { "type": "string" } } }, "Category": { "enum": [ "moderation", "fun", "utility", "games", "social", "productivity", "developer" ] }, "DirectoryApp": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "avatar_url": { "type": [ "string", "null" ] }, "category": { "oneOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "null" } ] }, "verified": { "type": "boolean" }, "server_count": { "type": "integer" }, "install_url": { "type": "string" } } }, "DirectoryAppDetails": { "allOf": [ { "$ref": "#/components/schemas/DirectoryApp" }, { "type": "object", "properties": { "long_description": { "type": "string" }, "sections": { "type": "array", "description": "Extra wiki sections written by the developer (plain text with light formatting: **bold**, `code`, [text](https://...), lines starting with \"- \").", "items": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" } } } }, "developer": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "privacy_policy_url": { "type": [ "string", "null" ] }, "terms_of_service_url": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "listed_at": { "type": [ "string", "null" ], "format": "date-time" }, "commands": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } } ] }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "bot": { "type": "boolean" }, "avatar_url": { "type": [ "string", "null" ], "description": "Public profile picture URL; null for an emoji avatar or none" } } }, "ServerSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "Channel": { "type": "object", "required": [ "id", "type", "name", "position" ], "properties": { "id": { "type": "string" }, "type": { "enum": [ "text", "voice", "category" ] }, "name": { "type": "string" }, "category_id": { "type": [ "string", "null" ] }, "position": { "type": "integer" }, "can_send": { "type": "boolean", "description": "text channels" }, "can_connect": { "type": "boolean", "description": "voice channels" }, "user_limit": { "type": "integer", "description": "voice channels; 0 = no limit" } } }, "Member": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "account name" }, "nick": { "type": [ "string", "null" ], "description": "nickname in this server; null when not set" }, "bot": { "type": "boolean" }, "avatar_url": { "type": [ "string", "null" ] }, "roles": { "type": "array", "items": { "type": "string" } }, "owner": { "type": "boolean" }, "joined_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Author": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ], "description": "Public profile picture URL; null for an emoji avatar or none" }, "webhook": { "type": "boolean" }, "system": { "type": "boolean" } } }, "Message": { "type": "object", "properties": { "id": { "type": "string" }, "server_id": { "type": "string" }, "channel_id": { "type": [ "string", "null" ] }, "author": { "$ref": "#/components/schemas/Author" }, "content": { "type": "string", "description": "Empty without Message content access unless the bot is mentioned or wrote it" }, "timestamp": { "type": "string", "format": "date-time" }, "edited_timestamp": { "type": [ "string", "null" ], "format": "date-time" }, "reply_to": { "type": [ "string", "null" ] }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "size": { "type": "integer" } } } }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "emoji": { "type": "string" }, "count": { "type": "integer" } } } }, "pinned": { "type": "boolean" }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/Button" } }, "embeds": { "type": "array", "items": { "$ref": "#/components/schemas/Embed" } }, "interaction": { "type": [ "object", "null" ], "properties": { "user_name": { "type": "string" }, "command": { "type": "string" } } } } }, "MessageCreate": { "type": "object", "description": "At least one of content, embeds or components.", "properties": { "content": { "type": "string", "maxLength": 2000 }, "reply_to": { "type": "string", "description": "Message id in the same channel" }, "embeds": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/Embed" } }, "components": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Button" } } } }, "MessageEdit": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 2000 }, "embeds": { "type": [ "array", "null" ], "maxItems": 3, "items": { "$ref": "#/components/schemas/Embed" } }, "components": { "type": [ "array", "null" ], "maxItems": 5, "items": { "$ref": "#/components/schemas/Button" } } } }, "DirectMessageCreate": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 2000 }, "embeds": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/Embed" } }, "components": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Button" } } } }, "Embed": { "type": "object", "description": "All text of the embeds in a message: at most 6000 characters.", "properties": { "title": { "type": "string", "maxLength": 256 }, "description": { "type": "string", "maxLength": 4000 }, "url": { "type": "string", "format": "uri", "description": "https only" }, "color": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 16777215 }, { "type": "string", "pattern": "^#?[0-9a-fA-F]{6}$" } ] }, "fields": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "maxLength": 256 }, "value": { "type": "string", "maxLength": 1024 }, "inline": { "type": "boolean" } } } }, "footer": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 2048 } } }, "image": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "https only" } } } } }, "Button": { "type": "object", "required": [ "type", "label" ], "properties": { "type": { "const": "button" }, "label": { "type": "string", "maxLength": 80 }, "style": { "enum": [ "primary", "secondary", "success", "danger", "link" ], "default": "secondary" }, "custom_id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Required unless style is link" }, "url": { "type": "string", "format": "uri", "description": "https; only for style link" }, "disabled": { "type": "boolean" } } }, "CommandOption": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "pattern": "^[\\p{Ll}\\p{N}_-]{1,32}$" }, "description": { "type": "string", "maxLength": 100 }, "type": { "enum": [ "string", "integer", "number", "boolean", "user" ] }, "required": { "type": "boolean", "description": "Required options must come first" } } }, "Command": { "type": "object", "required": [ "name", "description" ], "properties": { "name": { "type": "string", "pattern": "^[\\p{Ll}\\p{N}_-]{1,32}$" }, "description": { "type": "string", "maxLength": 100 }, "options": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/CommandOption" } } } }, "Interaction": { "type": "object", "description": "Delivered as the INTERACTION_CREATE gateway event or POSTed to the app's interactions endpoint (signed: X-Diyor-Timestamp, X-Diyor-Signature: sha256=HMAC-SHA256(secret, \".\")).", "properties": { "id": { "type": "string" }, "token": { "type": "string" }, "type": { "enum": [ "command", "button" ] }, "application_id": { "type": "string" }, "server_id": { "type": "string" }, "channel_id": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatar_url": { "type": [ "string", "null" ] } } }, "data": { "oneOf": [ { "type": "object", "title": "Command", "properties": { "name": { "type": "string" }, "options": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean" ] } } } }, { "type": "object", "title": "Button", "properties": { "custom_id": { "type": "string" }, "message_id": { "type": "string" } } } ] } } }, "InteractionResponse": { "type": "object", "required": [ "type" ], "properties": { "type": { "enum": [ "message", "defer", "update" ], "description": "message: send a message; defer: \"thinking…\", answer within 15 minutes; update: edit the message whose button was pressed" }, "data": { "allOf": [ { "$ref": "#/components/schemas/MessageCreate" }, { "type": "object", "properties": { "ephemeral": { "type": "boolean", "description": "Only the user sees it (not stored)" } } } ] } } }, "WebhookMessage": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 2000 }, "username": { "type": "string", "description": "Overrides the webhook name for this message" }, "avatar_url": { "type": "string", "maxLength": 500, "description": "https URL of a picture for this message (overrides the webhook avatar)" }, "embeds": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/Embed" } }, "text": { "type": "string", "description": "Slack compatible alias of content" } } } } } }