> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bodyguard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.bodyguard.ai/en/api-reference/concepts.md#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 `<your-api-key>` and `<your-channel-id>` with values provided by Bodyguard.

```bash cURL theme={null}
curl -X POST https://api.bodyguard.ai/analyze/v1/text \
  -H "Authorization: ApiKey <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "<your-channel-id>",
    "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 <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channelId: "<your-channel-id>",
    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 <your-api-key>",
        "Content-Type": "application/json",
    },
    json={
        "channelId": "<your-channel-id>",
        "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":   "<your-channel-id>",
		"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 <your-api-key>")
	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](https://docs.bodyguard.ai/en/documentation/taxonomy/text-classifications.md).

## 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 <your-api-key>` |
| `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](https://docs.bodyguard.ai/en/documentation/how-to/get-api-key.md) 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": "<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](https://docs.bodyguard.ai/en/api-reference/concepts.md)
>
> Learn the core building blocks of the Bodyguard API: organizations, sources, channels, references, and publication dates.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.