Item API
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 asrequired
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
data
JSONWhen 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. |
Updated 8 months ago