# Analyze a text message Source: https://docs.bodyguard.ai/api-reference/analyze/analyze-a-text-message /openapi/analyze.openapi.yaml post /analyze/v1/text Analyzes a text message/comment and returns its moderation classification, severity, target, detected language, and a recommended moderation action. Before diving in, we recommend reading the [text taxonomy](/en/documentation/taxonomy/text-classifications) to understand the classifications, severities, and moderation signals returned by this endpoint. # Analyze a username Source: https://docs.bodyguard.ai/api-reference/analyze/analyze-a-username /openapi/analyze.openapi.yaml post /analyze/v1/username Analyzes a username string to detect inappropriate, offensive, or otherwise undesirable content and returns a list of classifications. Before diving in, we recommend reading the [username taxonomy](/en/documentation/taxonomy/username-classifications) to understand the classifications returned by this endpoint. # Analyze an image Source: https://docs.bodyguard.ai/api-reference/analyze/analyze-an-image /openapi/analyze.openapi.yaml post /analyze/v1/image Analyzes an image by URL or by image bytes. Returns a list of classifications for the image and, when OCR is enabled, the text extracted from the image along with its own text analysis. Send the image in one of two ways: - **By URL:** an `application/json` body with `imageUrl`. - **By bytes:** a `multipart/form-data` body with the image file in the `imageData` part. The other fields are sent as form fields. Only **PNG**, **JPEG** and **WebP** images are accepted, and the image must not exceed **1 MiB** (1,048,576 bytes). Requests with an unsupported format or an oversized image are rejected with a `400 Bad Request`. Before diving in, we recommend reading the [image taxonomy](/en/documentation/taxonomy/image-classifications) to understand the classifications returned by this endpoint. # Image analysis feedback Source: https://docs.bodyguard.ai/api-reference/feedback/image-analysis-feedback /openapi/feedback.openapi.yaml post /feedback/v1/image Sends [feedback](/en/api-reference/concepts#feedback) on a classification returned by [`POST /analyze/v1/image`](/api-reference/analyze/analyze-an-image) that you judge incorrect for a given image, with the classifications you would have expected instead. Send the exact analyze request body you initially submitted in `analyzeRequest`. This will allow Bodyguard to replicate the analysis you referenced in your feedback and potentially enhance it based on your context. Send your feedback the same way you sent the image: - **By URL:** an `application/json` body, with your analyze request in `analyzeRequest`. - **By bytes:** a `multipart/form-data` body. Send each field of your analyze request as a form field prefixed with `analyzeRequest.`, with the image file in `analyzeRequest.imageData`. The other feedback fields are sent as form fields. Before diving in, we recommend reading the [image taxonomy](/en/documentation/taxonomy/image-classifications) to understand the classifications you can add or remove. # Text analysis feedback Source: https://docs.bodyguard.ai/api-reference/feedback/text-analysis-feedback /openapi/feedback.openapi.yaml post /feedback/v1/text Sends [feedback](/en/api-reference/concepts#feedback) on a classification returned by [`POST /analyze/v1/text`](/api-reference/analyze/analyze-a-text-message) that you judge incorrect for a given message, with the classifications you would have expected instead. Send the exact analyze request body you initially submitted in `analyzeRequest`. This will allow Bodyguard to replicate the analysis you referenced in your feedback and potentially enhance it based on your context. Before diving in, we recommend reading the [text taxonomy](/en/documentation/taxonomy/text-classifications) to understand the classifications you can add or remove. # Username analysis feedback Source: https://docs.bodyguard.ai/api-reference/feedback/username-analysis-feedback /openapi/feedback.openapi.yaml post /feedback/v1/username Sends [feedback](/en/api-reference/concepts#feedback) on a classification returned by [`POST /analyze/v1/username`](/api-reference/analyze/analyze-a-username) that you judge incorrect for a given username, with the classifications you would have expected instead. Send the exact analyze request body you initially submitted in `analyzeRequest`. This will allow Bodyguard to replicate the analysis you referenced in your feedback and potentially enhance it based on your context. Before diving in, we recommend reading the [username taxonomy](/en/documentation/taxonomy/username-classifications) to understand the classifications you can add or remove. # Key concepts Source: https://docs.bodyguard.ai/en/api-reference/concepts Understand the core building blocks of the Bodyguard API: organizations, sources, channels, references, and publication dates. ## Organization An **organization** is the top-level account entity in Bodyguard. It represents your company and owns all the resources associated with your contract — API keys, sources, channels, and usage quotas. ## Source A **source** represents a platform or integration registered with Bodyguard — for example, your mobile app or your website. Bodyguard provides a source identifier when you set up an integration. Sources belong to an organization and act as the container for your content. Each source contains one or more channels. Posts and authors are managed at the source level and are shared across all channels belonging to that source. A good rule of thumb: if two platforms share the same user base, they should be the same source. Moderation actions on authors — such as mute, ban, temporary mute, and temporary ban — are applied at the source level. An action taken against an author affects that author across every channel of the source, but never carries over to other sources. > [!NOTE] > > To moderate the same person independently across different platforms — for example, banning a player in one game but not in another — use a separate source for each platform. ## Channel A **channel** is a logical subdivision of a source — typically mapping to a distinct content stream within your platform, such as a product page, a live stream, or a community forum. Every analyze request requires a `channelId`, except username analysis, which requires a [`sourceId`](#source). Bodyguard uses the channel to apply the correct moderation configuration and to scope analytics and reporting. Channel identifiers are provided by Bodyguard when you configure your integration. ## Reference A **reference** is your own stable identifier for a piece of content, an author, or a post. You supply it in the request; Bodyguard stores it and echoes it back in webhooks and stored results so you can correlate moderation data with your own records. > [!NOTE] > > We strongly recommend sending references for messages, posts, and authors. Explicit references unlock the full potential of the Bodyguard platform — including accurate deduplication, reliable author-level analytics, and consistent moderation history. ## Publication date (`publishedAt`) The `publishedAt` field records when a piece of content was originally published on your platform. Bodyguard uses it to associate messages and posts with the correct time window in analytics and reporting. > [!WARNING] > > The value you send for a given message or post must remain **exactly** the same across all submissions and retries. Changing `publishedAt` for the same content causes it to appear as a duplicate in Bodyguard's records. ## Text sequence Some users split harmful content across several consecutive texts so that each text looks harmless on its own — for example `I am going to`, then `kill`, then `you`. Bodyguard detects this by also analyzing the recent consecutive texts of the same author, on the same post, as one combined text. Texts form a sequence only if they are consecutive, sent by the same author, on the same post, within a short time window. Text sequence analysis only runs when each request includes a `reference`, an `author.reference` and a `post.reference` — see [Reference](#reference). The response works as follows: * `textAnalysis` always contains the analysis of the current text alone. * When a sequence is detected as problematic, the response for the **last text** of the sequence also contains a `textSequence` object, with the `references` of every text in the sequence and the `textAnalysis` of the combined text. * To moderate the whole sequence, apply `textSequence.textAnalysis.recommendedAction` to every text listed in `textSequence.references`. > [!NOTE] > > Text sequence moderation may involve an additional cost. Contact your Bodyguard account manager for details. ## Feedback A **feedback** tells Bodyguard that a classification returned by the Analyze API does not fit your context — one you would not have applied, one you would have expected, or both. It is designed for edge cases and cases specific to your community: Bodyguard stays the authority on classification, and its moderation teams review your feedback to refine the models. You can submit feedback on the same content as many times as you like — it won't be rejected as a duplicate. > [!WARNING] > > Feedback informs Bodyguard's moderation teams for future improvements — it does not override moderation decisions in real time. Each analyze endpoint has a feedback counterpart: [text](/api-reference/feedback/text-analysis-feedback), [image](/api-reference/feedback/image-analysis-feedback), and [username](/api-reference/feedback/username-analysis-feedback). ## Next steps > [card] [Analyze text](/api-reference/analyze/analyze-a-text-message) > > Classify a comment, message, or any piece of text. > [card] [Analyze an image](/api-reference/analyze/analyze-an-image) > > Classify an image by URL or by file upload, with optional OCR. > [card] [Analyze a username](/api-reference/analyze/analyze-a-username) > > Check a username for inappropriate or undesirable content. # Introduction Source: https://docs.bodyguard.ai/en/api-reference/introduction Learn how to authenticate, handle errors, and understand rate limits for the Bodyguard API. The Bodyguard API is made of two parts: * The **Analyze API** classifies **text**, **images**, and **usernames** for harmful or undesirable content. * The **Feedback API** lets you send [feedback](/en/api-reference/concepts#feedback) on a classification you judge incorrect for your context, so Bodyguard can refine its models. Both share the same base URLs, authentication, rate limiting, and error format described on this page. All requests are made over HTTPS to: ```text theme={null} https://api.bodyguard.ai ``` `api.bodyguard.ai` is a global endpoint that should be used by default. `api.bodyguard.ai` is located in the Brussels (Belgium) area. ### Regional endpoints For lower latency, you can send requests directly to a specific region: | Region | Location | Base URL | | - | - | - | | US East | Northern Virginia, USA | `https://api.us1.bodyguard.ai` | | US West | California, USA | `https://api.us2.bodyguard.ai` | > [!NOTE] > > Regional endpoints expose the same API as the global endpoint — only the base URL changes. Your API key works across all regions. ## Quickstart The following example analyzes a text message. Replace `` and `` with values provided by Bodyguard. ```bash cURL theme={null} curl -X POST https://api.bodyguard.ai/analyze/v1/text \ -H "Authorization: ApiKey " \ -H "Content-Type: application/json" \ -d '{ "channelId": "", "text": "Einstein is an asshole", "publishedAt": "2026-04-23T10:30:00.000Z" }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.bodyguard.ai/analyze/v1/text", { method: "POST", headers: { Authorization: "ApiKey ", "Content-Type": "application/json", }, body: JSON.stringify({ channelId: "", text: "Einstein is an asshole", publishedAt: "2026-04-23T10:30:00.000Z", }), }); const result = await response.json(); console.log(result); ``` ```python Python theme={null} import requests response = requests.post( "https://api.bodyguard.ai/analyze/v1/text", headers={ "Authorization": "ApiKey ", "Content-Type": "application/json", }, json={ "channelId": "", "text": "Einstein is an asshole", "publishedAt": "2026-04-23T10:30:00.000Z", }, ) print(response.json()) ``` ```go Go theme={null} package main import ( "bytes" "encoding/json" "fmt" "io" "net/http" ) func main() { body, _ := json.Marshal(map[string]string{ "channelId": "", "text": "Einstein is an asshole", "publishedAt": "2026-04-23T10:30:00.000Z", }) req, _ := http.NewRequest("POST", "https://api.bodyguard.ai/analyze/v1/text", bytes.NewReader(body)) req.Header.Set("Authorization", "ApiKey ") req.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() out, _ := io.ReadAll(resp.Body) fmt.Println(string(out)) } ``` To interpret the response, see the [text classifications taxonomy](/en/documentation/taxonomy/text-classifications). ## Authentication All requests must include an `Authorization` header using the `ApiKey` scheme. The scheme name is case-sensitive — `ApiKey` must be written exactly as shown. ### Required request headers | Header | Value | | - | - | | `Authorization` | `ApiKey ` | | `Content-Type` | `application/json` | Your API key is provided by Bodyguard. Keep it secret and never expose it in client-side code. See [Get your API key](/en/documentation/how-to/get-api-key) to create a service account and an API key in the Bodyguard dashboard. ### Authentication errors All authentication failures return a `401 Unauthorized` response with the `AUTHENTICATION_ERROR` code and one of the following reasons: | Condition | `reason` | | - | - | | Invalid or unrecognized key | `REASON_INVALID_CREDENTIALS` | | Key has expired | `REASON_EXPIRED_CREDENTIALS` | | Key has been disabled | `REASON_DISABLED_CREDENTIALS` | The reason is returned inside the error envelope's `details.authenticationError.reason` field. See [Errors](#errors) for the full response format and a worked example. ## Versioning Endpoints live under a versioned path — for example, `/analyze/v1/text` and `/feedback/v1/text`. The `/v1/` endpoints are stable and Bodyguard commits to their API stability. Any breaking change will be introduced under a new version path (for example `/v2/`), allowing you to migrate on your own schedule. ## Rate limits Rate limits are enforced **per organization**. Each endpoint has its own independent quota. Quotas are customer-specific and negotiated as part of your contract. When your organization exceeds a quota, the API returns `429 Too Many Requests` with the `QUOTA_ERROR` code. The response envelope's `details.quotaError.violations` array identifies which specific quota was exceeded. ```json theme={null} { "error": { "code": "QUOTA_ERROR", "details": { "quotaError": { "violations": [ { "quotaName": "analyze.message.requests_per_second", "quotaValue": 10 } ] } } } } ``` Need a quota adjustment? [Contact us](https://www.bodyguard.ai/contact-us). ## Errors > [!NOTE] > > Check the [status page](https://status.bodyguard.ai) for real-time service availability and incident history. All errors follow a consistent JSON envelope: ```json theme={null} { "error": { "code": "", "details": { } } } ``` The `details` object contains structured information specific to the error type and has exactly one field whose name matches the error code (e.g. `badRequestError` for `BAD_REQUEST_ERROR`). The `Content-Type` of error responses is always `application/json`. ### Error codes | HTTP status | `code` | `details` payload | When it occurs | | - | - | - | - | | `400 Bad Request` | `BAD_REQUEST_ERROR` | `badRequestError.fieldViolations[]` | A required field is missing or a field value is invalid. The `fieldViolations` array identifies each offending field. | | `401 Unauthorized` | `AUTHENTICATION_ERROR` | `authenticationError.reason` | The API key is missing, invalid, expired, or disabled. | | `403 Forbidden` | `PERMISSION_DENIED_ERROR` | `permissionDeniedError.permission`, `.resourceIdentifier` | The API key does not have permission to perform the requested action on the resource. | | `404 Not Found` | `NOT_FOUND_ERROR` | `notFoundError.resourceIdentifier` | The requested resource does not exist. | | `409 Conflict` | `CONFLICT_ERROR` | `conflictError.reason` | The request conflicts with the current state of a resource. | | `412 Precondition Failed` | `PRECONDITION_FAILED_ERROR` | `preconditionFailedError.reason` | A precondition required for the request was not met. | | `429 Too Many Requests` | `QUOTA_ERROR` | `quotaError.violations[]` | Your organization has exceeded its rate limit. Safe to retry with backoff. See [Rate limits](#rate-limits). | | `503 Service Unavailable` | `TRANSIENT_ERROR` | `transientError.reason` | A transient server-side issue prevented the request from being processed. Safe to retry with backoff. | ### Example: bad request ```json theme={null} { "error": { "code": "BAD_REQUEST_ERROR", "details": { "badRequestError": { "fieldViolations": [ { "field": "text", "message": "field is required" } ] } } } } ``` ### Example: authentication failure ```json theme={null} { "error": { "code": "AUTHENTICATION_ERROR", "details": { "authenticationError": { "reason": "REASON_INVALID_CREDENTIALS" } } } } ``` ### Example: transient failure ```json theme={null} { "error": { "code": "TRANSIENT_ERROR", "details": { "transientError": { "reason": "upstream service temporarily unavailable" } } } } ``` Retry `TRANSIENT_ERROR` and `QUOTA_ERROR` responses with exponential backoff. All other error codes should not be retried without addressing the underlying cause. ## Next steps > [card] [Key concepts](/en/api-reference/concepts) > > Learn the core building blocks of the Bodyguard API: organizations, sources, channels, references, and publication dates. # Webhook payloads Source: https://docs.bodyguard.ai/en/api-reference/reference/webhooks/payloads Headers, payload structure, and examples of every event Bodyguard sends to your webhook endpoint. Bodyguard sends each notification as an HTTPS `POST` request with a JSON body. Headers and payload follow the [Standard Webhooks](https://www.standardwebhooks.com) specification. ## Headers | Header | Type | Description | | - | - | - | | `Content-Type` | string | The format of the body. Always `application/json`. | | `webhook-id` | string | The unique identifier of the notification, a UUID. It stays the same across retries, so you can use it to detect duplicates. Treat it as an opaque string and do not rely on its format. Example: `0f8fad5b-d9cb-469f-a165-70867728950e` | | `webhook-timestamp` | string | A Unix timestamp in seconds. It is part of the signed content and lets you reject replayed requests. Example: `1760868930` | | `webhook-signature` | string | One or more signatures of the request, separated by a space. Each signature is formatted as `v1,`. See [Quick start](/en/api-reference/webhooks/quick-start). Example: `v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=` | The request also includes the [custom headers](/en/api-reference/webhooks/configuration#custom-headers) configured on the webhook, if any. ## Payload structure Every payload has the same three top-level fields: | Field | Type | Description | | - | - | - | | `type` | string | The event type, for example `message.updated`. It identifies the schema of `data`. | | `timestamp` | string | When the event occurred, as an ISO 8601 date. It can differ from the time of delivery, and from the `webhook-timestamp` header. | | `data` | object | The content of the event. Its fields depend on `type`. | Payloads only carry identifiers and the attributes related to the event. Each event type below shows which fields are always present. Use `reference`, the identifier you sent in your analyze request, to match an event with your own records. ## Event types ### `message.updated` Sent when a Message is updated within a Channel. Optional fields are only present when their value changed. | Field in `data` | Type | Always present | Description | | - | - | - | - | | `id` | string | ✅ | The Bodyguard identifier of the message. | | `organizationId` | string | ✅ | The identifier of your organization. | | `sourceId` | string | ✅ | The identifier of the Source bound to the Channel. | | `channelId` | string | ✅ | The identifier of the Channel bound to the message. | | `reference` | string | ✅ | The [reference](/en/api-reference/concepts#reference) of the message. | | `classifications` | string\[] | Optional | The new classifications of the message, for example `["BODY_SHAMING", "INSULT"]`. See the [text taxonomy](/en/documentation/taxonomy/text-classifications). | | `recommendedAction` | string | Optional | The new recommended action, for example `KEEP` or `REMOVE`. | | `type` | string | Optional | The new nature of the content, for example `HATEFUL`. | | `severity` | string | Optional | The new severity of the content, for example `HIGH`. | For the possible values, see the [text taxonomy](/en/documentation/taxonomy/text-classifications). ```json Recommended action changed theme={null} { "type": "message.updated", "timestamp": "2026-10-19T10:15:30.706Z", "data": { "id": "d6a1f3b2-7c1e-4b8e-9a54-0e2f6c1b7a90", "organizationId": "5d849494-2b0e-49fc-85d5-7197ca62d7fe", "sourceId": "81310ae5-228e-438e-9720-35f737b9ca9f", "channelId": "cbc601f1-dec6-4594-9476-51628a17499a", "reference": "comment-48213", "recommendedAction": "REMOVE" } } ``` ```json Classifications changed theme={null} { "type": "message.updated", "timestamp": "2026-10-19T10:15:30.706Z", "data": { "id": "d6a1f3b2-7c1e-4b8e-9a54-0e2f6c1b7a90", "organizationId": "5d849494-2b0e-49fc-85d5-7197ca62d7fe", "sourceId": "81310ae5-228e-438e-9720-35f737b9ca9f", "channelId": "cbc601f1-dec6-4594-9476-51628a17499a", "reference": "comment-48213", "classifications": ["BODY_SHAMING", "INSULT"], "type": "HATEFUL", "severity": "HIGH", "recommendedAction": "REMOVE" } } ``` ### `author.updated` Sent when the status of an Author changes within a Source. | Field in `data` | Type | Always present | Description | | - | - | - | - | | `id` | string | ✅ | The Bodyguard identifier of the author. | | `organizationId` | string | ✅ | The identifier of your organization. | | `sourceId` | string | ✅ | The identifier of the Source bound to the author. | | `reference` | string | ✅ | The [reference](/en/api-reference/concepts#reference) of the author. | | `status` | string | ✅ | The new status of the author: `ACTIVE`, `BANNED`, `MUTED`, or `SHADOW_BANNED`. | | `statusExpiresAt` | string | Optional | The date when the action on the author expires, as an ISO 8601 date, for example `2026-10-26T10:15:30.706Z`. Only present when the action is temporary, for example a temporary ban. When the action expires, Bodyguard sends another `author.updated` event with the new status. | ```json Permanent action theme={null} { "type": "author.updated", "timestamp": "2026-10-19T10:15:30.706Z", "data": { "id": "7b3e9c10-5f2a-4d6b-8c41-a9d0e3f21b58", "organizationId": "5d849494-2b0e-49fc-85d5-7197ca62d7fe", "sourceId": "81310ae5-228e-438e-9720-35f737b9ca9f", "reference": "user-1a2b3c4d", "status": "BANNED" } } ``` ```json Temporary action theme={null} { "type": "author.updated", "timestamp": "2026-10-19T10:15:30.706Z", "data": { "id": "7b3e9c10-5f2a-4d6b-8c41-a9d0e3f21b58", "organizationId": "5d849494-2b0e-49fc-85d5-7197ca62d7fe", "sourceId": "81310ae5-228e-438e-9720-35f737b9ca9f", "reference": "user-1a2b3c4d", "status": "MUTED", "statusExpiresAt": "2026-10-26T10:15:30.706Z" } } ``` ### `webhook.validate` Sent when you enable a webhook, when you change the URL or the custom headers of an enabled webhook, and when you click **Send test event** in the dashboard. You cannot subscribe to this event. When you enable a webhook, or change the URL or the custom headers of an enabled webhook, your endpoint must answer with a `2xx` status code, otherwise the change fails with an error and the webhook stays as it was. **Send test event** is optional: use it to check that your endpoint receives events. The event is signed like any other event, so your endpoint verifies it as usual. | Field in `data` | Type | Description | | - | - | - | | `organizationId` | string | The identifier of your organization. | ```json webhook.validate theme={null} { "type": "webhook.validate", "timestamp": "2026-10-19T10:15:30.706Z", "data": { "organizationId": "5d849494-2b0e-49fc-85d5-7197ca62d7fe" } } ``` > [!NOTE] > > Ignore fields and event types you do not recognize, and answer them with a `2xx` status code. This keeps your endpoint working if the payloads evolve. ## Next steps > [card] [Handling errors](/en/api-reference/webhooks/handling-errors) > > Learn what Bodyguard expects from your endpoint, and its retry policy. # Reseller Guide Source: https://docs.bodyguard.ai/en/api-reference/reseller Advanced request fields available exclusively to Bodyguard reseller partners. > [!WARNING] > > This documentation applies exclusively to Bodyguard resellers and partners. If you are a direct customer, you can safely ignore this page. Reseller partners use the same three analyze endpoints as everyone else (`/analyze/v1/text`, `/analyze/v1/image`, `/analyze/v1/username`). The only difference: reseller API keys unlock a set of additional fields in the request body that tune how each endpoint behaves. Bodyguard configures a set of defaults for each organization and channel — industry vertical, language preferences, and many other advanced settings tailored to your use case. Reseller API keys let you override some of these defaults on a per-call basis, giving you fine-grained control when your traffic requires it. Settings not overridden in a request continue to use the values Bodyguard has configured for your channel. This page documents every reseller field. All fields are optional — pass only what you need. > [!NOTE] > > These fields require a reseller API key. Standard API keys that send them will receive an error. If you are not sure which type of key you hold, contact your Bodyguard account manager. ## Where each field applies | Field | Text | Image | Username | | - | :-: | :-: | :-: | | [`industry`](#industry) | Yes | Yes | Yes | | [`defaultLanguage`](#defaultlanguage) | Yes | Yes | Yes | | [`customerContext`](#customercontext) | — | Yes | Yes | | [`classificationsEnabled`](#classificationsenabled) | — | Yes | — | | [`ocrEnabled`](#ocrenabled) | — | Yes | — | Fields passed on endpoints where they don't apply are ignored. *** ## `industry` Sets the industry vertical of your platform. Bodyguard uses this to adapt the analysis model's thresholds and context — for example, weapon references in `GAMING` are treated very differently from weapon references in `MEDIA`. | Value | Description | | - | - | | `INDUSTRY_MEDIA` | News, broadcasting, editorial platforms | | `INDUSTRY_SPORT` | Sports clubs, leagues, fan communities | | `INDUSTRY_GAMING` | Games, esports, streaming | | `INDUSTRY_BRAND` | Brand social accounts, product communities | | `INDUSTRY_SOCIAL_PLATFORM` | General-purpose social networks | | `INDUSTRY_TECH_PROVIDER` | SaaS and developer platforms | | `INDUSTRY_OTHER` | Anything that doesn't fit the above | ```json theme={null} { "channelId": "", "text": "get rekt noob", "publishedAt": "2026-04-23T10:30:00.000Z", "industry": "INDUSTRY_GAMING" } ``` *** ## `defaultLanguage` An ISO 639-1 language code that tells Bodyguard which language your content is most likely in. This does **not** force the language — auto-detection still runs on every piece of content. When the detector is confident (for example, clearly Arabic text), it uses the detected language. When the signal is weak or ambiguous (short texts, emoji only, content that could plausibly be one of several languages), the `defaultLanguage` tips the decision in its favor. Set it to the language your channel is predominantly in to improve detection accuracy on borderline cases. ```json theme={null} { "channelId": "", "text": "lol", "publishedAt": "2026-04-23T10:30:00.000Z", "defaultLanguage": "fr" } ``` *** ## `customerContext` A free-form English description of the context in which your content is being moderated. The model uses it as an extra hint to disambiguate content whose meaning depends on the surrounding platform, audience, or editorial conventions. Applies to `/analyze/v1/image` and `/analyze/v1/username`. Typical things worth mentioning: * The type of platform and its audience (news site, sports club, gaming community, brand profile…). * Whether content is expected to include specific visual elements or usernames patterns (weapons in a combat game, nudity in an art publication, alcohol in a bar-owner brand account…). * Editorial or cultural conventions that would be surprising without context. Keep it general and stable across requests — this is meant to describe your channel, not each individual piece of content. Aim for **512 to 1,024 characters** and write in **English** for best results. ```json theme={null} { "channelId": "", "imageUrl": "https://cdn.example.com/uploads/screenshot.jpg", "publishedAt": "2026-04-23T10:30:00.000Z", "customerContext": "The provided images come from a peer-to-peer handyman marketplace where users share photos of their workspaces before, during, and after a service. Expect visual elements that are typical of manual work: construction and DIY tools such as utility knives, saws, and nail guns." } ``` *** ## `classificationsEnabled` Restricts image analysis to a subset of the [standard image taxonomy](/en/documentation/taxonomy/image-classifications). Only the classifications listed in this field are evaluated and returned — every other label is ignored, even if the image would otherwise match. This field overrides, for a single call, the list of classifications Bodyguard has configured for your organization, source, or channel. When it is omitted, Bodyguard falls back to that configured list. Each entry is the technical name of a standard image classification (for example `"WEAPONS"`, `"CSAM"`, `"GRAPHIC_NUDITY"`). ```json theme={null} { "channelId": "", "imageUrl": "https://cdn.example.com/uploads/screenshot.jpg", "publishedAt": "2026-04-23T10:30:00.000Z", "classificationsEnabled": ["WEAPONS", "EXTREME_VIOLENCE_AND_GORE"] } ``` With the settings above, the response will only ever contain `WEAPONS` and/or `EXTREME_VIOLENCE_AND_GORE` in its `classifications` array. Other classifications such as `ALCOHOL` or `QR_CODE` will not be evaluated. Enabling the `CSAM` classification *may incur additional pricing.* *** ## `ocrEnabled` Controls whether OCR (optical character recognition) runs on image inputs. When set to `true`, Bodyguard extracts all text from the image and runs a single text analysis on the full extracted content — the same analysis as the `/analyze/v1/text` endpoint. *Additional pricing may apply.* The OCR result is returned in the `ocrAnalysis` object of the image analysis response. It contains the extracted `text` and a `textAnalysis` object. ```json theme={null} { "channelId": "", "imageUrl": "https://cdn.example.com/uploads/screenshot.jpg", "publishedAt": "2026-04-23T10:30:00.000Z", "ocrEnabled": true } ``` **Example response with OCR results:** ```json theme={null} { "imageAnalysis": { "classifications": ["GRAPHIC_VIOLENCE"], "ocrAnalysis": { "text": "you're going to regret this", "textAnalysis": { "type": "HATEFUL", "classifications": ["THREAT"], "severity": "HIGH", "directedAt": "USER", "language": "en", "recommendedAction": "REMOVE" } } } } ``` *** ## Full example Combining all reseller fields on the image endpoint: ```bash cURL theme={null} curl -X POST https://api.bodyguard.ai/analyze/v1/image \ -H "Authorization: ApiKey " \ -H "Content-Type: application/json" \ -d '{ "channelId": "", "imageUrl": "https://cdn.example.com/uploads/photo.jpg", "publishedAt": "2026-04-23T10:30:00.000Z", "industry": "INDUSTRY_GAMING", "defaultLanguage": "en", "ocrEnabled": true, "classificationsEnabled": ["WEAPONS", "HATE_SPEECH_AND_SYMBOLS"], "customerContext": "Peer-to-peer handyman marketplace. Expect construction tools, messy rooms, and bathroom interiors — these must not be flagged as WEAPONS, VISUALLY_DISTURBING, or NUDITY. Flag only genuine policy violations. Audience is adults aged 25 to 55 in North America and Western Europe." }' ``` # Webhook configuration Source: https://docs.bodyguard.ai/en/api-reference/webhooks/configuration Configure the URL, events, signing secret, custom headers, and contacts of a Bodyguard webhook, and understand webhook statuses. This page describes the fields you set when you register a webhook in the dashboard (**Settings** > **Webhooks** > **Add webhook +**). ## Endpoint URL The URL that receives notifications. It must be a public `https` URL with a valid TLS certificate that is not self-signed. Bodyguard denies webhooks registered with an `http` URL. ## Events A webhook is triggered by one or more events that you subscribe to: | Event type | Triggered when | | - | - | | [`message.updated`](/en/api-reference/reference/webhooks/payloads#message-updated) | A Message is updated within a Channel. | | [`author.updated`](/en/api-reference/reference/webhooks/payloads#author-updated) | The status of an Author changes within a Source. | One webhook can subscribe to several events. You can also add another webhook with a different URL to handle other events separately. > [!NOTE] > > Bodyguard also sends a [`webhook.validate`](/en/api-reference/reference/webhooks/payloads#webhook-validate) event, which you cannot subscribe to. Your endpoint must answer it with a `2xx` status code when you enable the webhook, and when you change the URL or the custom headers of an enabled webhook. For the content of each event, see [Payloads](/en/api-reference/reference/webhooks/payloads). ## Signing secret Bodyguard generates a signing secret for each webhook. It starts with `whsec_` followed by a base64-encoded value. The dashboard displays it only once, when you create the webhook, so copy it then. See [Connect your webhook](/en/documentation/how-to/connect-webhook). Bodyguard uses it to sign every request, and you use it to verify that a request comes from Bodyguard and was not altered. See [Quick start](/en/api-reference/webhooks/quick-start). > [!WARNING] > > Treat the signing secret like a password. Store it in a secrets manager or an environment variable, and never expose it in client-side code. ## Custom headers Custom headers are optional HTTP headers that you add to a webhook as key/value pairs. Bodyguard includes them in every request it sends to your endpoint, including [`webhook.validate`](/en/api-reference/reference/webhooks/payloads#webhook-validate) events. For example, use them to send a token expected by your API gateway. Custom headers follow these rules: * A webhook can have up to 20 custom headers. * Each key and each value is limited to 256 characters. * A key must be a valid HTTP header name. * Keys are case-insensitive: you can't set the same key twice, even with a different case. * Standard headers, set by Bodyguard or by the HTTP protocol, can't be used as custom headers, whatever their case: for example `Content-Type`, `webhook-signature`, or `User-Agent`. If you change the custom headers of an enabled webhook, Bodyguard sends a `webhook.validate` event with the new headers. If your endpoint doesn't answer with a `2xx` status code, the update fails and the webhook keeps its previous headers. > [!NOTE] > > Custom headers don't replace signature verification. Always verify the `webhook-signature` header of each request, as described in the [Quick start](/en/api-reference/webhooks/quick-start). ## Contacts Each new webhook requires at least one contact. Bodyguard sends alerts to every contact if it encounters issues reaching your endpoint, such as the emails described in [Handling errors](/en/api-reference/webhooks/handling-errors#emails). Each contact must be a user registered to your organization on the dashboard. ## Webhook statuses Each webhook has a status that describes its current state: | Status | Description | | - | - | | `ENABLED` | The webhook is active and ready to receive notifications. | | `DISABLED` | The webhook is inactive and notifications are not sent. You can set this value from the dashboard. | | `ERROR` | The webhook is in error and notifications are not sent. Bodyguard attempted to notify your endpoint multiple times without success. | The `ERROR` status is set automatically. While a webhook is `DISABLED` or `ERROR`, Bodyguard doesn't send its events, and they can't be replayed when you enable the webhook again. To enable a webhook in error, fix the issue, then enable it manually from the dashboard. See [Handling errors](/en/api-reference/webhooks/handling-errors). ## Next steps > [card] [Payloads](/en/api-reference/reference/webhooks/payloads) > > Headers, payload structure, and an example for each event type. # Handling webhook errors Source: https://docs.bodyguard.ai/en/api-reference/webhooks/handling-errors Understand which responses Bodyguard accepts from your endpoint, the retry policy, and the emails sent when deliveries fail. This page describes how Bodyguard handles the responses of your endpoint, its retry policy, and the emails it sends when deliveries fail. ## Response handling Bodyguard judges a delivery by the response of your endpoint: | Response | Result | | - | - | | `2xx` | Success. The notification is delivered. | | Any other status code, or no response within 10 seconds | Failure. | Every failure enters the retry policy described below. ## Retry policy If a delivery fails, Bodyguard retries it several times over a period of time. Every attempt of the same notification carries the same [`webhook-id`](/en/api-reference/reference/webhooks/payloads#headers) header, so you can [deduplicate](/en/api-reference/webhooks/quick-start#process-events-safely) them. If your endpoint keeps failing, Bodyguard automatically sets the webhook status to `ERROR` and stops sending notifications to it. Events that occur while the webhook is in error are not sent, and can't be replayed when you enable it again. After you fix the issue, open the dashboard (**Settings** > **Webhooks**) and set the status back to `ENABLED`. ## Emails Bodyguard sends these emails to every [contact](/en/api-reference/webhooks/configuration#contacts) of the webhook: | Email | When it is sent | | - | - | | Warning | At the first failure. At most one warning email per day. | | Broken webhook | When the webhook status is set to `ERROR`. | # Introduction to webhooks Source: https://docs.bodyguard.ai/en/api-reference/webhooks/introduction Receive real-time notifications when the state of a message or an author changes in Bodyguard. A webhook notifies one system of a state change in another system. In practice, it is an HTTP request with a [JSON payload](/en/api-reference/reference/webhooks/payloads#payload-structure), sent by the central system to an endpoint you control. Bodyguard webhooks send real-time notifications when a resource changes. They are `POST` requests over HTTPS, and they follow the [Standard Webhooks](https://www.standardwebhooks.com) specification. You verify them with an open-source library instead of writing Bodyguard-specific code. > [!WARNING] > > This section describes the webhooks of the new Bodyguard API. Documentation for the existing webhooks is available at [https://www.bodyguard.ai/docs/api/webhooks/introduction](https://www.bodyguard.ai/docs/api/webhooks/introduction). ## Webhooks vs. polling Polling and webhooks are two general ways to learn about changes in another system. This comparison explains the concepts only: Bodyguard sends changes through webhooks and doesn't provide a polling API. | | Polling | Webhooks | | - | - | - | | How you get events | You call an API in a loop, at a fixed interval | Bodyguard calls your endpoint when an event happens | | Real-time notification | No | Yes | | Quota impact | Every call counts toward your quotas | None | | Integration effort | A scheduler and state tracking | One HTTPS endpoint | ## When to use webhooks Webhooks let you automate actions in your application based on Bodyguard events. We recommend integrating them to keep track of the state of each resource. Typical uses: * **Message decisions:** you receive a notification when a message is classified as `SPAM`, or when its recommended action changes. * **Automatic author decisions:** you receive a notification when an author is banned or muted based on their behavior (for example a bot or a scammer). * **Manual actions from the dashboard:** you receive a notification when a message is removed (its recommended action changes to `REMOVE`) or an author is banned from the Bodyguard dashboard. ## How it works **1. Create your endpoint** Build an endpoint on your server that accepts `POST` requests on a public HTTPS URL, and verifies the signature of each request. See [Quick start](/en/api-reference/webhooks/quick-start) for ready-to-use examples. **2. Register it in the dashboard** Click the gear icon in the left menu to open **Settings**, then select **Webhooks** and click **Add webhook +**. Fill in the form: see [Configuration](/en/api-reference/webhooks/configuration) for each field. The webhook is created with the `DISABLED` status. **3. Enable and test the integration** Enable the webhook. Bodyguard sends a [`webhook.validate`](/en/api-reference/reference/webhooks/payloads#webhook-validate) event to your endpoint, which must answer with a `2xx` status code for the webhook to be enabled. Click **Send test event** at any time to send a [`webhook.validate`](/en/api-reference/reference/webhooks/payloads#webhook-validate) event and check that your endpoint receives events. Once enabled, your webhook has the `ENABLED` [status](/en/api-reference/webhooks/configuration#webhook-statuses) and Bodyguard sends an HTTPS `POST` request to your endpoint each time an event you subscribed to is triggered. See [Payloads](/en/api-reference/reference/webhooks/payloads) for the content of each request. ## Next steps > [card] [Quick start](/en/api-reference/webhooks/quick-start) > > Build an endpoint and verify each request with a Standard Webhooks library. > [card] [Configuration](/en/api-reference/webhooks/configuration) > > Events, signing secret, custom headers, contacts, and webhook statuses. > [card] [Payloads](/en/api-reference/reference/webhooks/payloads) > > Headers, payload structure, and an example for each event type. # Webhooks quick start Source: https://docs.bodyguard.ai/en/api-reference/webhooks/quick-start Build a webhook endpoint and verify each Bodyguard request with a Standard Webhooks library. Bodyguard signs every webhook request, so you can check that it comes from Bodyguard and that nobody altered it. Signatures follow the [Standard Webhooks](https://www.standardwebhooks.com) specification, so you verify them with the official open-source libraries instead of writing the cryptography yourself. ## Prerequisites * The signing secret of your webhook. It starts with `whsec_`. See [Configuration](/en/api-reference/webhooks/configuration#signing-secret). * A server that can expose a public HTTPS endpoint. * The endpoint must complete a valid TLS handshake, with a certificate from a trusted certificate authority. Self-signed certificates are not accepted. * The endpoint must answer within 10 seconds. Otherwise, the delivery is considered a failure. ## How signing works Bodyguard signs each request as described in the [Verifying webhook authenticity](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#verifying-webhook-authenticity) section of the Standard Webhooks specification. Bodyguard uses the symmetric signature scheme: `HMAC-SHA256` with your `whsec_` signing secret, and the `v1` signature identifier. ## Create your endpoint Install the library for your language: ```bash JavaScript theme={null} npm install standardwebhooks express ``` ```bash Python theme={null} pip install standardwebhooks flask ``` ```bash Go theme={null} go get github.com/standard-webhooks/standard-webhooks/libraries/go ``` Then create an endpoint that accepts `POST` requests and verifies each one. Pass the signing secret in the `BODYGUARD_WEBHOOK_SECRET` environment variable. For the content of `event.data`, see [Payloads › Event types](/en/api-reference/reference/webhooks/payloads#event-types). ```javascript JavaScript theme={null} const express = require("express"); const { Webhook } = require("standardwebhooks"); const wh = new Webhook(process.env.BODYGUARD_WEBHOOK_SECRET); // "whsec_..." const app = express(); // Keep the raw body: the signature covers the exact bytes Bodyguard sent. app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => { let event; try { event = wh.verify(req.body, req.headers); } catch (err) { return res.status(400).send("Invalid signature"); } switch (event.type) { case "message.updated": console.log("Message updated:", event.data.id, event.data); break; case "author.updated": console.log("Author updated:", event.data.id, event.data); break; } // Any 2xx response acknowledges the delivery. res.sendStatus(200); }); app.listen(8080, () => console.log("Listening on port 8080")); ``` ```python Python theme={null} import os from flask import Flask, request from standardwebhooks import Webhook, WebhookVerificationError wh = Webhook(os.environ["BODYGUARD_WEBHOOK_SECRET"]) # "whsec_..." app = Flask(__name__) @app.post("/webhook") def webhook(): # Use the raw body: the signature covers the exact bytes Bodyguard sent. try: event = wh.verify(request.get_data(), request.headers) except WebhookVerificationError: return "Invalid signature", 400 if event["type"] == "message.updated": print("Message updated:", event["data"]) elif event["type"] == "author.updated": print("Author updated:", event["data"]) # Any 2xx response acknowledges the delivery. return "", 200 if __name__ == "__main__": app.run(port=8080) ``` ```go Go theme={null} package main import ( "encoding/json" "io" "log" "net/http" "os" standardwebhooks "github.com/standard-webhooks/standard-webhooks/libraries/go" ) func main() { wh, err := standardwebhooks.NewWebhook(os.Getenv("BODYGUARD_WEBHOOK_SECRET")) // "whsec_..." if err != nil { log.Fatal(err) } http.HandleFunc("/webhook", func(w http.ResponseWriter, r *http.Request) { // Use the raw body: the signature covers the exact bytes Bodyguard sent. body, err := io.ReadAll(r.Body) if err != nil { http.Error(w, "Cannot read body", http.StatusBadRequest) return } if err := wh.Verify(body, r.Header); err != nil { http.Error(w, "Invalid signature", http.StatusBadRequest) return } var event struct { Type string `json:"type"` Data json.RawMessage `json:"data"` } if err := json.Unmarshal(body, &event); err != nil { http.Error(w, "Invalid payload", http.StatusBadRequest) return } switch event.Type { case "message.updated": log.Printf("Message updated: %s", event.Data) case "author.updated": log.Printf("Author updated: %s", event.Data) } // Any 2xx response acknowledges the delivery. w.WriteHeader(http.StatusOK) }) log.Println("Listening on port 8080") log.Fatal(http.ListenAndServe(":8080", nil)) } ``` > [!WARNING] > > Verify the raw request body, exactly as received. If a framework parses the JSON and you serialize it again, whitespace and key order can change and the signature check fails. The [`webhook.validate`](/en/api-reference/reference/webhooks/payloads#webhook-validate) event does not need special handling: it is signed like any other event, so your endpoint verifies it and answers with a `2xx` status code. Run your endpoint: ```bash JavaScript theme={null} BODYGUARD_WEBHOOK_SECRET="whsec_..." node index.js ``` ```bash Python theme={null} BODYGUARD_WEBHOOK_SECRET="whsec_..." python app.py ``` ```bash Go theme={null} BODYGUARD_WEBHOOK_SECRET="whsec_..." go run . ``` ### Other languages Standard Webhooks also provides libraries for Java and Kotlin, Rust, Ruby, PHP, C#, and Elixir. See the [list of libraries](https://github.com/standard-webhooks/standard-webhooks#libraries). > [accordion] Verify a signature without a library > > If no library fits your stack, implement the verification described in the [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md): > > 1. Read the `webhook-id`, `webhook-timestamp`, and `webhook-signature` [headers](/en/api-reference/reference/webhooks/payloads#headers). > 2. Reject the request if `webhook-timestamp` is too far from the current time (the official libraries use five minutes). > 3. Build the signed content: `{webhook-id}.{webhook-timestamp}.{raw body}`. > 4. Remove the `whsec_` prefix from your signing secret and base64-decode the rest. Compute the HMAC SHA256 of the signed content with this key, and base64-encode the result. > 5. Compare it, in constant time, with each `v1,` signature in the `webhook-signature` header. The request is valid if one of them matches. ## Test your endpoint When you enable the webhook, or change the URL or the custom headers of an enabled webhook, Bodyguard sends a [`webhook.validate`](/en/api-reference/reference/webhooks/payloads#webhook-validate) event: if your endpoint doesn't answer with a `2xx` status code, the change fails. To check your endpoint at any time, click **Send test event** in the dashboard. ## Process events safely * **Answer quickly.** Return a `2xx` status code within 10 seconds, as soon as you have verified and stored the event, and do the heavy work afterwards. Any other response, or no response, is a [failure](/en/api-reference/webhooks/handling-errors#response-handling) and triggers a retry. * **Deduplicate with `webhook-id`.** Bodyguard retries failed deliveries with the same [`webhook-id`](/en/api-reference/reference/webhooks/payloads#headers) header. Store the identifiers you have processed, and skip the ones you have already seen. * **Keep the secret private.** Load it from the environment, and never log it. ## Next steps > [card] [Configuration](/en/api-reference/webhooks/configuration) > > Events, signing secret, custom headers, contacts, and webhook statuses. # Connect your webhook Source: https://docs.bodyguard.ai/en/documentation/how-to/connect-webhook Register a webhook in the Bodyguard dashboard to receive notifications on your endpoint. A webhook notifies your endpoint when events occur in Bodyguard, such as a message or an author being updated. This page walks you through registering one in the dashboard. To learn how webhooks work, see the [Webhooks introduction](/en/api-reference/webhooks/introduction). ## Prerequisites You need a public HTTPS endpoint that is ready to receive notifications. Bodyguard denies webhooks registered with an `http` URL. See the [Quick start](/en/api-reference/webhooks/quick-start) to build your endpoint and verify the signature of each request. ## Steps **1. Add a webhook** 1. Click the gear icon in the left menu to open **Settings**, select **Webhooks**, then click **Add webhook**. ![Webhooks page with the Settings gear icon (1), the Webhooks entry (2), and the Add webhook button (3) highlighted](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/connect-webhook/01-open-webhooks-page.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=71ad72d9f89c307321eb2981a9acf4c9) Settings > Webhooks 2. Fill in the form. The numbers match the screenshot below. **1.** Enter the **Endpoint URL** that receives notifications. It must be publicly reachable over HTTPS.\ **2.** Add at least one **Alert contact**. Bodyguard notifies your contacts when deliveries to this endpoint fail. Each contact must be a user registered to your organization on the dashboard.\ **3.** Choose the **Sources** the webhook applies to. In this example, **All the organization's API sources** is selected.\ **4.** Select the **Events** you subscribe to: `message.updated` (when a message is updated by Bodyguard) and `author.updated` (when an author is updated by Bodyguard).\ **5.** Click **Create webhook**. ![New webhook dialog with the Endpoint URL (1), Alert contact (2), Sources (3), and Events (4) fields and the Create webhook button (5) highlighted](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/connect-webhook/02-new-webhook-form.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=b3c06997e442288a625613943e370d37) New webhook form See [Configuration](/en/api-reference/webhooks/configuration) for each field and [Payloads](/en/api-reference/reference/webhooks/payloads) for the content of each event. **2. Copy your signing secret** Bodyguard generates a signing secret when you create the webhook and displays it in the **Webhook created** dialog. Copy it with the copy icon and store it somewhere safe, then click **Done**. The secret starts with `whsec_`. ![Webhook created dialog with the signing secret field and its copy icon highlighted](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/connect-webhook/03-signing-secret.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=3c03ea994fe4205b5afd49160524df63) Signing secret displayed at creation > [!WARNING] > > The signing secret is shown only once. You can't see it again after closing the dialog. Treat it like a password and never expose it in client-side code. You use the signing secret to verify that each request comes from Bodyguard. See the [Quick start](/en/api-reference/webhooks/quick-start). **3. Enable and test your webhook** Your webhook is created with the `Disabled` status. Enable it once your endpoint is ready to receive events. Click the **⋮** menu at the end of the webhook row to open its actions: ![Webhooks list with the three-dot button of the webhook row (1) and its actions menu highlighted, showing Send test event, Edit webhook, Enable webhook, and Delete webhook](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/connect-webhook/04-webhook-actions-menu.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=f6f543e38882a16540b4c21afdfa074c) Webhook actions menu * **Enable webhook** activates the webhook. Bodyguard first sends a [`webhook.validate`](/en/api-reference/reference/webhooks/payloads#webhook-validate) event to your endpoint, which must answer with a `2xx` status code, otherwise the webhook stays disabled. * **Send test event** lets you check that your endpoint receives events. * **Edit webhook** and **Delete webhook** let you change or remove the webhook. > [!NOTE] > > While a webhook is disabled, Bodyguard doesn't send its events, and they can't be replayed when you enable the webhook again. See [Webhook statuses](/en/api-reference/webhooks/configuration#webhook-statuses). ## Next steps > [card] [Quick start](/en/api-reference/webhooks/quick-start) > > Build an endpoint and verify each request with a Standard Webhooks library. > [card] [Configuration](/en/api-reference/webhooks/configuration) > > Events, signing secret, custom headers, contacts, and webhook statuses. > [card] [Handling errors](/en/api-reference/webhooks/handling-errors) > > What happens when your endpoint fails, and how to recover. # Get your API key Source: https://docs.bodyguard.ai/en/documentation/how-to/get-api-key Create a service account and an API key in the Bodyguard dashboard to authenticate your API requests. To call the Bodyguard API, your application authenticates with an API key. In the dashboard, API keys belong to a **service account**: the service account is the identity of your application or automated process (a monitoring tool, a script, a data pipeline, a staging or production environment), and the API key is the credential it uses to authenticate. > [!NOTE] > > Service accounts and API keys are only supported by the new API. ## Prerequisites You need the **Admin** role in your organization to create and manage service accounts and API keys. Members and Editors can view them. ## Steps **1. Create a service account** 1. Click the gear icon in the left menu to open **Settings**, then select **Identity & access management**. ![Bodyguard dashboard with the Settings gear icon in the left menu and the Identity & access management entry highlighted](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/get-api-key/01-open-identity-access-management.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=3c532a44d620aaa28e01b00ff3f95620) Settings > Identity & access management 2. Open the **Service accounts** tab and click **Create service account**. ![Service accounts tab with the Create service account button highlighted](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/get-api-key/02-create-service-account-button.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=eb53cd519b9cec5584337e650243ba9b) Service accounts tab 3. Fill in the form. The numbers match the screenshot below. **1.** Enter a **Name**.\ **2.** Add an optional **Description**.\ **3.** Review the source access. **Grant full source access** is enabled by default: the service account can access all current and future sources.\ **4.** Click **Create**. ![Create service account dialog with the Name field (1), the Description field (2), the Grant full source access option (3), and the Create button (4) highlighted](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/get-api-key/03-create-service-account-form.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=e743a37f72a204681cc090a4cc38f5e8) Create service account form Use a clear name that identifies the application or environment using the account. For example, name it `Production Monitoring` and describe it as `Used by the production monitoring integration`. 4. Your service account appears in the list. Click the expand icon at the end of its row to open its details page. ![Service accounts list with the new service account highlighted and an arrow pointing to the expand icon that opens its details page](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/get-api-key/04-open-service-account-details.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=e1d50b7bcfaade82b2c03090037a4909) Open the service account details page **2. Generate an API key** 1. On the service account details page, click **Generate an API key**. ![Service account details page with the Generate an API key button highlighted](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/get-api-key/05-generate-api-key-button.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=c92294d33da1a0875332546f58778bd8) Service account details page 2. Enter a name and an optional description. To make the key expire, select **Set an expiration date** and pick a date. Then click **Generate and continue**. ![Generate an API key dialog with the Name, Description, Set an expiration date, and Expiration date fields, and the Generate and continue button](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/get-api-key/06-generate-api-key-form.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=f3e43876ed8bf82236e8e3e2a5b0b4e8) Generate an API key form 3. Copy your API key with the copy icon and store it securely, then click **Done**. The key is displayed only once, when you create it. You can't display it again afterwards. ![Your API key has been generated dialog with the API key field and its copy icon highlighted](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/get-api-key/07-api-key-displayed-once.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=762e744f44a2f31268010e24dbf0c302) API key displayed at creation You can later edit, deactivate, or delete a key from the **⋮** menu at the end of its row. Editing a key only changes its name, description, and expiration date: you can't change or display its value. If you lose the value of a key, generate a new one. ![API key row with its menu open, showing the Edit API key, Deactivate, and Delete actions](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/get-api-key/08-api-key-actions.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=b2356adafef5ccd8a281dc62cdc48548) API key actions > [!WARNING] > > Deactivating a service account does not deactivate its API keys. Manage the keys separately when necessary. **3. Use your API key** Send the key in the `Authorization` header of every request, using the case-sensitive `ApiKey` scheme: ```text Authorization header theme={null} Authorization: ApiKey ``` See [Authentication](/en/api-reference/introduction#authentication) for the required headers and the authentication errors, and the [Quickstart](/en/api-reference/introduction#quickstart) for a first request. > [!WARNING] > > Keep your API key secret and never expose it in client-side code. ## Next steps > [card] [API introduction](/en/api-reference/introduction) > > Authenticate and send your first request. > [card] [Connect your webhook](/en/documentation/how-to/connect-webhook) > > Receive notifications on your endpoint. # Introduction Source: https://docs.bodyguard.ai/en/documentation/introduction Bodyguard protects your platform from toxic content using contextual AI. Get severity ratings, classifications, and recommended actions in real time. > [!WARNING] > > This documentation describes the new Bodyguard API, which is not yet generally available. Documentation for the existing API is available at [https://www.bodyguard.ai/docs/api](https://www.bodyguard.ai/docs/api). > [card] [Text classifications](/en/documentation/taxonomy/text-classifications) > > Explore the categories, severities, and recommended actions returned when analyzing text. > [card] [Image classifications](/en/documentation/taxonomy/image-classifications) > > Explore the categories, severities, and recommended actions returned when analyzing images. > [card] [Username classifications](/en/documentation/taxonomy/username-classifications) > > Explore the classifications returned when analyzing usernames. # Image classifications Source: https://docs.bodyguard.ai/en/documentation/taxonomy/image-classifications A complete reference to Bodyguard's image taxonomy: the classifications we detect in visual content. Bodyguard analyzes every image and describes it with a set of labels that tell you precisely what was detected — from nudity and violence to QR codes and identifiable people. Each label is a **classification**, and a single image can carry several classifications at once. Unlike text, images are not qualified by additional signals such as type, severity, or target. The taxonomy is flat: each classification stands on its own and is returned whenever Bodyguard detects the corresponding content. > [!NOTE] > > OCR (text extraction from images) is an optional feature that can be enabled on request. When activated, any text found in the image is extracted and analyzed through the text taxonomy. [Contact us](https://www.bodyguard.ai/contact-us) to enable it. *** ## Classifications Each card below shows the human-friendly name, the technical value used by the API, and a short description of what triggers the classification. ### Sexual content > [!WARNING] > > `CSAM` is the highest-severity classification. Any detection should trigger immediate action and, where legally required, reporting to the relevant authorities. > [card] [Child Sexual Abuse Material](#child-sexual-abuse-material) > > `CSAM` > > Any Child Sexual Abuse Material — photos, videos, and computer-generated images depicting sexual abuse of minors. > > *Additional pricing may apply.* > [card] [Sexual activity](#sexual-activity) > > `SEXUAL_ACTIVITY` > > Content showing explicit sexual acts between individuals (e.g. penetration, masturbation, oral sex). > [card] [Graphic nudity](#graphic-nudity) > > `GRAPHIC_NUDITY` > > Explicit and non-artistic nudity. Fully exposed genitals, buttocks, or breasts in a sexual context. > [card] [Partial nudity](#partial-nudity) > > `PARTIAL_NUDITY` > > Non-explicit nudity, such as partially or barely covered breasts or buttocks. > [card] [Suggestive poses & erotica](#suggestive-poses-erotica) > > `SUGGESTIVE_POSES_AND_EROTICA` > > Erotic content or sexually suggestive poses without explicit nudity. > [card] [Bare male chest](#bare-male-chest) > > `BARE_MALE_CHEST` > > Bare male torso, or a torso visible through sheer fabric. Excludes opaque tank tops and babies. > [card] [Revealing attire](#revealing-attire) > > `REVEALING_ATTIRE` > > Individuals wearing highly revealing clothing (e.g. lingerie, swimwear) in a sexual pose or context. > [card] [Adult toys](#adult-toys) > > `ADULT_TOYS` > > Items designed for sexual stimulation (e.g. sex toys, inflatable dolls). > [card] [Female swimwear or underwear](#female-swimwear-or-underwear) > > `FEMALE_SWIMWEAR_OR_UNDERWEAR` > > Women wearing swimwear or visible underwear. Excludes sports bras. > [card] [Male swimwear or underwear](#male-swimwear-or-underwear) > > `MALE_SWIMWEAR_OR_UNDERWEAR` > > Men wearing swimwear or visible underwear without other clothes on top. > [card] [Nudity in art or education](#nudity-in-art-or-education) > > `NUDITY_IN_ART_OR_EDUCATION` > > Nudity in a clear artistic (e.g. painting, sculpture) or educational (e.g. anatomical diagram) context. ### Violence & harm > [card] [Extreme violence & gore](#extreme-violence-gore) > > `EXTREME_VIOLENCE_AND_GORE` > > Graphic and explicit violence — severe injuries, mutilation, corpses in a gore context, or large amounts of blood. > [card] [Physical violence](#physical-violence) > > `PHYSICAL_VIOLENCE` > > Non-graphic physical altercations such as fights or assaults. Excludes regulated combat sports and video games. > [card] [Weapons](#weapons) > > `WEAPONS` > > Weapons being used or displayed in a threatening context. Excludes non-threatening contexts (e.g. video games, sports, art, law enforcement). > [card] [Self-harm](#self-harm) > > `SELF_HARM` > > Acts of self-harm, suicide, or content that glorifies such behaviors. > [card] [Visually disturbing](#visually-disturbing) > > `VISUALLY_DISTURBING` > > Non-gory content that may be shocking or unsettling (e.g. accidents, emaciated bodies). ### Hate & harassment > [card] [Hate speech & symbols](#hate-speech-symbols) > > `HATE_SPEECH_AND_SYMBOLS` > > Symbols, text, or imagery associated with hate or terrorist groups (e.g. Nazism, KKK). Excludes religious or cultural symbols outside of a hateful context. > [card] [Harassment & bullying](#harassment-bullying) > > `HARASSMENT_AND_BULLYING` > > Content intended to harass, threaten, or humiliate an identifiable private individual. > [card] [Offensive gestures](#offensive-gestures) > > `OFFENSIVE_GESTURES` > > Hand gestures widely recognized as offensive or obscene (e.g. the middle finger). ### Substances & regulated activity > [card] [Drugs & controlled substances](#drugs-controlled-substances) > > `DRUGS_AND_CONTROLLED_SUBSTANCES` > > Illegal drugs, drug paraphernalia (e.g. syringes, bongs), or the consumption of controlled substances. > [card] [Tobacco & vaping](#tobacco-vaping) > > `TOBACCO_AND_VAPING` > > The act of smoking or vaping, or the prominent display of tobacco and vaping products. > [card] [Alcohol](#alcohol) > > `ALCOHOL` > > Consumption of alcohol or the prominent display of open containers. Excludes background presence or sealed bottles. > [card] [Gambling](#gambling) > > `GAMBLING` > > Gambling activities such as casino games, slot machines, or sports betting. ### People & identity > [card] [Minors](#minors) > > `MINORS` > > Presence of clearly identifiable minors (outside of a CSAM context). > [card] [Identifiable person](#identifiable-person) > > `VISUALLY_IDENTIFIABLE_PERSON` > > A clearly identifiable human face, which may constitute personally identifiable information (PII). > [card] [Sensitive personal information](#sensitive-personal-information) > > `SENSITIVE_PERSONAL_INFORMATION` > > Clearly legible sensitive personal information (e.g. ID cards, credit cards). ### Codes & information > [card] [QR code](#qr-code) > > `QR_CODE` > > Presence of a QR code, which can be used to redirect users to external URLs. > [card] [Barcode](#barcode) > > `BAR_CODE` > > Presence of a traditional barcode (used for products). ### Other > [card] [Body waste](#body-waste) > > `BODY_WASTE` > > Human or animal waste products (e.g. faeces, vomit, urine, sperm). > [card] [Spoof & memes](#spoof-memes) > > `SPOOF_AND_MEMES` > > Images modified for humorous or satirical purposes (memes). *** ## Custom classifications Beyond the catalog above, Bodyguard can build **custom image classifications** tailored to your business. Custom classifications are created on request by the Bodyguard team, trained on your industry and visual context, and delivered typically within a few weeks. They are the right choice when you need to detect something specific that isn't covered by the standard taxonomy — a brand-specific visual element, an industry-specific risk, or a niche community behavior. If you have a need the standard taxonomy doesn't cover, [reach out to our team](https://www.bodyguard.ai/contact-us). # Text classifications Source: https://docs.bodyguard.ai/en/documentation/taxonomy/text-classifications A complete reference to Bodyguard's text taxonomy: the signals we use to describe content and the classifications we detect. Bodyguard reads every comment, message, or post and describes it with a set of labels. Those labels tell you **what kind of content it is**, **how serious it is**, and **who it is aimed at**. Together, they form the text taxonomy. The taxonomy has two layers: * **Moderation signals** — the *type*, *severity*, and *target* of the content. These qualify the content and help decide what to do with it. * **Classifications** — the detailed labels that describe precisely what the content contains (an insult, a scam, an advertisement, and so on). Both layers appear in every analysis result, whether you access Bodyguard through the dashboard or through the API. *** ## Moderation signals Three signals sit alongside the classifications to refine every moderation decision. The same classification can require a very different action depending on these signals — an insult marked `LOW` and aimed at no specific person is not handled like an insult marked `CRITICAL` and aimed at a user. ### Type The type is the overall nature of the content. It groups classifications into families so you can filter and prioritize at a glance. | Name | Technical value | Definition | | - | - | - | | Hate speech | `HATE_SPEECH` | Content that is explicitly violent or discriminatory — racism, LGBTQIA+ phobia, misogyny, ableism, moral or sexual harassment, and so on. | | Hateful | `HATEFUL` | Content with malicious intent such as insults, denigration, aggression, condescension, or body-shaming. | | Undesirable | `UNDESIRABLE` | Content that disturbs the experience of the community or the normal flow of conversation (spam, floods, ads). | | Criticism | `CRITICISM` | Content with a negative tone that is not hateful — typically complaints or unfavorable opinions. | | Neutral | `NEUTRAL` | Content that displays neither supportive nor problematic signals. | | Positive | `POSITIVE` | Supportive, encouraging, fair-play, or body-positive content. | | None | `NONE` | Content that doesn't belong to any of the categories above. | ### Severity Severity tells you how intense the content is. It's the main lever to adapt moderation: the same type of content can be merely inappropriate, genuinely harmful, or an immediate safety issue. | Name | Technical value | Definition | | - | - | - | | None | `NONE` | A message not considered harmful or offensive. | | Low | `LOW` | A message that may be offensive or inappropriate. | | Medium | `MEDIUM` | A message with the potential to cause harm or distress, but not urgent or severe. | | High | `HIGH` | A message likely to cause significant harm or damage, such as hate speech or discrimination against protected groups. | | Critical | `CRITICAL` | A message that poses an immediate threat to the safety or well-being of individuals or groups, such as content that incites violence. | ### Directed at The target tells you who the content is aimed at. The same insult directed at a public figure, a family member, or an entire community does not carry the same weight, and moderation policies often differ accordingly. | Name | Technical value | Definition | | - | - | - | | User | `USER` | The comment responds to the author of the original content or directly to another user. | | User's family | `USER_FAMILY` | The comment targets the family of the author of the original content or of another commenter. | | Single person | `SINGLE_PERSON` | The comment refers to a specific third person (typically named or referred to with he/she). | | Group | `GROUP` | The comment targets a group of individuals (a community, a demographic, a team). | | Everyone | `EVERYONE` | A general statement with no specific target or aimed at a wide range of people. | | Author of the comment | `AUTHOR_OF_COMMENT` | The commenter is talking about themselves, or including themselves in the sentiment. Important for signals such as self-harm. | | Haters | `HATERS` | The comment addresses critics or detractors of the author or of the brand. | | Entity | `ENTITY` | The comment refers to a company, brand, or other non-human entity. | | None | `NONE` | No target identified. | > [!NOTE] > > Moderation signals are returned on every analysis. Classifications — described below — are the actionable labels applied to each piece of content. *** ## Classifications Classifications are the detailed labels Bodyguard assigns to content. A single piece of content can carry **several classifications at once** — an insulting comment containing a phone number will be labeled both as an insult and as personal information. Classifications come in three tiers: * **General** — available to everyone. Used in moderation decisions and always returned when detected. * **Additional** — monitoring-only labels available on the Advanced plan and negotiated per contract. They enrich reporting and community insights without driving automated moderation. * **Custom** — classifications built on request for a specific customer. See [Custom classifications](#custom-classifications). Each card below shows the human-friendly name, the technical value used by the API, a short description, and a real example. ### Harmful content > [card] [Insult](#insult) > > `INSULT` · Hateful > > Disrespectful or abusive language targeting an individual. > > *"You all are cocksuckers!"* > [card] [Threat](#threat) > > `THREAT` · Hate speech > > Comments designed to intimidate or scare another person by promising to endanger them mentally or physically. > > *"I'm going to find you, and then I'm going to kill you."* > [card] [Racism](#racism) > > `RACISM` · Hate speech > > Discrimination or prejudice on the basis of race or ethnicity, typically towards minorities or marginalized groups. > > *"Go back to your country."* > [card] [Hatred](#hatred) > > `HATRED` · Hateful > > Comments expressing fundamental hostility, aimed at insulting or injuring a person, group, or entity. > > *"I hate you, you deserve nothing."* > [card] [Misogyny](#misogyny) > > `MISOGYNY` · Hate speech > > Discrimination or prejudice against women, including comments reflecting hateful patriarchal or transphobic attitudes. > > *"Go make me a sandwich, woman."* > [card] [Ableism](#ableism) > > `ABLEISM` · Hate speech > > Discrimination or prejudice against individuals living with disabilities — mental, psychological, or physical. > > *"The paralympics are shit."* > [card] [LGBTQIA+ phobia](#lgbtqiaplus-phobia) > > `LGBTQIAPLUS_PHOBIA` · Hate speech > > Discrimination or prejudice against people who identify as members of the LGBTQIA+ community. > > *"Trans people are sick in the head. They need therapy."* > [card] [Body shaming](#body-shaming) > > `BODY_SHAMING` · Hateful > > Discrimination or prejudice targeting someone's physical appearance or body modifications. > > *"You look like a fat, disgusting cow."* > [card] [Sexual harassment](#sexual-harassment) > > `SEXUAL_HARASSMENT` · Hate speech > > Inappropriate sexual comments or unwelcome advances, from flirtatious remarks to violent sexual fantasies. > > *"Wanna see you naked."* > [card] [Moral harassment](#moral-harassment) > > `MORAL_HARASSMENT` · Hate speech > > Comments and abusive behavior designed to undermine and humiliate a person. > > *"You really are useless aren't you."* > [card] [Trolling](#trolling) > > `TROLLING` · Hateful > > Confusing or manipulative messages posted to provoke a reaction. > > *"Just like Belgium at the World Cup."* > [card] [Vulgarity](#vulgarity) > > `VULGARITY` · Neutral > > Socially unpleasant, offensive, or obscene language without necessarily targeting anyone. > > *"Oh fuck, I can't believe this shit!"* > [card] [Doxxing](#doxxing) > > `DOXXING` · Hateful > > Publishing, or threatening to publish, someone's personal information or intimate content without consent. > > *"Here's her address: 1234 S Canal St, Chicago, IL 60607."* > [card] [Self-harm](#self-harm) > > `SELF_HARM` · Hate speech > > Content expressing distress, intent to harm oneself, or suicidal ideation. Flagged so teams can offer support — never removed automatically. > > *"I can't do this anymore. This life's not worth living."* > [card] [Reputation harm](#reputation-harm) > > `REPUTATION_HARM` · Hateful > > Comments intended to damage the reputation of an individual or an entity. > > *"\[Brand] is in cahoots with pedophiles."* > [card] [Geopolitical](#geopolitical) > > `GEOPOLITICAL` · Neutral > > Comments about politics, especially international relations influenced by geographical factors. > > *"#FreePalestine"* ### Explicit content > [card] [Sexually explicit](#sexually-explicit) > > `SEXUALLY_EXPLICIT` · Neutral > > Comments that talk about or detail sexual acts or genitalia. > > *"I'll let you bend me over."* > [card] [Pedophilia](#pedophilia) > > `PEDOPHILIA` · Hate speech > > Comments exhibiting or promoting sexual attraction towards minors. > > *"kali ur 13 but respectfully u are hot"* > [card] [Pedophilia reference](#pedophilia-reference) > > `PEDOPHILIA_REFERENCE` · Neutral > > Reference to child sexual abuse or illegal sexual activity with minors, excluding first-person statements of intent. > > *"Nude photos with under 12 year olds are available on the dark web."* > [card] [Drug references](#drug-references) > > `DRUG_EXPLICIT` · Neutral > > Comments that talk about or encourage the use of drugs. > > *"I'm so looking forward to dropping acid at music festivals this summer."* > [card] [Weapon references](#weapon-references) > > `WEAPON_EXPLICIT` · Neutral > > Comments that talk about or encourage the use of arms and weapons. Adapted to context — gaming weapons are treated differently from real-world promotion. > > *"I love my AK47 with its high capacity drum mag."* > [card] [Terrorism](#terrorism) > > `TERRORISM` · Hate speech > > Content supporting intimidation or coercion through the threat or perpetration of violence. > > *"Totally support his action, should have killed more of them."* > [card] [Terrorism reference](#terrorism-reference) > > `TERRORISM_REFERENCE` · Neutral > > Explicit mentions or references to acts of terrorism, terrorist organizations, or associated individuals. > > *"This is just like what ISIS did in 2015."* > [card] [Underage user](#underage-user) > > `UNDERAGE_USER` · Neutral > > Content where the user discloses or is understood to be underage. Age thresholds (under 13, 16, or 18) are configurable. > > *"Hi, I'm John and I'm 9 years old."* ### Spam & low quality > [card] [Spam](#spam) > > `SPAM` · Undesirable > > Undesirable comments sent repeatedly to a large number of people. Detection relies on time and repetition patterns, not just content. > > *Behaviour-based detection — no single example applies.* > [card] [Flood](#flood) > > `FLOOD` · Undesirable > > Comments meant to disturb a platform's normal operation, such as the mass publishing of senseless or repetitive text. > > *"ooooooooooooooooooooooooooooooooo"* > [card] [ASCII art flood](#ascii-art-flood) > > `FLOOD_ASCII_ART` · Undesirable > > Flood content composed of ASCII art characters. > > *"(╯°□°)╯︵ ┻━┻ ┻━┻ ︵ ╯(°□° ╯)"* > [card] [Emoji repetition](#emoji-repetition) > > `FLOOD_EMOJI_REPETITION` · Undesirable > > Flood content consisting of repeated emojis. > > *"😂😂😂😂😂😂😂😂😂😂😂😂😂😂😂"* > [card] [Stylized text flood](#stylised-text-flood) > > `FLOOD_STYLISED_TEXT` · Undesirable > > Flood content using stylized, decorated, or Unicode-manipulated characters. > > *"hello everyone hello everyone"* > [card] [Uppercase flood](#uppercase-flood) > > `FLOOD_UPPERCASE_TEXT` · Undesirable > > Flood content written entirely or predominantly in uppercase. > > *"WHY IS NOBODY ANSWERING ME WHY IS NOBODY ANSWERING ME"* > [card] [Word repetition](#word-repetition) > > `FLOOD_WORD_REPETITION` · Undesirable > > Flood content consisting of the same word or phrase repeated. > > *"come on come on come on come on come on come on"* > [card] [Unknown text flood](#unknown-text-flood) > > `FLOOD_UNKNOWN_TEXT` · Undesirable > > Flood content that does not fit a more specific flood subtype. > > *"asdfjkl; asdfjkl; asdfjkl; asdfjkl;"* > [card] [Useless](#useless) > > `USELESS` · Undesirable > > Comments without meaningful content that do not add to or enrich the conversation. > > *"1st person in the comment section"* > [card] [Scam](#scam) > > `SCAM` · Undesirable > > Deceptive messages designed to trick people out of money, personal information, or account access. > > *"Click my link "Millionaire 111" so that you too can make money."* > [card] [Link](#link) > > `LINK` · Neutral > > Comments containing a link to another page or site. > > *"[https://www.bodyguard.ai](https://www.bodyguard.ai)"* > [card] [Forbidden link](#forbidden-link) > > `FORBIDDEN_LINK` · Undesirable > > Comments containing a link blacklisted for your channel. > > *Triggered when a link matches your configured blacklist.* > [card] [Forbidden language](#forbidden-language) > > `FORBIDDEN_LANGUAGE` · Undesirable > > Comments written in a language blacklisted for your channel. > > *Triggered when content is outside your configured language allowlist.* > [card] [Platform bypass](#platform-bypass) > > `PLATFORM_BYPASS` · Undesirable > > Comments inviting users to leave the current platform and continue the conversation elsewhere. > > *"Wanna talk on snap?"* > [card] [Dating solicitation](#dating-solicitation) > > `DATING` · Neutral > > Comments indicating intent or interest in pursuing romantic or sexual relationships. > > *"Are you single? I'd love to get to know you better 😉"* ### Personal information (PII) PII sub-labels are returned alongside the parent `PII` label. For example, a comment containing an email address is labeled with both `PII` and `PII_EMAIL`. > [card] [Personal information](#personal-information) > > `PII` · Neutral > > The act of publishing, willingly or not, personally identifiable information online. > > *"Actually my number is 9958592028, please call me."* > [card] [Email address](#email-address) > > `PII_EMAIL` · Neutral > > A comment containing a personal email address. > > *"Reach me at [john.doe@gmail.com](mailto:john.doe@gmail.com) anytime."* > [card] [Physical address](#physical-address) > > `PII_PHYSICAL_ADDRESS` · Neutral > > A comment containing a home or physical address. > > *"I'm at 12 Oak Street, Springfield — come find me."* > [card] [Phone number](#phone-number) > > `PII_PHONE_NUMBER` · Neutral > > A comment containing a personal phone number. > > *"Call me on +1 555 234 5678."* > [card] [Bank information](#bank-information) > > `PII_BANK_INFORMATION` · Neutral > > A comment containing banking details such as account or card numbers. > > *"My IBAN is FR76 3000 6000 0112 3456 7890 189."* > [card] [National ID](#national-id) > > `PII_NATIONAL_ID` · Neutral > > A comment containing a national identification number or document reference. > > *"My SSN is 078-05-1120."* > [card] [Registration plate](#registration-plate) > > `PII_REGISTRATION_PLATE` · Neutral > > A comment containing a vehicle registration plate. > > *"That's the guy — his plate is AB-123-CD."* > [card] [Social handle](#social-handle) > > `PII_SOCIAL_HANDLE` · Neutral > > A comment containing a social media handle pointing to a personal account. > > *"Find me on Instagram @john.doe.real"* > [card] [Real names](#real-names) > > `PII_REAL_NAMES` · Neutral > > A comment containing a real first or last name. > > *"My name is Jean Dupont."* ### Advertising ADS sub-labels are returned alongside the parent `ADS` label when the type of advertisement is identified. > [card] [Advertisement](#advertisement) > > `ADS` · Undesirable > > Promotional messages advertising products, services, events, or personal brands. > > *"Hello, please visit my page, I need a follower 😉"* > [card] [Collaboration request](#collaboration-request) > > `ADS_COLLAB_REQUEST` · Undesirable > > Offers to collaborate with other users on social media. > > *"Hey, I'd love to collab with you — DM me!"* > [card] [Direct sale](#direct-sale) > > `ADS_DIRECT_SALE` · Undesirable > > Explicit attempts to sell products or services directly to users. > > *"Selling brand new AirPods Pro, €150. DM to buy."* > [card] [Profile promotion](#profile-promotion) > > `ADS_PROFILE` · Undesirable > > Attempts to drive other users to the commenter's social media profile. > > *"Follow my page for daily tips 👇 @mypage"* > [card] [Promo code](#promo-code) > > `ADS_PROMO_CODE` · Undesirable > > Offers of discounts or promo codes for products and services. > > *"Use code SAVE20 for 20% off your first order!"* > [card] [Self-promotion](#self-promotion) > > `ADS_SELF_PROMOTION` · Undesirable > > Attempts to get users to engage with the commenter's events or projects. > > *"I just dropped my new track — link in bio 🔥"* > [card] [Adult content ad](#adult-content-ad) > > `ADS_SEXUAL_CONTENT` · Undesirable > > Explicit attempts to sell sexual material or services. > > *"Check my OnlyFans for exclusive content 🔞 link in bio."* > [card] [Ticket sale](#ticket-sale) > > `ADS_TICKET_SALE` · Undesirable > > Offers to sell tickets to events. > > *"Selling 2 floor tickets for the concert Saturday, €80 each."* > [card] [Betting](#betting) > > `BETTING` · Neutral > > Comments including links to betting websites. > > *"Best tips for all today's games — join the link below."* > [card] [Streaming link](#streaming-link) > > `STREAMING_LINK` · Neutral > > Comments with links to illegal live event broadcasts. > > *"Watch the match live for free here → bit.ly/stream99"* > [card] [Plagiarism](#plagiarism) > > `PLAGIARISM` · Neutral > > Comments raising concerns or accusing a brand of stealing concepts or ideas from other brands or creators. > > *"Copying other brands won't make you successful. Come up with your own ideas."* ### Positive signals > [card] [Supportive](#supportive) > > `SUPPORTIVE` · Positive > > Comments showing appreciation for a user or their content. > > *"This product is amazing."* > [card] [Encouragement](#encouragement) > > `ENCOURAGEMENT` · Positive > > Comments giving an individual or entity your support. > > *"Keep it up guys, you can do it!!!"* > [card] [Fair play](#fair-play) > > `FAIRPLAY` · Positive > > Comments expressing fairness and honor, following the spirit of the rules. > > *"GG guys!"* > [card] [Neutral](#neutral) > > `NEUTRAL` · Neutral > > Comments that do not display any supportive or problematic content. > > *"It's gonna rain tomorrow."* ### Brand & community > [card] [Negative criticism](#negative-criticism) > > `NEGATIVE_CRITICISM` · Criticism > > Critiques of a user's content or actions without the intent of harming the user. > > *"I don't like this bag, I think it's not fashionable at all."* > [card] [Boycott](#boycott) > > `BOYCOTT` · Criticism > > Comments urging users to stop buying, using, or supporting a company's products or services. > > *"No one should buy from this brand ever again."* > [card] [Defamatory](#defamatory) > > `DEFAMATORY` · Hateful > > False statements of fact presented as true, with intent or effect of damaging reputation. > > *"I heard they tested their products on children without consent."* > [card] [Customer complaint](#customer-complaint) > > `CUSTOMER_COMPLAINTS` · Neutral > > Comments where a customer criticizes the brand's quality, representatives, or service. > > *"No call back; can't ever speak with management!!! Poor customer service!"* > [card] [Customer request](#customer-request) > > `CUSTOMER_REQUESTS` · Neutral > > Customer enquiries and requests for assistance about a brand's service or product. > > *"Can you please help me identify the name of this particular bag?!"* > [card] [Customer satisfaction](#customer-satisfaction) > > `CUSTOMER_SATISFACTION` · Neutral > > Comments where a client expresses appreciation for the brand's service, representatives, or product. > > *"I met this amazing sales person, made shopping there very easy."* > [card] [Health concerns](#health-concerns) > > `HEALTH_CONCERNS` · Neutral > > Reports of negative physical reactions, health concerns, or safety risks related to a product. > > *"Your product gave me an allergic reaction. Thanks for nothing!"* ### Context & topics > [!NOTE] > > All classifications below are **Additional** — monitoring-only labels that provide community insights. > [card] [Politics](#politics) > > `POLITICS` · Neutral > > Comments related to or mentioning governments, political parties, and political figures. > > *"Imagine people using social media to discourage artists after speaking out against Trump."* > [card] [Finance](#finance) > > `FINANCE` · Neutral > > Comments related to monetary and economic issues — management, impact, and ethics of financial practices. > > *"Their prices keep rising while quality drops — classic corporate greed."* > [card] [Market manipulation](#market-manipulation) > > `MARKET_MANIPULATION` · Undesirable > > Messages that promote, coordinate, facilitate, or falsely represent activity with the intention to artificially influence financial assets. > > *"I’m on the board. Buy before the decision is announced."* > [card] [Environment](#environment) > > `ENVIRONMENT` · Neutral > > Concerns or campaigns regarding ecological issues tied to a brand's production processes. > > *"This brand's packaging is completely non-recyclable — shameful."* > [card] [Animal well-being](#animal-welfare) > > `ANIMAL_WELL_BEING` · Neutral > > Concerns or campaigns regarding a brand's use of animal products. > > *"I won't buy from them until they stop using fur."* > [card] [Cybersecurity](#cybersecurity) > > `CYBERSECURITY` · Neutral > > Comments related to digital security topics. > > *"@brand you had a data breach — someone tried to order \$166 worth of product and my bank caught it!"* > [card] [Pricing](#pricing) > > `PRICING` · Neutral > > Comments criticizing high prices or price increases of a brand's products. > > *"€400 for a basic t-shirt? Completely out of touch."* > [card] [Sexting](#sexting) > > `SEXTING` · Neutral > > Sexual comments or invitations that are playful or respectful, within mature-user norms. Differs from sexual harassment in that it does not include violent or degrading content. > > *"You looked incredible in that photo last night 🔥"* > [card] [Cheat reference](#cheat-reference) > > `CHEAT_REFERENCE` · Neutral > > Mentions or references to cheating websites or practices, primarily in gaming contexts. > > *"Report mojo for cheats — pretty sure he is using one."* *** ## Custom classifications Beyond the catalog above, Bodyguard can build **custom classifications** tailored to your business. Custom classifications are created on request by the Bodyguard NLP team, trained on your industry and languages, and delivered typically within two weeks. They are the right choice when you need to detect something specific that isn't covered by the general or additional classifications — a brand-specific terminology, an industry-specific risk, or a niche community behavior. If you have a need the standard taxonomy doesn't cover, [reach out to our team](https://www.bodyguard.ai/contact-us). # Username classifications Source: https://docs.bodyguard.ai/en/documentation/taxonomy/username-classifications A complete reference to Bodyguard's username taxonomy: the classifications we detect in username strings. Bodyguard analyzes every username string and assigns it one or more labels that tell you precisely what was detected — from hate speech and explicit content to personally identifiable information. Each label is a **classification**. Unlike text content, usernames are not qualified by additional signals such as type, severity, or target. The taxonomy is flat: each classification stands on its own and is returned whenever Bodyguard detects the corresponding content. > [!NOTE] > > Username analysis is context-aware. Bodyguard considers the full string before applying a classification — for example, a term that may imply drug dealing in isolation (such as "plug") is not flagged when it clearly forms part of an unrelated compound (such as "spark_plug"). *** ## Classifications Each card below shows the human-friendly name, the technical value used by the API, a short description, and an illustrative example. ### Harmful content > [card] [Body shaming](#body-shaming) > > `BODY_SHAMING` > > Mocks, degrades, or attacks physical appearance or weight. > > *"fatuglyloser"* > [card] [Extremism](#extremism) > > `EXTREMISM` > > Promotes terrorist organizations, violent extremism, or radicalization. > > *"jihad4lyfe"* > [card] [Insult](#insult) > > `INSULT` > > Contains direct, targeted profanity or degrading insults meant to offend. > > *"ur_a_moron99"* > [card] [LGBTQIA+ phobia](#lgbtqiaplus-phobia) > > `LGBTQIAPLUS_PHOBIA` > > Contains slurs, mockery, or hate speech directed at the LGBTQIA+ community. > > *"nogays_allowed"* > [card] [Misogyny](#misogyny) > > `MISOGYNY` > > Promotes hatred, prejudice, or harmful stereotyping against women. > > *"womenareuseless"* > [card] [Racism](#racism) > > `RACISM` > > Contains racial slurs, stereotypes, or hate speech based on race or ethnicity. > > *"whitepower88"* ### Explicit content > [card] [Drug references](#drug-references) > > `DRUG_EXPLICIT` > > Promotes or references illegal drugs, narcotics, or drug dealing. > > *"cocainecowboy\_"* > [card] [Sexually explicit](#sexually-explicit) > > `SEXUALLY_EXPLICIT` > > Contains explicit sexual acts, crude anatomical references, or pornography. > > *"xxxhotgirl69"* ### Personal information (PII) > [card] [Personal information](#personal-information) > > `PII` > > Contains sensitive Personally Identifiable Information such as phone numbers, email addresses, physical addresses, or government IDs. > > *"john.doe.0612345678"* > [!NOTE] > > Standard first/last name combinations without other identifiers are not flagged — they default to `NEUTRAL`. ### Neutral > [card] [Neutral](#neutral) > > `NEUTRAL` > > Does not violate any guidelines. The default classification for benign, everyday, or ambiguous usernames. > > *"cool_gamer_99"*