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

# Rich Content Types

> Complete guide to the 5 content types supported by HITL.sh requests — markdown, image, file, video, and audio

# Rich Content Types

HITL.sh review requests support 5 content types that control how content is rendered for human reviewers on the web dashboard and mobile app. The `type` field on every request selects which renderer is used.

## Overview

> [card] Markdown
>
> Rich text with headings, bold, code blocks, tables, and links

> [card] Image
>
> Inline image display with zoom support and optional S3 upload

> [card] File
>
> Document review with inline PDF annotator and download links

> [card] Video
>
> Embedded video player supporting YouTube, Vimeo, and direct files

> [card] Audio
>
> Embedded audio player supporting SoundCloud, Spotify, and direct files

## Content Type Comparison

| Type | URL Field | Upload Available | Inline Render |
| - | - | - | - |
| `markdown` | — (uses `request_text`) | — | Yes (markdown parser) |
| `image` | `image_url` | Yes (S3, max 10 MB) | Yes (with zoom) |
| `file` | `file_url` | Yes (S3, max 50 MB) | PDFs only (annotator) |
| `video` | `video_url` | No (link only) | Yes (embedded player) |
| `audio` | `audio_url` | No (link only) | Yes (embedded player) |

## Markdown (Default)

Render markdown-formatted text directly in `request_text`. This is the default type and requires no additional URL fields.

**type** `string` *required*

Set to `"markdown"`

**request\_text** `string` *required*

The markdown content to display (max 2000 characters). Supports headings, bold, italic, code blocks, tables, lists, and links.

### Example

```python Python theme={null}
request_data = {
    "processing_type": "deferred",
    "type": "markdown",
    "priority": "medium",
    "request_text": "## Content Review\n\nPlease review the following paragraph and flag any factual errors:\n\n> The Eiffel Tower was built in **1889** for the World's Fair.\n\nIs this accurate?",
    "response_type": "boolean",
    "response_config": {},
    "default_response": False,
    "platform": "api"
}

response = requests.post(
    f"https://api.hitl.sh/v1/api/loops/{loop_id}/requests",
    headers={"Authorization": f"Bearer {api_key}"},
    json=request_data
)
```

```javascript Node.js theme={null}
const requestData = {
    processing_type: "deferred",
    type: "markdown",
    priority: "medium",
    request_text: "## Content Review\n\nPlease review the following paragraph and flag any factual errors:\n\n> The Eiffel Tower was built in **1889** for the World's Fair.\n\nIs this accurate?",
    response_type: "boolean",
    response_config: {},
    default_response: false,
    platform: "api"
};

const response = await axios.post(
    `https://api.hitl.sh/v1/api/loops/${loopId}/requests`,
    requestData,
    { headers: { Authorization: `Bearer ${apiKey}` }}
);
```

```bash cURL theme={null}
curl -X POST https://api.hitl.sh/v1/api/loops/{loop_id}/requests \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "processing_type": "deferred",
    "type": "markdown",
    "priority": "medium",
    "request_text": "## Content Review\n\nPlease review the following paragraph and flag any factual errors:\n\n> The Eiffel Tower was built in **1889** for the World'"'"'s Fair.\n\nIs this accurate?",
    "response_type": "boolean",
    "response_config": {},
    "default_response": false,
    "platform": "api"
  }'
```

## Image

Display an externally-hosted image inline for visual review tasks such as content moderation, quality assessment, or labeling.

**type** `string` *required*

Set to `"image"`

**image\_url** `string` *required*

Publicly accessible URL to the image

**request\_text** `string` *required*

The question or instructions for the reviewer

**Supported formats:** JPEG, PNG, GIF, WebP

**Upload:** You can host images on HITL.sh using the [Upload Image](https://docs.hitl.sh/api-reference/upload/upload-image.md) endpoint (S3-backed, max 10 MB). Use the returned URL as your `image_url`.

**Rendering:** Displayed inline above the response form. Supports pinch-to-zoom on mobile and click-to-zoom on web.

### Example

```python Python theme={null}
request_data = {
    "processing_type": "time-sensitive",
    "type": "image",
    "priority": "high",
    "request_text": "Does this product photo meet our quality standards? Check for correct background, lighting, and framing.",
    "image_url": "https://cdn.example.com/products/item-4521.jpg",
    "timeout_seconds": 1800,
    "response_type": "boolean",
    "response_config": {},
    "default_response": False,
    "platform": "api",
    "callback_url": "https://myapp.com/webhooks/hitl-response"
}
```

```javascript Node.js theme={null}
const requestData = {
    processing_type: "time-sensitive",
    type: "image",
    priority: "high",
    request_text: "Does this product photo meet our quality standards? Check for correct background, lighting, and framing.",
    image_url: "https://cdn.example.com/products/item-4521.jpg",
    timeout_seconds: 1800,
    response_type: "boolean",
    response_config: {},
    default_response: false,
    platform: "api",
    callback_url: "https://myapp.com/webhooks/hitl-response"
};
```

```bash cURL theme={null}
curl -X POST https://api.hitl.sh/v1/api/loops/{loop_id}/requests \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "processing_type": "time-sensitive",
    "type": "image",
    "priority": "high",
    "request_text": "Does this product photo meet our quality standards?",
    "image_url": "https://cdn.example.com/products/item-4521.jpg",
    "timeout_seconds": 1800,
    "response_type": "boolean",
    "response_config": {},
    "default_response": false,
    "platform": "api"
  }'
```

## File / Document

Attach a document for reviewers to read or annotate. PDFs render with an inline annotator on the web dashboard; other file types provide a download link.

**type** `string` *required*

Set to `"file"`

**file\_url** `string` *required*

Publicly accessible URL to the document

**file\_type** `string`

MIME type of the document (e.g., `"application/pdf"`)

**file\_name** `string`

Original filename shown to the reviewer (e.g., `"Q4-report.pdf"`)

**request\_text** `string` *required*

The question or instructions for the reviewer

**Supported upload formats:** PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, CSV, TXT (max 50 MB)

**Upload:** Use the [Upload Document](https://docs.hitl.sh/api-reference/upload/upload-document.md) endpoint to host files on HITL.sh.

**Rendering:**

* **PDFs:** Inline annotator on web dashboard with highlight and comment tools
* **All other types:** Download link with filename and detected MIME type

### PDF Annotations

When the file is a PDF, the web dashboard activates an inline annotator. Reviewers can:

* Highlight text passages
* Add comment pins at specific positions
* Draw freeform shapes over the document
* Reply to other reviewers' annotations

Annotations are saved alongside the reviewer's response and returned in the response payload.

> [!NOTE]
>
> PDF annotations are only available on the web dashboard. The mobile app shows a download link for all file types including PDFs.

### Example

```python Python theme={null}
request_data = {
    "processing_type": "deferred",
    "type": "file",
    "priority": "medium",
    "request_text": "Please review Section 3 of this contract and flag any clauses that require legal approval before signing.",
    "file_url": "https://cdn.example.com/contracts/vendor-agreement-2026.pdf",
    "file_type": "application/pdf",
    "file_name": "vendor-agreement-2026.pdf",
    "response_type": "text",
    "response_config": {
        "placeholder": "Describe any clauses that need review...",
        "min_length": 20,
        "max_length": 1000,
        "required": True
    },
    "default_response": "No issues found",
    "platform": "api"
}
```

```javascript Node.js theme={null}
const requestData = {
    processing_type: "deferred",
    type: "file",
    priority: "medium",
    request_text: "Please review Section 3 of this contract and flag any clauses that require legal approval before signing.",
    file_url: "https://cdn.example.com/contracts/vendor-agreement-2026.pdf",
    file_type: "application/pdf",
    file_name: "vendor-agreement-2026.pdf",
    response_type: "text",
    response_config: {
        placeholder: "Describe any clauses that need review...",
        min_length: 20,
        max_length: 1000,
        required: true
    },
    default_response: "No issues found",
    platform: "api"
};
```

```bash cURL theme={null}
curl -X POST https://api.hitl.sh/v1/api/loops/{loop_id}/requests \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "processing_type": "deferred",
    "type": "file",
    "priority": "medium",
    "request_text": "Please review Section 3 of this contract.",
    "file_url": "https://cdn.example.com/contracts/vendor-agreement-2026.pdf",
    "file_type": "application/pdf",
    "file_name": "vendor-agreement-2026.pdf",
    "response_type": "text",
    "response_config": {
        "placeholder": "Describe any clauses that need review...",
        "min_length": 20,
        "max_length": 1000,
        "required": true
    },
    "default_response": "No issues found",
    "platform": "api"
  }'
```

## Video

Embed a video player for reviewers to watch before responding. Supports major streaming platforms and direct video file links. No video hosting is provided — link to an externally-hosted video.

**type** `string` *required*

Set to `"video"`

**video\_url** `string` *required*

URL to the video

**request\_text** `string` *required*

The question or instructions for the reviewer

**Supported platforms and formats:**

| Source | Examples |
| - | - |
| YouTube | `https://www.youtube.com/watch?v=...` |
| Vimeo | `https://vimeo.com/...` |
| Direct MP4 | `https://cdn.example.com/video.mp4` |
| Direct WebM | `https://cdn.example.com/video.webm` |
| Direct MOV | `https://cdn.example.com/video.mov` |

**Rendering:** YouTube and Vimeo use their native iframe embeds. Direct video files use the browser's native `<video>` element on both web and mobile.

### Example

```python Python theme={null}
request_data = {
    "processing_type": "time-sensitive",
    "type": "video",
    "priority": "high",
    "request_text": "Watch this product demo video (approx. 3 minutes) and rate it on clarity and professionalism.",
    "video_url": "https://cdn.example.com/demos/product-v2.mp4",
    "timeout_seconds": 7200,
    "response_type": "rating",
    "response_config": {
        "scale_min": 1,
        "scale_max": 5
    },
    "default_response": 3,
    "platform": "api"
}
```

```javascript Node.js theme={null}
const requestData = {
    processing_type: "time-sensitive",
    type: "video",
    priority: "high",
    request_text: "Watch this product demo video (approx. 3 minutes) and rate it on clarity and professionalism.",
    video_url: "https://cdn.example.com/demos/product-v2.mp4",
    timeout_seconds: 7200,
    response_type: "rating",
    response_config: {
        scale_min: 1,
        scale_max: 5
    },
    default_response: 3,
    platform: "api"
};
```

```bash cURL theme={null}
curl -X POST https://api.hitl.sh/v1/api/loops/{loop_id}/requests \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "processing_type": "time-sensitive",
    "type": "video",
    "priority": "high",
    "request_text": "Watch this product demo video and rate it on clarity and professionalism.",
    "video_url": "https://cdn.example.com/demos/product-v2.mp4",
    "timeout_seconds": 7200,
    "response_type": "rating",
    "response_config": { "scale_min": 1, "scale_max": 5 },
    "default_response": 3,
    "platform": "api"
  }'
```

## Audio

Embed an audio player for reviewers to listen to before responding. Supports major streaming platforms and direct audio file links. No audio hosting is provided — link to an externally-hosted audio file.

**type** `string` *required*

Set to `"audio"`

**audio\_url** `string` *required*

URL to the audio

**request\_text** `string` *required*

The question or instructions for the reviewer

**Supported platforms and formats:**

| Source | Examples |
| - | - |
| SoundCloud | `https://soundcloud.com/...` |
| Spotify | `https://open.spotify.com/track/...` |
| Direct MP3 | `https://cdn.example.com/audio.mp3` |
| Direct WAV | `https://cdn.example.com/audio.wav` |
| Direct OGG | `https://cdn.example.com/audio.ogg` |
| Direct M4A | `https://cdn.example.com/audio.m4a` |
| Direct AAC | `https://cdn.example.com/audio.aac` |

**Rendering:** SoundCloud and Spotify use their native iframe embeds. Direct audio files use the browser's native `<audio>` element on both web and mobile.

### Example

```python Python theme={null}
request_data = {
    "processing_type": "deferred",
    "type": "audio",
    "priority": "low",
    "request_text": "Listen to this customer support call recording and categorize the primary reason for the customer's complaint.",
    "audio_url": "https://cdn.example.com/recordings/support-call-20260115.mp3",
    "response_type": "single_select",
    "response_config": {
        "options": [
            "Billing Issue",
            "Technical Problem",
            "Shipping Delay",
            "Product Defect",
            "Other"
        ]
    },
    "default_response": "Other",
    "platform": "api"
}
```

```javascript Node.js theme={null}
const requestData = {
    processing_type: "deferred",
    type: "audio",
    priority: "low",
    request_text: "Listen to this customer support call recording and categorize the primary reason for the customer's complaint.",
    audio_url: "https://cdn.example.com/recordings/support-call-20260115.mp3",
    response_type: "single_select",
    response_config: {
        options: [
            "Billing Issue",
            "Technical Problem",
            "Shipping Delay",
            "Product Defect",
            "Other"
        ]
    },
    default_response: "Other",
    platform: "api"
};
```

```bash cURL theme={null}
curl -X POST https://api.hitl.sh/v1/api/loops/{loop_id}/requests \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "processing_type": "deferred",
    "type": "audio",
    "priority": "low",
    "request_text": "Listen to this customer support call and categorize the complaint.",
    "audio_url": "https://cdn.example.com/recordings/support-call-20260115.mp3",
    "response_type": "single_select",
    "response_config": {
        "options": ["Billing Issue", "Technical Problem", "Shipping Delay", "Product Defect", "Other"]
    },
    "default_response": "Other",
    "platform": "api"
  }'
```

## Rendering Behavior

| Content Type | Web Dashboard | Mobile App |
| - | - | - |
| `markdown` | Full markdown render (GFM) | Full markdown render |
| `image` | Inline image, click to zoom | Inline image, pinch-to-zoom |
| `file` (PDF) | Inline PDF annotator with highlight/comment tools | Download link |
| `file` (other) | Download link with filename | Download link with filename |
| `video` (YouTube/Vimeo) | Native iframe embed | Native iframe embed |
| `video` (direct) | HTML5 `<video>` player | HTML5 `<video>` player |
| `audio` (SoundCloud/Spotify) | Native iframe embed | Native iframe embed |
| `audio` (direct) | HTML5 `<audio>` player | HTML5 `<audio>` player |

## Required API Key Scopes

* `request:write` — Create requests
* `request:read` — Read request status and responses
* `loop:read` — Access loop information
* `upload:write` — Upload images and documents (upload endpoints only)

## Next Steps

> [card] [Upload Image](https://docs.hitl.sh/api-reference/upload/upload-image.md)
>
> Host images on HITL.sh before creating image requests

> [card] [Upload Document](https://docs.hitl.sh/api-reference/upload/upload-document.md)
>
> Host documents on HITL.sh before creating file requests

> [card] [Response Types](https://docs.hitl.sh/responses/types.md)
>
> Choose the right response type for your content review workflow

> [card] [Create Request](https://docs.hitl.sh/api-reference/requests/create-request.md)
>
> Start sending requests with rich content types


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