Moderation API
Check messages from your own app, site, or service with A.M.A.R. or M.A.C.R.O.
Keys
There are two kinds of key. A workspace key belongs to your workspace itself, for an app, site, or game that has nothing to do with a Discord server. Make one under API keys in your workspace. Workspace keys are included for verified Student Organizations, on Ultra at no charge.
A server key checks with one server's bot and uses its plan, M.A.C.R.O. units, and settings. API access is included with a server's Pro and Ultra plans. Make a key on the server's page, under Moderation, then API.
A key's secret is shown once. Keep it on your own server, never in an app or page people download, and revoke it at once if it leaks. A key stops working when it's revoked, while its plan doesn't include the API, or, for a server key, when the server leaves its workspace.
- A workspace key uses ASCA's standard settings for its bot.
- By default a server key uses the server's settings and follows any change to them: its content rating, rules, and what happens for each kind of problem.
- Give a server key its own settings to judge a different place differently, such as a children's forum held to Everyone while the server is Teen (PG-13).
Send a message
Send each message as a POST to /api/v1/moderation/checks with your key as a bearer token and an Idempotency-Key header that's unique to the message. Retrying with the same Idempotency-Key never checks or charges twice; reusing it for a different message is refused.
curl -X POST "https://asca.example/api/v1/moderation/checks" \
-H "Authorization: Bearer $ASCA_API_KEY" \
-H "Idempotency-Key: comment-81723" \
-H "Content-Type: application/json" \
-d '{
"text": "Message to check",
"author": { "id": "user-1", "name": "Sam" },
"conversationId": "thread-42",
"messageId": "comment-81723",
"replyToMessageId": "comment-81700",
"links": [{ "url": "https://example.com/picture.png" }]
}'What to send
- text: the message, up to 20,000 characters. Send text, links, or both.
- author.id: your ID for who wrote it. Their earlier messages are part of the context.
- conversationId: messages in the same conversation are read as context for each other, like a channel. Defaults to one shared conversation. A key can have up to 10,000 conversations.
- messageId and replyToMessageId: your IDs for the message and the one it answers. Sending the same messageId again checks the new version and replaces the earlier result.
- links: up to 10 links in the message, including images and files shared by link. They're scanned for malware, and looked at when the key's settings analyze linked images and files.
Results and waiting
The response waits up to 10 seconds for the check to finish and includes its result, so one request is usually all you need. Add ?wait=0 to return at once, or a number up to 10 to wait less. If it isn't done in time, the response is 202 with status queued or checking, estimatedWaitSeconds based on how long this server's recent checks took and how many are ahead of it, and a Retry-After header. Ask again with GET /api/v1/moderation/checks/{id}, which also accepts ?wait=.
- status: queued, checking, done, replaced (a newer version of the message was sent), or failed.
- result.outcome: allow, flag, or review, which means a person should decide.
- result.categories and result.reasons: what was found, in plain language.
- result.confidence: how sure the bot is, from 0 to 100.
- result.recommendedActions: what the key's settings would do: delete_message, warn_member with the warning to show, or timeout_member with minutes. Your service takes the action; ASCA never acts outside Discord.
- result.moderatorFirst: true when the key's settings would ask a moderator to approve these actions first.
Limits and errors
- Each key can make 300 requests a minute. Checks run as fast as the server's plan allows, like checks in Discord.
- 401: the key is missing, wrong, or revoked. 403: the key's plan doesn't include the API, the server left its workspace, or the key's workspace is no longer active. 409: the Idempotency-Key was used for a different message or conversation. 422: the request isn't valid, or the key has reached its conversation limit. 429: too many requests; wait for Retry-After.
- Possible child safety and serious harm are sent to ASCA for review, as they are from Discord.
- Messages you send are kept, encrypted, for as long as the server's plan keeps history, from 7 to 365 days, so they can be read as context and shown with their results.


