diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 5be90be..2c07e21 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -35,7 +35,6 @@ - [Report](api/report.md) - [Appeal](api/appeal.md) - [Policies](api/policies.md) - - [User Scores](api/user-scores.md) - [Handling Actions](api/actions.md) - [Partial Items](api/partial-items.md) - [Errors](api/errors.md) diff --git a/docs/api/README.md b/docs/api/README.md index 224fa67..c03c39b 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -11,16 +11,15 @@ Content-Type: application/json You can find or rotate your API key under **Settings** → **API Keys** in the Coop UI. For details on verifying the signatures Coop adds to outgoing webhook requests, see [API Keys & Authentication](../development/api-auth.md). -| Endpoint | Description | -| :--------------------------- | :------------------------------------------------------------- | -| `POST /api/v1/items/async/` | [Items](items.md): send content for rule evaluation | -| `POST /api/v1/report` | [Report](report.md): submit a user report | -| `POST /api/v1/report/appeal` | [Appeal](appeal.md): submit a user appeal | -| `GET /api/v1/policies/` | [Policies](policies.md): fetch your configured policies | -| `GET /api/v1/user_scores` | [User Scores](user-scores.md): fetch a user's moderation score | +| Endpoint | Description | +| :--------------------------- | :------------------------------------------------------ | +| `POST /api/v1/items/async/` | [Items](items.md): send content for rule evaluation | +| `POST /api/v1/report` | [Report](report.md): submit a user report | +| `POST /api/v1/report/appeal` | [Appeal](appeal.md): submit a user appeal | +| `GET /api/v1/policies/` | [Policies](policies.md): fetch your configured policies | See also: -- [Handling Actions](actions.md): information about receiving action webhooks from Coop +- [Handling Actions](actions.md): receive action webhooks from Coop for automated actions, moderator decisions, crossing user strike thresholds, and appeal decisions - [Partial Items API](../api/partial-items.md): support Coop fetching Items and their attributes on demand - [Errors](errors.md): details of error responses from Coop diff --git a/docs/api/actions.md b/docs/api/actions.md index a67879a..c5f280c 100644 --- a/docs/api/actions.md +++ b/docs/api/actions.md @@ -1,6 +1,6 @@ # Handling Actions -When Coop triggers an Action—either through an automated rule or a moderator's decision in the Review Console—it sends a POST request to the callback URL you configured for that Action. Your server receives this request and performs the corresponding operation. +When Coop triggers an Action—whether through an automated rule, a moderator's decision in the Review Console, or a user crossing a User Strike threshold—it sends a POST request to the callback URL you configured for that Action. Your server receives this request and performs the corresponding operation. ## Setting up your callback endpoint @@ -58,6 +58,18 @@ Failed deliveries are retried up to five times with exponential backoff. | `id` | String | Coop's unique rule ID | | `name` | String | Rule name | +### User Strikes + +When a user's cumulative strike score crosses a configured threshold, Coop executes the action associated with that threshold using the same callback mechanism described above. The only differences from a rule-triggered action callback are: + +- `policies` is always an empty array; the threshold fires on cumulative score, not a specific policy violation in this request + +- `rules` is always an empty array; no rule directly triggered the callback + +- `actorEmail` and `actorNote` are never present; there is no human actor + +For more on setting up and configuring user strikes, thresholds, and associated actions, see [User Strikes](../user/automated-enforcement.md#user-strikes) in the user guide. + ## Appeal decision callback When a moderator reviews an appeal in the Review Console and makes a decision, Coop sends a POST request to the Appeal callback URL configured in your Appeals Dashboard. @@ -83,3 +95,20 @@ When a moderator reviews an appeal in the Review Console and makes a decision, C | `custom` | Object | Not always | Custom parameters configured in the Appeal Configuration Form under "Body" | For the full appeal submission flow, see [Appeals](../user/appeals.md). + + diff --git a/docs/api/user-scores.md b/docs/api/user-scores.md deleted file mode 100644 index 7caf1a5..0000000 --- a/docs/api/user-scores.md +++ /dev/null @@ -1,44 +0,0 @@ -# User Scores API - -Fetch the current moderation score for a specific user. Scores range from 1 (worst) to 5 (best) and reflect a user's ratio of penalty points to total submissions. - -For details on how scores are calculated and what thresholds map to which score values, see [User Score](../user/concepts.md) in Basic Concepts. - -## Endpoint - -```http -GET /api/v1/user_scores -``` - -Authentication: `X-API-KEY` header. See [API Keys & Authentication](../development/api-auth.md). - -## Query parameters - -| Parameter | Type | Required? | Description | -| :-------- | :----- | :-------- | :--------------------------------------- | -| `id` | String | Required | Your unique identifier for the user | -| `typeId` | String | Required | The Coop Item Type ID for this user type | - -**Example request:** - -```http -GET /api/v1/user_scores?id=user-123&typeId=your-user-type-id -``` - -## Response - -Returns the user's score as a number between 1 and 5. - -```json -3 -``` - -HTTP statuses: - -| Status | Meaning | -| :---------------- | :--------------------------------------------- | -| `200 OK` | Score returned successfully | -| `400 Bad Request` | Missing or invalid `id` or `typeId` parameters | -| `401` or `403` | Authentication failure | - -See [Errors](errors.md) for the full error response format. diff --git a/docs/development/architecture.md b/docs/development/architecture.md index 0ed5c3d..7eaa3d9 100644 --- a/docs/development/architecture.md +++ b/docs/development/architecture.md @@ -120,7 +120,7 @@ When a report is submitted or a proactive rule sends an item to the review conso ## Review Console -The [Review Console](../user/review-console.md) (sometimes referred to as "manual review tool" or "MRT" in the codebase) is a BullMQ-backed queue system used for human review. Items enter the review console as a [Job](../user/concepts.md#jobs) via rule actions or user reports. Each Job is enriched with context (user scores, related items) and routed to a named queue via routing rules configured in the UI. Moderators claim Jobs via exclusive locks (so only one person can claim one Job) and make decisions by performing [Actions](../user/concepts.md#actions), which trigger downstream callbacks or reporting workflows (ie. NCMEC). +The [Review Console](../user/review-console.md) (sometimes referred to as "manual review tool" or "MRT" in the codebase) is a BullMQ-backed queue system used for human review. Items enter the review console as a [Job](../user/concepts.md#jobs) via rule actions or user reports. Each Job is enriched with context (number of reports, user strikes, related items) and routed to a named queue via routing rules configured in the UI. Moderators claim Jobs via exclusive locks (so only one person can claim one Job) and make decisions by performing [Actions](../user/concepts.md#actions), which trigger downstream callbacks or reporting workflows (ie. NCMEC). ### Queue operations