👥

Manual Moderation API

Submit content for human expert review

The manual moderation API allows you to submit content for human expert review. Results are delivered asynchronously via webhooks, typically within 48 hours.

Create Submission

POSThttps://api.outharm.com/moderation/manual

Submits content for human expert review and returns a submission ID for tracking.

📋 Requirements

  • • Authentication: Bearer token required
  • • Content-Type: application/json
  • • Subscription: Manual moderation subscription required
  • • Webhooks: Configure webhook endpoint to receive results

Request Body

The request body uses the same structure as automated moderation, with schema-based content validation:

{
  "schema_id": "550e8400-e29b-41d4-a716-446655440000",
  "content": {
    "field_name": ["value1", "value2"],
    "another_field": ["value3"]
  }
}

Field Requirements

schema_idREQUIREDUUID

The ID of the schema that defines the content structure.

contentREQUIREDObject

Content to moderate, organized by field names. Field names must match schema component names. All values are arrays for consistency.

Content Value Types
Text Values:
"title": ["Blog post about AI safety", "Another title"]
Image URLs:
"images": ["https://example.com/image.jpg", "https://example.com/photo.png"]
Base64 Images:
"avatar": ["data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."]

⚠️ Validation Rules

Content Structure:

  • • Content object cannot be empty
  • • Maximum 50 fields per request
  • • Field names must match schema component names
  • • Field names cannot be empty or exceed 100 characters

Content Arrays:

  • • Arrays cannot be empty (must have at least one value)
  • • Maximum 100 values per field array
  • • Individual values cannot be empty or whitespace-only

URLs & Images:

  • • HTTP/HTTPS URLs must be under 2048 characters
  • • Base64 data URLs must include `;base64,` format

Request Example

POST https://api.outharm.com/moderation/manual
Authorization: Bearer your_api_token_here
Content-Type: application/json

{
  "schema_id": "550e8400-e29b-41d4-a716-446655440000",
  "content": {
    "title": ["User-generated content requiring expert review"],
    "description": [
      "Complex content that needs human judgment",
      "Context-sensitive material to evaluate"
    ],
    "images": [
      "https://example.com/user-uploaded-image.jpg",
      "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
    ]
  }
}

Response

{
  "submission_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response Fields

submission_idUUID

Unique identifier for the submitted content. Use this ID to track the submission and receive webhook notifications.

Add to Queue

POSThttps://api.outharm.com/submissions/{submission_id}/moderation/manual

Adds an existing submission to the manual moderation queue for human review.

⚠️ Use Case

This endpoint is typically used when you want to manually review a submission that was initially processed through automated moderation, such as for appeals or quality assurance purposes.

Path Parameters

submission_idREQUIREDUUID

The ID of an existing submission that belongs to your project. This submission will be added to the manual moderation queue.

Request Example

POST https://api.outharm.com/submissions/123e4567-e89b-12d3-a456-426614174000/moderation/manual
Authorization: Bearer your_api_token_here

Response

Returns HTTP 200 with no response body on successful addition to the queue.

Receiving Results

📡 Webhook Delivery

Manual moderation results are delivered asynchronously via webhooks to your configured endpoint. Reviews are typically completed within 48 hours. For complete webhook setup, payload structure, and security information, see Webhooks API documentation.

Error Responses

Subscription Required (403 Forbidden)

When manual moderation subscription is required:

{
  "name": "manual-moderation-subscription-required",
  "message": "Manual moderation subscription required",
  "status_code": "403"
}

Submission Not Found (404 Not Found)

When submission doesn't exist or doesn't belong to your project:

{
  "name": "submission-not-found",
  "message": "Submission not found or not accessible",
  "status_code": "404"
}

Already Processed (422 Unprocessable Entity)

When trying to add a submission that's already in the manual moderation queue:

{
  "name": "request-already-processed",
  "message": "Request already processed",
  "status_code": "422"
}

Validation Errors (400 Bad Request)

When request validation fails (same validation rules as automated moderation):

{
  "name": "validation-error",
  "message": "Content cannot be empty",
  "status_code": "400"
}

// Schema errors:
{
  "name": "schema-not-found",
  "message": "Schema not found or not accessible", 
  "status_code": "404"
}

Appeals Process

⚖️ Appeal Moderation Decisions

If you disagree with a moderation decision (either automated or manual), you can appeal by using the "Add Existing Submission to Manual Queue" endpoint. This allows human moderators to review the content again with additional context.

Appeal Workflow
  1. 1. Get the submission_id from the original moderation result
  2. 2. Use POST /submissions/{submission_id}/moderation/manual
  3. 3. Human moderators will review the content again
  4. 4. Receive updated results via webhook notification

Best Practices

✅ Webhook Configuration

Configure and test your webhook endpoint before submitting content. Manual moderation results are only delivered via webhooks.

✅ Track Submissions

Store submission IDs to track requests and match webhook notifications to original submissions.

✅ Hybrid Approach

Use automated moderation for most content and manual review for edge cases, appeals, or high-risk content.

❌ Duplicate Submissions

Don't submit the same content multiple times unless appealing a decision. Each submission enters the review queue.

Ready to Get Started?

Set up manual moderation with webhook configuration and start leveraging human expertise for complex content decisions.

Manual Moderation Concepts

Understanding the review process

→

Configure Webhooks

Set up result notifications

→

Related Documentation