This document is a guide to help you test the Azure AI Content Safety API with different request examples. The API is used to analyze harmful content in images and text, supporting four categories: Hate, SelfHarm, Sexual, and Violence.

## How to report bugs:

## Base URL

The base URL for the API should be in the following format:

https://{endpoint}/contentsafety

Replace `{endpoint}` with the endpoint provided by Azure Cognitive Services.

## API Version

For all requests, include the `api-version` query parameter with the value `2023-10-01`.

## Endpoints
### 1. Analyze Text

This endpoint analyzes potentially harmful text content, returning results in categories according to the specified output type.

#### Request

POST /text:analyze?api-version=2023-10-01

**Headers:**

- `Content-Type: application/json`

**Body:**

{
  "text": "The text to analyze goes here...",
  "categories": [
    "Hate",
    "SelfHarm",
    "Sexual",
    "Violence"
  ],
  "blocklistNames": [
    "Blocklist1",
    "Blocklist2"
  ],
  "haltOnBlocklistHit": true,
  "outputType": "FourSeverityLevels"
}

**Fields:**

- `text`: Required. The text to analyze. Maximum length: 10,000 Unicode characters.
- `categories`: Optional. Categories to analyze. If not provided, a default set of results for all categories will be returned.
- `blocklistNames`: Optional. Names of blocklists to use during analysis.
- `haltOnBlocklistHit`: Optional. If `true`, further analyses of harmful content will not be performed if blocklists are hit. If `false`, all analyses will be performed regardless of blocklist hits.
- `outputType`: Optional. The type of output. Default is `FourSeverityLevels`. You could also try with `EightSeverityLevels`.

#### Response

`Status: 200 OK`

{
  "blocklistsMatch": [
    {
      "blocklistName": "Blocklist1",
      "blocklistItemId": "example-item-id-1",
      "blocklistItemText": "Example text 1 from blocklist"
    }
  ],
  "categoriesAnalysis": [
    {
      "category": "Hate",
      "severity": 2
    },
    {
      "category": "SelfHarm",
      "severity": 0
    },
    {
      "category": "Sexual",
      "severity": 4
    },
    {
      "category": "Violence",
      "severity": 6
    }
  ]
}

### 2. Analyze Image

This endpoint analyzes potentially harmful image content, returning results in categories according to the specified output type.

#### Request

POST /image:analyze?api-version=2023-10-01

**Headers:**

- `Content-Type: application/json`

**Body:**

{
  "image": {
    "content": "base64EncodedImageData",
    "blobUrl": "https://url.to/the/image.blob"
  },
  "categories": [
    "Hate",
    "SelfHarm",
    "Sexual",
    "Violence"
  ],
  "outputType": "FourSeverityLevels"
}

**Fields:**

- `image`: Required. One of `content` (base64 encoded image data) or `blobUrl` (URL of image blob) must be provided.
- `content`: Optional. The base64-encoded image content. Maximum image size: 2048 x 2048 pixels, not exceeding 4 MB. Minimum image size: 50 x 50 pixels.
- `blobUrl`: Optional. The URL of the image blob. Follows same size restrictions as `content`.
- `categories`: Optional. Categories to analyze. If not provided, a default set of results for all categories will be returned.
- `outputType`: Optional. The type of output. Default is `FourSeverityLevels`. You could also try with `EightSeverityLevels`.

#### Response

`Status: 200 OK`

{
  "categoriesAnalysis": [
    {
      "category": "Hate",
      "severity": 2
    },
    {
      "category": "SelfHarm",
      "severity": 0
    },
    {
      "category": "Sexual",
      "severity": 4
    },
    {
      "category": "Violence",
      "severity": 6
    }
  ]
}

## Blocklist related endpoints

The following endpoints are related to managing blocklists and blocklist items:

- `GET /text/blocklists`: Get all text blocklists details.
- `GET /text/blocklists/{blocklistName}`: Get text blocklist by blocklistName.
- `PATCH /text/blocklists/{blocklistName}`: Create or update a text blocklist.
- `DELETE /text/blocklists/{blocklistName}`: Delete a text blocklist by blocklistName.
- `POST /text/blocklists/{blocklistName}:addOrUpdateBlocklistItems`: Add or update blocklist items to a text blocklist.
- `POST /text/blocklists/{blocklistName}:removeBlocklistItems`: Remove blocklist items from a text blocklist.
- `GET /text/blocklists/{blocklistName}/blocklistItems`: Get all blocklist items by blocklistName.
- `GET /text/blocklists/{blocklistName}/blocklistItems/{blocklistItemId}`: Get a blocklistItem by blocklistName and blocklistItemId.

## Get All Text Blocklists
Endpoint: `/text/blocklists`

### Description:
Get all text blocklists details.

### API Example Request:

GET {endpoint}/contentsafety/text/blocklists?api-version=2023-01-01
Headers:
"x-ms-client-request-id": "{your-request-id}",
"Content-Type": "application/json",
"Authorization": "Bearer {your-token}",
"Ocp-Apim-Subscription-Key": "{your-subscription-key}"

### API Example Response:

{
  "value": [
    {
      "blocklistName": "blocklist1",
      "description": "Example blocklist 1 for harmful content"
    },
    {
      "blocklistName": "blocklist2",
      "description": "Example blocklist 2 for harmful content"
    }
  ]
}

***

## Get Text Blocklist by Blocklist Name
Endpoint: `/text/blocklists/{blocklistName}`

### Description:
Returns text blocklist details.

### API Example Request:

GET {endpoint}/contentsafety/text/blocklists/blocklist1?api-version=2023-01-01
Headers:
"x-ms-client-request-id": "{your-request-id}",
"Content-Type": "application/json",
"Authorization": "Bearer {your-token}",
"Ocp-Apim-Subscription-Key": "{your-subscription-key}"

### API Example Response:

{
  "blocklistName": "blocklist1",
  "description": "Example blocklist 1 for harmful content"
}

### Restrictions:
- blocklistName: maximum length 64, pattern "^[0-9A-Za-z._~-]+$"

***

## Create or Update Text Blocklist
Endpoint: `/text/blocklists/{blocklistName}`

### Description:
Updates a text blocklist. If the blocklistName does not exist, a new blocklist will be created.

### API Example Request:

PATCH {endpoint}/contentsafety/text/blocklists/blocklist1?api-version=2023-01-01
Headers:
"x-ms-client-request-id": "{your-request-id}",
"Content-Type": "application/json",
"Authorization": "Bearer {your-token}",
"Ocp-Apim-Subscription-Key": "{your-subscription-key}"

Body:
{
  "description": "Updated blocklist 1 for harmful content"
}

### API Example Response:

{
  "blocklistName": "blocklist1",
  "description": "Updated blocklist 1 for harmful content"
}

### Restrictions:
- blocklistName: maximum length 64, pattern "^[0-9A-Za-z._~-]+$"

***

## Delete Text Blocklist by Blocklist Name
Endpoint: `/text/blocklists/{blocklistName}`

### Description:
Deletes a text blocklist.

### API Example Request:

DELETE {endpoint}/contentsafety/text/blocklists/blocklist1?api-version=2023-01-01
Headers:
"x-ms-client-request-id": "{your-request-id}",
"Content-Type": "application/json",
"Authorization": "Bearer {your-token}",
"Ocp-Apim-Subscription-Key": "{your-subscription-key}"

### API Example Response:
`HTTP 204 No Content`

### Restrictions:
- blocklistName: maximum length 64, pattern "^[0-9A-Za-z._~-]+$"

***

## Add or Update Blocklist Items to Text Blocklist
Endpoint: `/text/blocklists/{blocklistName}:addOrUpdateBlocklistItems`

### Description:
Add or update blocklistItems to a text blocklist. You can add or update at most 100 blocklistItems in one request.

### API Example Request:

POST {endpoint}/contentsafety/text/blocklists/blocklist1:addOrUpdateBlocklistItems?api-version=2023-01-01
Headers:
"x-ms-client-request-id": "{your-request-id}",
"Content-Type": "application/json",
"Authorization": "Bearer {your-token}",
"Ocp-Apim-Subscription-Key": "{your-subscription-key}"

Body:
{
  "blocklistItems": [
    {
      "text": "example-word-1",
      "description": "Example blocklist item"
    }
  ]
}

### API Example Response:

{
  "blocklistItems": [
    {
      "blocklistItemId": "5c68ccb9-a926-464b-8ed8-9ed0b96c6838",
      "description": "Example blocklist item",
      "text": "example-word-1"
    }
  ]
}

### Restrictions:
- Maximum of 100 blocklistItems in one request

***

## Remove Blocklist Items from Text Blocklist
Endpoint: `/text/blocklists/{blocklistName}:removeBlocklistItems`

### Description:
Remove blocklistItems from a text blocklist. You can remove at most 100 BlocklistItems in one request.

### API Example Request:

POST {endpoint}/contentsafety/text/blocklists/blocklist1:removeBlocklistItems?api-version=2023-01-01 
Headers:
"x-ms-client-request-id": "{your-request-id}",
"Content-Type": "application/json",
"Authorization": "Bearer {your-token}",
"Ocp-Apim-Subscription-Key": "{your-subscription-key}"

Body:
{
  "blocklistItemIds": [
    "5c68ccb9-a926-464b-8ed8-9ed0b96c6838"
  ]
}

### API Example Response:
`HTTP 204 No Content`

### Restrictions:
- Maximum of 100 blocklistItemIds in one request.

***

## Get All Blocklist Items by Blocklist Name
Endpoint: `/text/blocklists/{blocklistName}/blocklistItems`

### Description:
Get all blocklistItems in a text blocklist.

### API Example Request:

GET {endpoint}/contentsafety/text/blocklists/blocklist1/blocklistItems?api-version=2023-01-01        
Headers:
"x-ms-client-request-id": "{your-request-id}",
"Content-Type": "application/json",
"Authorization": "Bearer {your-token}",
"Ocp-Apim-Subscription-Key": "{your-subscription-key}"

### API Example Response:

{
  "value": [
    {
      "blocklistItemId": "5c68ccb9-a926-464b-8ed8-9ed0b96c6838",
      "description": "Example blocklist item",
      "text": "example-word-1"
    }
  ]
}

***

## Get Blocklist Item by Blocklist Name and Blocklist Item ID
Endpoint: `/text/blocklists/{blocklistName}/blocklistItems/{blocklistItemId}`

### Description:
Get blocklistItem by blocklistName and blocklistItemId from a text blocklist.

### API Example Request:

GET {endpoint}/contentsafety/text/blocklists/blocklist1/blocklistItems/5c68ccb9-a926-464b-8ed8-9ed0b96c6838?api-version=2023-01-01
Headers:
"x-ms-client-request-id": "{your-request-id}",
"Content-Type": "application/json",
"Authorization": "Bearer {your-token}",
"Ocp-Apim-Subscription-Key": "{your-subscription-key}"

### API Example Response:

{
  "blocklistItemId": "5c68ccb9-a926-464b-8ed8-9ed0b96c6838",
  "description": "Example blocklist item",
  "text": "example-word-1"
}

***