Concepts
How The Claw works
The Claw turns Discord community history into queryable, governed API data. This page explains the core ideas behind the platform.
Isolation
Servers and data isolation
Each Discord server is provisioned with its own isolated storage. Data from one server is never exposed to another server, regardless of whether they share an account. This boundary is enforced at the database level, not by application logic.
In the API, a server is identified by its Discord server ID (guild_id).
All queries are scoped to a single server.
Lifecycle
Installed vs enabled
Installing The Claw bot to your server syncs message history into isolated storage. Once setup completes, API access is enabled by default so your keys can start querying right away.
You can disable API access anytime from the dashboard. When disabled, existing API keys stop working immediately while data sync continues in the background. Re-enable anytime.
This gives owners full control — pause API access without losing sync progress, and re-enable whenever you are ready.
Credentials
API keys and principals
Every API key is bound to one server and one principal — the identity the key represents at runtime. A principal can be a Discord user, an external service, or an AI agent.
The platform distinguishes between the actor (who issued the key) and the subject (who uses it). An owner might issue a key for an external integration — the owner is the actor, the integration is the subject. Every key issuance and revocation is attributable to an authenticated actor.
Keys can be created from the dashboard by an admin, or via
/theclaw register in Discord when member sign-up is enabled.
Access scope
Channel controls
Owners choose which channels are exposed to the API in the Channels tab. All channels are included by default, so exclude any channel that should not be available to your API consumers.
Channel controls apply to all keys for that server. Changes take effect immediately — adding or removing a channel updates what every key can access.
Visibility depends on the bot’s permissions.
The bot can only sync and expose channels it can see in Discord.
By default it has View Channel and
Read Message History, which limits it to channels
visible to @everyone. To include private channels,
grant the bot’s role access to those channels or give it
Administrator.
Metering
Data usage and limits
Usage is metered by the amount of data your keys read (response data served, also known
as egress). The free tier provides pooled daily limits across all your
linked servers. Paid plans include a monthly data budget and scale with metered overage.
Paid plans let you configure how much data each self-registered member can read per day. The API tab in the dashboard shows current usage across your keys.
Entitlement
Verification hooks
When a member runs /theclaw register, The Claw can optionally call your
verification endpoint to decide whether to grant access. Your endpoint receives a
signed request with the access token, Discord user ID, and server ID, and returns
an allow or deny decision.
This lets you gate API access on external criteria — for example, a valid license key or an active subscription. See the Verification Integration guide for the full endpoint contract.