Sending Reports to Cove

Cove's Rules allow you to automate 90% of your Trust & Safety work, but unfortunately, it's impossible to automate 100% of it. There will always be harmful Items that slips through your automated systems. To handle those Items, you should allow your users to flag/report anything on the platform that they think is harmful (and in fact, a flagging/reporting feature is required by the iOS App Store guidelines and the EU's Digital Services Act). These reports are typically manually reviewed by a real person to account for the mistakes of automation.

Cove helps you handle this workflow. Through our Manual Review Tool, we allow you to review those reports and make decisions about whether or not to take an Action. All you have to do is send us reported Items through our Report API, and we'll automatically add those Items to a Review Queue for manual review.

Then, your moderators can log into Cove, review every report in the Queue, and decide whether to take action on each Item.

Implementation

Note: Before you implement the Report API integration, please first review the Basic Concepts and set up your Item Types and Actions

To utilize our Report API and Manual Review Tool, all you need to do is send us reported Items. When a user flags/reports an Item on your platform as potentially harmful, make a POST request to https://getcove.com/api/v1/report. You'll have to authenticate the request and add the relevant parameters to the body of the request, as shown in our code examples below.

REST API Examples

Below are some code snippets that you can paste directly into your code. You'll notice we're authenticating the request using your organization's API key in the HTTP headers.

Example Request

const body = {
  "reporter": {
    "kind": "user",
    "id": "abc123",
    "typeId": "def456"
  },
  "reportedAt": "2022-10-16 17:47:55.781-05",
  "reportedItem": {
    "id": "ghi789",
    "typeId": "jkl234",
    "data": {
      "text": "some text commented by a user",
      // ... all other fields in your Item Type
    }
  },
  "reportedForReason": {
    "policyId": "examplePolicyId",
    "reason": "reason for reporting",
  },
  "reportedItemThread": [
    {
      "id": "mno345",
      "typeId": "jkl234",
      "data": {
        "text": "some other comment",
        // ... all other fields in your Item Type
      }
    },
    {
      "id": "pqr456",
      "typeId": "jkl234",
      "data": {
        "text": "yet another comment",
        // ... all other fields in your Item Type
      }
    },
  ],
  "reportedItemsInThread": [
    {
      "id": "mno345",
      "typeId": "jkl234",
    }
  ],
  "additionalItems": [
    {
      "id": "hij123",
      "typeId": "jkl234",
      "data": {
        "text": "some post",
        // ... all other fields in your Item Type
      }
    },
    {
      "id": "rst567",
      "typeId": "jkl234",
      "data": {
        "text": "another post",
        // ... all other fields in your Item Type
      }
    },
  ]
};

const response = await fetch(
  "https://getcove.com/api/v1/report",
  {
    method: 'post',
    body: JSON.stringify(body),
    headers: {
      "x-api-key": "<<apiKey>>",
      "Content-Type": "application/json"
    },
  }
);
console.log(response.status);

import requests

headers = {
  'x-api-key': '<<apiKey>>',
  'Content-Type': 'application/json'
}

data = {
  'reporter': {
    'kind': 'user',
    'id': 'abc123',
    'typeId': 'def456'
  },
  'reportedAt': '2022-10-16 17:47:55.781-05',
  'reportedItem': {
    'id': 'ghi789',
    'typeId': 'jkl234',
    'data': {
      'text': 'some text commented by a user',
      # ... all other fields in your Item Type
    }
  },
  'reportedForReason': {
    'policyId': 'examplePolicyId',
  	'reason': 'reason for reporting',
  },
  'reportedItemThread': [
    {
      'id': 'mno345',
      'typeId': 'jkl234',
      'data': {
        'text': 'some other comment',
        # ... all other fields in your Item Type
      }
    },
    {
      'id': 'pqr456',
      'typeId': 'jkl234',
      'data': {
        'text': 'yet another comment',
        # ... all other fields in your Item Type
      }
    },
  ]
}

response = requests.post(
  'https://getcove.com/api/v1/report',
  headers=headers,
  json=data
)
response_dict = response.json()

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$headers = [
  'x-api-key' => '<<apiKey>>',
  'Content-Type' => 'application/json'
];

$body = [
  'reporter' => [
    'kind' => 'user',
    'id' => 'abc123',
    'typeId' => 'def456'
  ],
  'reportedAt' => '2022-10-16 17:47:55.781-05',
  'reportedItem' => [
    'id' => 'ghi789',
    'typeId' => 'jkl234',
    'data' => [
      'text' => 'some text commented by a user',
      # ... all other fields in your Item Type
    ]
  ],
  'reportedForReason' => [
    'policyId' => 'examplePolicyId',
  	'reason' => 'reason for reporting',
  ],
  'reportedItemThread' => [
    [
      'id' => 'mno345',
      'typeId' => 'jkl234',
      'data' => [
        'text' => 'some other comment',
        # ... all other fields in your Item Type
      ]
    ],
    [
      'id' => 'pqr456',
      'typeId' => 'jkl234',
      'data' => [
        'text' => 'yet another comment',
        # ... all other fields in your Item Type
      ]
    ],
  ]
];
  

$response = $client->request('POST', 'https://getcove.com/api/v1/report', [
  'headers' => $headers,
  'json' => $body,
]);

echo $response->getBody();

curl --request POST \
    --url https://getcove.com/api/v1/report \
    --header 'x-api-key: <<apiKey>>' \
    --header 'Content-Type: application/json' \
    --data '{
      "reporter": {
        "kind": "user",
        "id": "abc123",
        "typeId": "def456"
      },
      "reportedAt": "2022-10-16 17:47:55.781-05",
      "reportedItem": {
        "id": "ghi789",
        "typeId": "jkl234",
        "data": {
          "text": "some text commented by a user"
        }
      },
      "reportedForReason": {
        "policyId": "examplePolicyId",
        "reason": "reason for reporting"
      },
      "reportedItemThread": [
        {
          "id": "mno345",
          "typeId": "jkl234",
          "data": {
            "text": "some other comment"
          }
        },
        {
          "id": "pqr456",
          "typeId": "jkl234",
          "data": {
            "text": "yet another comment"
          }
        }
      ]
    }'

These are the fields that we expect in the body of the request:

Property	Type	Required?	Description
`reporter`	`Reporter`	Required	The user that reported the Item you're sending. See the `Reporter` schema below for details.
`reportedAt`	`Datetime`	Required	The datetime indicating the exact time at which the Item was reported. Datetimes should be formatted as ISO 8601 strings.
`reportedItem`	`ReportedItem`	Required	The Item that was reported. See the `ReportedItem` schema below for details.
`reportedForReason`	`ReportedForReason`	Optional	The reason that this Item was reported. See the `ReportedForReason` schema below for details.
`reportedItemThread`	`Array<ReportedItem>`	Optional	If the `reportedItem` is just one piece of content within a larger thread (e.g. a comment thread or a direct message thread), then you can include previous (and subsequent) messages from that thread inside this report. That way, you can view the full thread as you're reviewing the report to get maximal context.
`reportedItemsInThread`	`Array<ItemIdentifier>`	Optional	Indicates if an item in the `reportedItemThread` was reported specifically. This will cause a tag to show up in the ticket for the report in the Manual Review Tool next to the reported Items.
`additionalItems`	`Array<ReportedItem>`	Optional	If you want to render other pieces of content along with your report (e.g. the previous five posts made by the author of the reported content) for additional context, you can include those here in your report.

Reporter schema:

Property	Type	Required?	Description
`kind`	`String`	Required	The type of entity that reported the content. For now, the only supported entity type is `'user'`, so please set this field to the value `'user'`.
`id`	`String`	Required	Your unique identifier for the user who reported this Item.
`typeId`	`String`	Required	The ID of this user's Item Type. This should exactly match the ID of one of the Item Types that you defined in the Item Types Dashboard. The ID of each Item Type can be found in that dashboard.

ReportedItem schema:

Property	Type	Required?	Description
`id`	`String`	Required	Your unique identifier for the Item that is being reported.
`typeId`	`String`	Required	The ID of the Item Type that corresponds to the Item being reported. This should exactly match the ID of one of the Item Types that you defined in the Item Types Dashboard.
`data`	`JSON`	Required	This is a JSON containing the Item itself. In the Item Types Dashboard, you defined a schema for each Item Type. This `data` JSON must contain the fields you defined in the schema of the Item Type that corresponds to the reported Item. We'll return an error if any of the required fields are missing, if any of the types mismatch, or if any additional fields are included. Note: This is the same `data` JSON that you send us in the Item API.

ItemIdentifier schema:

Property	Type	Required?	Description
`id`	`String`	Required	Your unique identifier for the Item that is being reported.
`typeId`	`String`	Required	The ID of the Item Type that corresponds to the Item being reported. This should exactly match the ID of one of the Item Types that you defined in the Item Types Dashboard.

ReportedForReason schema:

Property	Type	Required?	Description
`policyId`	`String`	Optional	Some reporting flows allow users to select the reason they're reporting an Item. For example, a user might report an Item for Hate, or for Spam, or for Harassment. If you would like to map those reasons to the Policies you set up in your Policies Dashboard, you can specify the ID of the relevant Policy in this `policyId` field.
`reason`	`String`	Optional	If you allow users to write additional freeform text associated with the report to indicate why they're submitting the report, you can add that here.

ReportedItemThread schema:

This is just an array of ReportedItem objects.
The one notable difference is that in the data field, we do not need every required field to actually be present. This is because sometimes, when you're retroactively fetching previous Items in a thread, you might not have every piece of information immediately available, including information that is marked as required in your Item Type schema. So we do not enforce that required fields are actually provided in these ReportedItem objects.
However, we do expect every Item in this array to be sent with the datetime of when they are created or in the order that you would like us to display them in. If you send Items in the array to us without datetimes, we’ll expect the array to also contain the reported Item itself so we know where that reported Item belongs (chronologically) in the thread.

Example Response

We will respond with an HTTP response status code, which indicates whether the request was successful.

{
    status: 204,
}

Successful requests will have a 204 status code. If an error occurs, the status will contain the relevant error code.