POST https://api.hivemoderation.com/api/v1/appeals/create

Appeals allow users to contest previous moderation decisions. You can submit an appeal using either judgment_id or appeal_context. If the content has expired, you will need to include this field in this request.

Example Request

curl -X POST https://api.hivemoderation.com/api/v1/appeals/create \
  -H "Authorization: token <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "appeal_context": {
      "type": "post",
      "post_id": "post-1",
      "user_id": "user-1" },
    "appealer_id": "user-1",
    "appeal_reason": "This content was flagged incorrectly. It is educational material.",
    "appeal_categories": ["false_positive", "educational_content"]
  }'

Request

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	API key from Moderation Dashboard (per-application).
`Content-Type`	string	Yes	Submit JSON data in the request body.

Request Body Parameters

Parameter	Type	Required	Description
`appealer_id`	string	Yes	Unique identifier for the user submitting the appeal.
`judgment_id`	string	Conditional*	ID of the moderation judgment being appealed.
`appeal_context`	object	Conditional*	Context object for the content being appealed (see below).
`appeal_reason`	string	No	Free-form text explaining the appeal.
`appeal_categories`	array	No	Category strings for the appeal type.
`report_id`	string	No	Associated report ID.
`metadata`	object	No	Custom metadata (any valid JSON). Must not be greater than 2048 characters.
`text_data`	string	Conditional†	Text content for moderator review. Required if original content has expired.
`url`	string	Conditional†	Media URL for moderator review. Required if original content has expired.

Notes

(*) Provide exactly one: judgment_id OR appeal_context.
(†) When original content has expired, provide exactly one: text_data OR url.

Appeal Context Object

Required when using appeal_context instead of judgment_id.

Field	Type	Required	Description
`type`	string	Yes	Either `"post"` or `"user"`.
`user_id`	string	Yes	User ID associated with the content.
`post_id`	string	Conditional	Required when type is `"post"`. Mutually exclusive with `source_post_id`.
`source_post_id`	string	No	Original post ID for shared/reposted content. Mutually exclusive with `post_id`.

Responses

Response Fields

Field	Type	Always Returned	Description
`appeal.id`	string	No	Unique identifier for the created appeal.
`appeal.application_id`	string	Yes	Your application ID.
`appeal.appeal_categories`	array	No	Categories associated with the appeal.
`appeal.patron_id`	string	No	ID of the user about whom the appeal was made.
`appeal.post_id`	string	No	ID of the post about which the appeal was made.
`appeal.timestamp`	string	Yes	Timestamp (ISO 8601 format) when the appeal was created.
`appeal.appeal_reason`	string	No	The reason provided for the appeal.
`appeal.metadata`	object	No	Custom metadata attached to the appeal.
`appeal.text_data`	string	Conditional*	Text content from the appealed post. Returned if the post is of type text.
`appeal.url`	string	Conditional*	Media URL from the appealed post. Returned if the post contains media.
`appeal.judgment_id`	string	No	Associated judgment ID (if provided).
`appeal.report_id`	string	No	Associated report ID (if provided).
`appeal.appealer_id`	string	Yes	ID of the user who submitted the appeal.
`appeal.entity_type`	string	Yes	Either `"patron"`, `"post"`, or `"none"`.
`appeal.bucket`	string	Yes
`appeal.content_expired`	boolean	Yes	Whether the content has expired.

Notes

(*) When original content has expired, provide exactly one: text_data OR url.

Example Responses

Example Success (200 OK)

{
  "appeal": {
    "id": "appeal_xyz789",
    "application_id": "app_123",
    "judgment_id": "jdg_abc123xyz",
    "appealer_id": "user_789",
    "appeal_reason": "This content was flagged incorrectly. It is educational material.",
    "appeal_categories": ["false_positive", "educational_content"],
    "status": "pending",
    "created_at": "2026-01-21T10:30:00Z",
    "metadata": null
  }
}

Example Error Response (400 Bad Request)

{
  "error": true,
  "status": 400,
  "error_code": "PARAM_REQUIRED",
  "message": "appealer_id is required.",
  "show_alert": false,
}

Common Errors

Status Code	Error Code	Description
400	`INVALID_PARAMETERS`	Missing required parameter or invalid type.
400	`INVALID_APPEAL_CONTEXT_TYPE`	`appeal_context.type` must be `"post"` or `"user"`.
400	`CONFLICTING_PARAMETERS`	Violated mutual exclusivity rules (e.g., provided both `judgment_id` and `appeal_context`).
400	`NONEXISTENT_POST_ID`	The post ID references expired/deleted content. Include `text_data` or `url` to provide content for moderator review.
400	`APPEAL_METADATA_TOO_LARGE`	Appeal Metadata must be under 2048 total characters.
401	`UNAUTHORIZED`	Invalid or missing API key.
404	`JUDGMENT_NOT_FOUND`	The specified `judgment_id` does not exist.
429	`RATE_LIMIT_EXCEEDED`	Too many requests. Please retry after the specified time.