Get Custom AI Model Scores

If you are only interested in using Cove's Custom AI Models, but you don't want to use the Automated Enforcement or Moderator Console products, then this is the only API you need.

With this API, you can send an Item (or batch of Items), and get back the raw scores produced by all your Custom AI models for that Item. This API endpoint is synchronous, so you don't even have to worry about Handling Moderation Actions asynchronously.

Implementation

To send us an Item, simply make a POST request to https://getcove.com/api/v1/items/scores. You'll have to authenticate the request and add 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 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/scores",
  {
    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/scores',
  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/scores', [
  'headers' => $headers,
  'json' => $body,
]);

echo $response->getBody();

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

Response Format and Example

The synchronous response will be returned with a 200 status code, and will be returned with data in the following shape:

{
  items: {
    id: string;
    typeId: string;
    scores: {
      policy: {
        id: string;
        name: string;
      };
      modelVersion: 'LIVE';
  		score: number | undefined;
  		error: string | undefined;
    }[];
  }[]
}

This is an example of what a response from this endpoint might look like. While we only list a single item, the response will contain entries for each item sent in the request.

{
  items: [
    { 
      id: 'abc123',
	    typeId: 'def456',
      scores: [
        policy: {
        	id: '123456',
        	name: 'Harassment',
        },
    		modelVersion: 'LIVE',
    		score: 0.8,
    		error: undefined,
      ],
    },
    ...
  ],

Implementation

REST API Examples

Example Request

Formatting the data JSON

Response Format and Example

Formatting the `data` JSON