Sending Items to Cove

Every time you send us an Item, we run it through all your Cove Rules. So whenever you want an Item to run through your Rules (e.g. when it gets uploaded, edited, reported, shared, etc.), you can easily send it to us through our REST API.

To send us an Item, simply make a POST request to You'll have to authenticate the request and add parameters to the body of the request, as shown in our code examples below.

If you provide a valid Item, we'll return a status: 202 response immediately. Then, if one of your Rules determines that an Action should be taken (e.g. the Item should be deleted), we'll trigger that Action by sending a POST request to your Action's callback URL.

Note: If you need responses to be synchronous, please contact us at [email protected] and we can chat!

REST API Examples

Below are some code snippets that you can paste directly into your code. You'll notice a couple things:

  1. We're authenticating the request using your organization's API key in the HTTP headers.
  2. In the HTTP request body, we've specified the Item's Type under item.typeId. This should correspond to one of the Item Types we defined earlier in the Cove dashboard. You can find the IDs of all your Item Types in that dashboard.
  3. In the data field, you must include all of the required fields listed in that Item Type, as Cove expects all fields marked as required to be present.

Example Request

const body = {
  items: [
      id: "abc123", // your unique ID for this item
      typeId: "def456", // the ID of the item's "Item Type" (in Cove's system)
      data: {
        text: "some text uploaded by a user"
        // ... all other fields in your Item Type
    ... // other items

const response = await fetch(
    method: 'post',
    body: JSON.stringify(body),
    headers: {
      "x-api-key": "<<apiKey>>",
      "Content-Type": "application/json"
import requests

headers = {
  'x-api-key': '<<apiKey>>',
  'Content-Type': 'application/json'
data = {
  'items': [
      'id': 'abc123', # your unique ID for this item
      'typeId': 'def456', # the ID of the item's "Item Type" (in Cove's system)
      'data': {
        'text': 'some text uploaded by a user',
        # ... all other fields in your Item Type
    ... # other items
response =
response_dict = response.json()

$client = new \GuzzleHttp\Client();

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

$body = [
  'items' => [
    'id' => 'abc123', // your unique ID for this item
    'typeId' => 'def456', // the ID of the item's "Item Type" (in Cove's system)
    'data' => [
      'text' => 'some text uploaded by a user'
      // ... all other fields in your Item Type

$response = $client->request('POST', '', [
  'headers' => $headers,
  'json' => $body,

echo $response->getBody();
curl --request POST \
    --url \
    --header 'x-api-key: <<apiKey>>' \
    --header 'Content-Type: application/json' \
    --data '{
        "items": [
                "id": "abc123",
                "typeId": "def456",
                "data": {
                    "text": "some text uploaded by a user"

In the body of the request, there is only one top-level property called items, which is an array of objects representing each Item you're submitting. This property is an array so that you can submit batches of multiple Items within a single API request, if you'd like.

In each object in the items array, we expect the following fields:

idStringYour unique identifier for this Item. Every time we send you an HTTP request to trigger an Action, we'll include this id as a parameter so you know on which Item you should execute the Action.
typeIdStringThe ID of the Item Type that corresponds to the Item you're sending. This should exactly match the ID of one of the Item Types that you defined in the Item Types Dashboard. The IDs of each Item Type can be found in that dashboard.
dataJSONThis 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 corresponding Item Type's schema. 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.

See the section below to understand exactly how each field in the JSON should be formatted.

Formatting the data JSON

When you create fields on an Item Type, you specify the type that each field should be (e.g. "String", "Boolean", "Image", etc.). Below is a table that can help you format each field properly according to its Type

Listed Field TypeExpected FormatAdditional Notes
AudioUrlThis should be a publicly accessible URL to the Audio File
DatetimeStringA string representing a date. We'll accept almost all common formats, but here's a specific list of the acceptable formats.
GeohashStringA geohash representing the latitude and longitude of a location
IdStringAny ID representation in your systems.
ImageUrlThis should be a publicly accessible URL to the Image (or GIF) File
Policy IdStringA Cove Policy ID, which you can find in your Policies Dashboard
Related ItemObject of type
{ id: string, typeId: string }
An object representing an Item. The id field will be your unique identifier for the item, whereas the typeId field will be the ID of the item's Item Type in your Cove Dashboard.
UrlUrlAny link
VideoUrlThis should be a publicly accessible URL to the Video File

Example Response

  status: 202,

These fields will be returned in every response:

statusNumber202 indicates that a request was successful. If an error occurs, status will contain the relevant error code.