{"id":28363893,"url":"https://github.com/paillat-dev/pycord-rest","last_synced_at":"2026-03-10T11:04:48.820Z","repository":{"id":281205446,"uuid":"944535170","full_name":"Paillat-dev/pycord-rest","owner":"Paillat-dev","description":"A lightweight wrapper for Discord's HTTP interactions and webhook events using py-cord and FastAPI.","archived":false,"fork":false,"pushed_at":"2026-02-09T20:23:33.000Z","size":382,"stargazers_count":2,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-09T23:55:58.480Z","etag":null,"topics":["discord","discord-api","discord-api-wrapper","discord-bot","discord-framework","py-cord","pycord"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Paillat-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-07T14:16:36.000Z","updated_at":"2025-12-31T17:34:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"cdf0c886-1315-4067-a669-8469cee0ea31","html_url":"https://github.com/Paillat-dev/pycord-rest","commit_stats":null,"previous_names":["paillat-dev/pycord-rest"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/Paillat-dev/pycord-rest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paillat-dev%2Fpycord-rest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paillat-dev%2Fpycord-rest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paillat-dev%2Fpycord-rest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paillat-dev%2Fpycord-rest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Paillat-dev","download_url":"https://codeload.github.com/Paillat-dev/pycord-rest/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paillat-dev%2Fpycord-rest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30331650,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T05:25:20.737Z","status":"ssl_error","status_checked_at":"2026-03-10T05:25:17.430Z","response_time":106,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discord","discord-api","discord-api-wrapper","discord-bot","discord-framework","py-cord","pycord"],"created_at":"2025-05-28T19:39:58.638Z","updated_at":"2026-03-10T11:04:48.809Z","avatar_url":"https://github.com/Paillat-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003ePycord REST\u003c/h1\u003e\n\n\u003c!-- badges --\u003e\n\n[![PyPI - Version](https://img.shields.io/pypi/v/pycord-rest-bot)](https://pypi.org/project/pycord-rest-bot/)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pycord-rest-bot)](https://pypi.org/project/pycord-rest-bot/)\n[![PyPI - Types](https://img.shields.io/pypi/types/pycord-rest-bot)](https://pypi.org/project/pycord-rest-bot/)\n[![PyPI - License](https://img.shields.io/pypi/l/pycord-rest-bot)](https://pypi.org/project/pycord-rest-bot/)\n[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Paillat-dev/pycord-rest/CI.yaml)](https://github.com/Paillat-dev/pycord-rest/actions/workflows/CI.yaml)\n[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Paillat-dev/pycord-rest/main.svg)](https://results.pre-commit.ci/latest/github/Paillat-dev/pycord-rest/main)\n\n\u003c!-- end badges --\u003e\n\n\u003c!-- short description --\u003e\n\nA lightweight wrapper for Discord's HTTP interactions and webhook events using py-cord\nand FastAPI.\n\n\u003c!-- end short description --\u003e\n\n\u003c/div\u003e\n\n\u003c!-- toc --\u003e\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Core Concepts](#core-concepts)\n  - [How It Works](#how-it-works)\n  - [Discord Application Setup](#discord-application-setup)\n- [Features](#features)\n  - [Interaction Handling](#interaction-handling)\n  - [Webhook Events](#webhook-events)\n  - [Type Safety](#type-safety)\n- [Usage Examples](#usage-examples)\n  - [Basic Commands](#basic-commands)\n  - [Event Handling](#event-handling)\n  - [Custom Routes](#custom-routes)\n- [Configuration](#configuration)\n- [Limitations](#limitations)\n- [Getting Help](#getting-help)\n- [Development](#development)\n  - [Local Testing](#local-testing)\n  - [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\nPycord REST enables you to build Discord applications that respond to:\n\n- **Interactions** via HTTP endpoints (slash commands, components, modals)\n- **Webhook events** such as application authorization and entitlements\n\nBuilt on:\n\n- **FastAPI** - For handling HTTP requests\n- **py-cord** - For Discord command builders and interaction handling\n- **uvicorn** - ASGI server implementation\n\n## Installation\n\n```bash\npip install pycord-rest-bot\n```\n\n\u003c!-- quick-start --\u003e\n\n## Quick Start\n\n```python\nfrom pycord_rest import App\nimport discord\n\napp = App()\n\n@app.slash_command(name=\"ping\", description=\"Responds with pong!\")\nasync def ping(ctx):\n    await ctx.respond(\"Pong!\")\n\nif __name__ == \"__main__\":\n    app.run(\n        token=\"YOUR_BOT_TOKEN\",\n        public_key=\"YOUR_PUBLIC_KEY\",  # From Discord Developer Portal\n        uvicorn_options={\n            \"host\": \"0.0.0.0\",\n            \"port\": 8000\n        }\n    )\n```\n\n## Core Concepts\n\n### How It Works\n\nPycord REST creates an HTTP server that:\n\n1. Listens for Discord interaction requests and webhook events\n2. Verifies request signatures using your application's public key\n3. Routes events to appropriate handlers\n4. Returns responses back to Discord\n\nUnlike traditional WebSocket-based Discord bots, HTTP-based applications:\n\n- Only wake up when receiving interactions or webhook events\n- Don't maintain a persistent connection to Discord's gateway\n- Don't receive most real-time Discord events\n\n### Discord Application Setup\n\n1. Create an application on the\n   [Discord Developer Portal](https://discord.com/developers/applications)\n2. Copy your public key to verify signatures\n3. Run the Pycord REST app\n4. Configure the endpoints:\n\n- **Interactions Endpoint URL** - For slash commands and component interactions\n  (`https://example.com`)\n- **Webhook URL** - For receiving application events (e.g.,\n  `https://example.com/webhook`)\n\n\u003c!-- prettier-ignore --\u003e\n\u003e [!IMPORTANT]\n\u003e Don't forget to run your FastAPI server **before** setting up the application on Discord, or else Discord won't be able to verify the endpoints.\n\n## Features\n\n### Interaction Handling\n\nRespond to Discord interactions such as:\n\n- **Slash Commands** - Create and respond to application commands\n- **UI Components** - Buttons, select menus, and other interactive elements\n- **Modal Forms** - Pop-up forms for gathering user input\n- **Autocomplete** - Dynamic option suggestions as users type\n\n### Webhook Events\n\nHandle Discord webhook events such as:\n\n- **Application authorization** - When your app is added to a guild or authorized by a\n  user\n- **Entitlement creation** - When a user subscribes to your app's premium features\n\n### Type Safety\n\nPycord REST is fully type-annotated and type-safe. It uses `basedpyright` for type\nchecking.\n\n\u003c!-- prettier-ignore --\u003e\n\u003e [!NOTE]\n\u003e While Pycord REST itself is fully typed, the underlying py-cord library has limited type annotations, which may affect type checking in some areas.\n\n## Usage Examples\n\n\u003c!-- prettier-ignore --\u003e\n\u003e [!TIP]\n\u003e For complete examples, check out the [examples directory](/examples).\n\n### Basic Commands\n\nCommands use the familiar py-cord syntax:\n\n```python\n@app.slash_command(name=\"hello\", description=\"Say hello\")\nasync def hello(ctx, user: discord.Member = None):\n    user = user or ctx.author\n    await ctx.respond(f\"Hello {user.mention}!\")\n\n@app.slash_command()\nasync def button(ctx):\n    view = discord.ui.View()\n    view.add_item(discord.ui.Button(label=\"Click me!\", custom_id=\"my_button\"))\n    await ctx.respond(\"Press the button!\", view=view)\n```\n\n### Event Handling\n\nThe possible events are:\n\n- `on_application_authorized` - When your app is added to a guild or authorized by a\n  user\n- `on_entitlement_create` - When a user subscribes to your app's premium features\n\n\u003c!-- prettier-ignore --\u003e\n\u003e [!NOTE]\n\u003e For application installation events, use `on_application_authorized` instead of `on_guild_join`.\n\n```python\n@app.listen(\"on_application_authorized\")\nasync def on_application_authorized(event: ApplicationAuthorizedEvent):\n    # Triggers when app is added to a guild OR when a user authorizes your app\n    print(f\"Authorization received: Guild={event.guild}, User={event.user}\")\n```\n\n### Custom Routes\n\nAdd your own FastAPI routes:\n\n```python\nfrom fastapi import Request\n\n@app.router.get(\"/custom\")\nasync def custom_endpoint(request: Request):\n    return {\"message\": \"This is a custom endpoint\"}\n```\n\n## Configuration\n\n```python\napp.run(\n    token=\"YOUR_BOT_TOKEN\",\n    public_key=\"YOUR_PUBLIC_KEY\",\n    uvicorn_options={\n        \"host\": \"0.0.0.0\",  # Listen on all network interfaces\n        \"port\": 8000,        # Port to listen on\n        \"log_level\": \"info\", # Uvicorn logging level\n    },\n    health=True  # Enable /health endpoint for monitoring\n)\n```\n\n### Integration Options\n\n1. **Stand-alone HTTP Interaction Bot** - Commands and components only\n2. **Webhook Event Handler Only** - Process application events alongside a separate\n   gateway bot\n3. **Full HTTP Application** - Handle both interactions and webhook events\n\n## Limitations\n\nSince Pycord REST doesn't use Discord's WebSocket gateway:\n\n- **No Cache** - No local storage of guilds, channels, or users\n- **Limited API Methods** - Functions that rely on cache won't work:\n  - `app.get_channel()`, `app.get_guild()`, `app.get_user()`\n  - Presence updates\n  - Voice support\n  - Member tracking\n- **Limited Events** - Only interaction-based and webhook events work\n\n## Getting Help\n\nIf you encounter issues or have questions about pycord-rest:\n\n- **GitHub Issues**:\n  [Submit a bug report or feature request](https://github.com/Paillat-dev/pycord-rest/issues)\n- **Discord Support**:\n  - For py-cord related questions: Join the\n    [Pycord Official Server](https://discord.gg/pycord)\n  - For pycord-rest specific help: Join the\n    [Pycord Official Server](https://discord.gg/pycord) and mention `@paillat`\n\n\u003c!-- prettier-ignore --\u003e\n\u003e [!TIP]\n\u003e Before asking for help, check if your question is already answered in the [examples directory](/examples) or existing GitHub issues.\n\n## Development\n\n### Local Testing\n\nUse tunneling tools to expose your local development server:\n\n- **ngrok**:\n\n  ```bash\n  # Install ngrok\n  npm install -g ngrok\n\n  # Expose your local server\n  ngrok http 8000\n  ```\n\n- **Cloudflare Tunnel** or **localtunnel** - Alternative tunneling options\n\nThese tools provide temporary URLs for testing without deploying to production.\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run linter, formatter and type checker: `ruff check .`,`ruff format .`,\n   `basedpyright .`\n5. Submit a pull request\n\n**Development Tools**:\n\n- **uv**: For dependency management\n- **Ruff**: For linting and formatting\n- **HashiCorp Copywrite**: For managing license headers\n- **basedpyright**: For type checking\n\n\u003c!-- prettier-ignore --\u003e\n\u003e [!NOTE]\n\u003e This is an early-stage project and may have unexpected behaviors or bugs. Please report any issues you encounter.\n\n## License\n\nMIT License - Copyright (c) 2025 Paillat-dev\n\n---\n\nMade with ❤ by Paillat-dev\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaillat-dev%2Fpycord-rest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaillat-dev%2Fpycord-rest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaillat-dev%2Fpycord-rest/lists"}