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 https://getcove.com/api/v1/items/async. 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:

We're authenticating the request using your organization's API key in the HTTP headers.
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.
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(
  "https://getcove.com/api/v1/items/async",
  {
    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 = {
  '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 = requests.post(
  'https://getcove.com/api/v1/items/async',
  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 = [
  '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', 'https://getcove.com/api/v1/items/async', [
  'headers' => $headers,
  'json' => $body,
]);

echo $response->getBody();

curl --request POST \
    --url https://getcove.com/api/v1/items/async \
    --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:

Property	Type	Description
`id`	`String`	Your 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.
`typeId`	`String`	The 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.
`data`	`JSON`	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 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 Type	Expected Format	Additional Notes
`Audio`	Url	This should be a publicly accessible URL to the Audio File
`Boolean`	Boolean
`Datetime`	String	A string representing a date. We'll accept almost all common formats, but here's a specific list of the acceptable formats.
`Geohash`	String	A geohash representing the latitude and longitude of a location
`Id`	String	Any ID representation in your systems.
`Image`	Url	This should be a publicly accessible URL to the Image (or GIF) File
`Number`	Number
`Policy Id`	String	A Cove Policy ID, which you can find in your Policies Dashboard
`Related Item`	Object 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.
`Url`	Url	Any link
`Video`	Url	This should be a publicly accessible URL to the Video File

Example Response

{
  status: 202,
}

These fields will be returned in every response:

Property	Type	Description
`status`	`Number`	`202` indicates that a request was successful. If an error occurs, `status` will contain the relevant error code.

Sending Items to Cove

REST API Examples

Example Request

Formatting the data JSON

Example Response

Formatting the `data` JSON