Collection API Represents grouped entities. A collection is comprised of multiple items grouped together in a playlist, album, folder, group or channel on your platform. For example, a playlist of videos (holding a list of videos), a discussion group (holding a list of posts), a folder (holding a list of files) or a channel.
openapi: 3.0.0
info:
license:
name: Alice API Terms of Use
url: https://app.alice.io/ts-platform/api-terms.pdf
version: 3.0.0
title: Alice API Documentation collection API
description: "# About This Guide\nThis guide provides comprehensive documentation for Alice's API offerings:\n\n**WonderSuite** - Our GenAI protection suite:\n- **WonderBuild**: Red teaming and security assessment tools for AI applications\n- **WonderFence**: Real-time guardrails for AI-generated content\n\n**ActiveFamily** - Our content moderation platform:\n- **ActiveScore**: AI-driven automated detection API that analyzes items and returns risk scores\n- **ActiveOS**: Self-service UI for organizing items, taking automatic or manual actions, and more\n\nAll APIs use a standard REST design, allowing you to use any standard REST client to call our endpoints from your server.\n\n### Run in Postman\nIf you use Postman, you can import the Alice APIs endpoints as a collection into your Postman app, then try out different requests to learn how the API works. Click the following button to get started:\n\n[](https://god.gw.postman.com/run-collection/24226888-0756580e-fccf-4fc3-8d36-7cc224b9215e?action=collection%2Ffork&collection-url=entityId%3D24226888-0756580e-fccf-4fc3-8d36-7cc224b9215e%26entityType%3Dcollection%26workspaceId%3D4a89e487-a108-4875-9ade-315bd98baf53)\n\n# Authentication\nAn Alice platform account is required to send requests and data to the Alice platform. An Alice representative will open an account for you and send you an email invitation to log in.\n\nThe following describes how to generate an API key, which you must use in the **af-api-key** header of each API request that you send. \n\n\n\n## Generating an API Key – How To\n**To generate an API key –**\n\n1. Click the **Account Settings** button.\n\n2. Select **DATA MANAGEMENT** and then select **Alice API Keys**. \nA list of the Alice API keys that have already been defined is displayed. \n\n \n3. Click the **Add Key** button. The following displays – \n\n \n\n4. In the **Key Name** field, enter any free-text name to identify the key.\n\n5. In the **Description** field, enter any free text description of the key.\n\n6. Click the **Generate Key** button. The key is then displayed in the following window – \n\n \n\n You must copy the key and should keep it secure, because you will not be able to see it again. Later, if needed you can [regenerate this key](#section/Authentication/Regenerating-a-Key).\n\n7. Click on the key in the **Your API Key** field to copy it to the clipboard. You can now click the **I've copied the key** button.\n\n8. Use this key as the value of an **af-api-key** header that you must add to each request.\n**af-api-key: \"YOUR_API_KEY\"** \n\n ## Regenerating a Key\nRegenerating a key will override the current one. The old one will still be valid for an additional 12 hours. After 12 hours, any request sent with the old key will be rejected.\n\n**To regenerate an Alice API Key –** \n1. Click the **Account Settings** button. \n2. Select **DATA MANAGEMENT** and then **Alice API Keys**. The following displays – \n\n\n3. Click the **Regenerate** button on the right side of the API key to be generated.\n\n**Note –** The options to delete a key and/or regenerate an existing one enable you to rotate between two different API keys.\n\n## Editing/Deleting a Key\nOnly the name and description of a key can be edited.\nOnce you delete a key, any request that uses the deleted key will be rejected. \n\n**To delete an Alice API Key –** \n\n1. Click the **Account Settings** button. \n\n2. Select **DATA MANAGEMENT**, and then **Alice API Keys**. \n\n3. Click the button on the right side of the API key and select the **Edit** or the **Delete** option.\n"
contact:
name: Support
email: support@alice.io
termsOfService: https://app.alice.io/ts-platform/terms.pdf
servers:
- url: https://api.alice.io
description: APIs Server
security:
- API Key: []
tags:
- name: collection
description: Collection API Represents grouped entities. A collection is comprised of multiple items grouped together in a playlist, album, folder, group or channel on your platform. For example, a playlist of videos (holding a list of videos), a discussion group (holding a list of posts), a folder (holding a list of files) or a channel.
paths:
/v3/collections/{collection_type}:
parameters:
- $ref: '#/components/parameters/collection_type'
post:
summary: Collection API
operationId: post-collections
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
description: 'Endpoint: https://api.alice.io/v3/collections/{collection_type}
The Collections API enables you to send details about a collection of your platform to the Alice T&S platform, which will analyze it, detect violations and return an array of one or more violations detected in the item. If the ID of this collection already exists, then its details are updated.
The T&S platform analyzes the **name** and **description** fields of each collection.'
callbacks:
Analysis result:
'{$request.body#/callback_url}':
post:
summary: callback with analysis result
requestBody:
description: Analysis result
content:
application/json:
schema:
type: object
properties:
response_id:
$ref: '#/components/schemas/response_id'
entity_id:
$ref: '#/components/schemas/entity_id'
entity_type:
$ref: '#/components/schemas/entity_type'
violations:
type: array
items:
type: object
properties:
violation_type:
$ref: '#/components/schemas/violation_type_text'
risk_score:
$ref: '#/components/schemas/risk_score'
detection_type:
$ref: '#/components/schemas/detection_type'
analysis_description:
$ref: '#/components/schemas/analysis_description'
required:
- violation_type
- risk_score
analyzed_violations:
type: array
description: violation types analyzed by Alice in this response
items:
$ref: '#/components/schemas/violation_types'
errors:
type: array
items:
$ref: '#/components/schemas/violation_error'
required:
- response_id
- entity_id
- entity_type
- violations
responses:
'200':
description: Callback successfully processed
requestBody:
content:
application/json:
schema:
type: object
description: 'The collection object '
properties:
collection:
$ref: '#/components/schemas/collection'
callback_url:
$ref: '#/components/schemas/callback_url'
callback_key_name:
$ref: '#/components/schemas/callback_key_name'
application/xml:
schema:
type: object
properties: {}
description: ''
tags:
- collection
components:
schemas:
violation_types:
title: violation_types
type: string
enum:
- abusive_or_harmful.harassment_or_bullying
- abusive_or_harmful.profanity
- abusive_or_harmful.hate_speech
- abusive_or_harmful.child_grooming
- abusive_or_harmful.graphic_violence
- abusive_or_harmful.general_violence
- abusive_or_harmful.child_abuse
- abusive_or_harmful.promotes_terrorism
- self_harm.general
- adult_content.general
- adult_content.swimwear
- unauthorised_sales.drugs
- unauthorised_sales.alcohol
- unauthorised_sales.weapons
- gambling.gambling
- privacy_violation.PII
description: violation types analyzed by Alice
entity_type:
type: string
title: entity_type
enum:
- content
- collection
- user
description: 'The type of the entity, which can be one of the following –
"content", "user" or "collection".'
violation_type_text:
type: string
enum:
- abusive_or_harmful.harassment_or_bullying
- abusive_or_harmful.profanity
- abusive_or_harmful.general_violence
- abusive_or_harmful.hate_speech
- abusive_or_harmful.child_grooming
- adult_content.general
- self_harm.general
- privacy_violation.PII
title: violation_type_text
description: Specifies the detected violation for a text.
entity_id:
title: entity_id
type: string
description: 'The unique identifier of the item on your platform, as specified in the request''s content_id / collection_id / user_id field. '
collection:
title: collection
type: object
description: A Collection object is a data structure to be used in ActiveScore API requests to describe a collection of items, such as playlist, groups, folders and so on.
properties:
collection_id:
type: string
description: The unique ID of the collection.
name:
type: string
description: The name of the collection.
maxLength: 1024
admins:
type: array
description: An array of user_ids of the collection's admins as provided in the Users API.
items:
type: string
example: '["admin1","admin2"]'
webpage_url:
$ref: '#/components/schemas/webpage_url'
description:
$ref: '#/components/schemas/description'
thumbnail_url:
$ref: '#/components/schemas/thumbnail_url'
date_created:
$ref: '#/components/schemas/date_created'
views_count:
$ref: '#/components/schemas/views_count'
comments_count:
$ref: '#/components/schemas/comments_count'
custom_fields:
$ref: '#/components/schemas/custom_fields'
response_custom_fields:
$ref: '#/components/schemas/response_custom_fields'
required:
- collection_id
- name
detection_type:
type: string
title: detection_type
enum:
- manual
description: OPTIONAL. This field is only returned when its value is manual, which indicates that the decision was made by a human reviewer in the Alice platform user interface.
views_count:
type: number
title: views_count
description: 'The quantity of views of this item on your platform. '
minimum: 0
date_created:
title: date_created
description: "The time in which the item was added to your platform.\nSupports ISO 8601 time string or UNIX number. \n\nISO format: \nYYYY-MM-DD HH:MM or \nMM-DD-YYYY HH:MM. \n\nFor example – \"2020-11-23 22:30\" 0r \"11-23-2015 05:30\"."
example: 2020-11-23 22:30
x-examples:
ISO format: 2020-11-23 22:30
Unix format: 1650886140
anyOf:
- type: number
- type: string
risk_score:
type: number
title: risk_score
maximum: 1
minimum: 0.1
example: 0.87
description: A number between 0.1 and 1 representing the probability of the item to be violative.
response_custom_fields:
title: response_custom_fields
x-stoplight:
id: v1yd97fsakvfi
type: array
description: 'list of field names to be included in the response.
these names should match some \ all of the fields which were specified in the ''custom_fields''.
'
items:
type: string
description: Corresponds to a custom field's field name.
x-examples:
- field1
- field2
response_id:
title: response_id
type: string
description: 'A tracking ID generated by the Alice platform upon receiving any request from your platform. This unique identifier enables you to trace events, if needed.
All callbacks for a request have the same response ID, so they can all be related to the request.'
callback_url:
title: callback_url
x-stoplight:
id: dbz2z4mf2znla
type: string
description: Callback URL where Alice will post the response to.
webpage_url:
type: string
title: webpage_url
format: uri
description: The publicly available web page where the item is visible.
violation_error:
title: violation_error
x-stoplight:
id: spx19wur2mvdt
type: object
properties:
violation:
type: string
status:
type: number
example: 400
type:
type: string
example: Bad request
message:
type: string
example: 'media type invalid: '
comments_count:
type: number
title: comments_count
description: The quantity of comments on this item on your platform.
minimum: 0
custom_fields:
title: custom_fields
x-stoplight:
id: pn300kxait3uk
type: array
description: "A set of key/value pairs of the custom fields that were added to your account. \nThese custom fields then appear throughout the platform.\n\n**Example –** [{\"special_name\":\"name1\"}, {\"special_count\": \"10\"}, {\"is_premium\": \"true\"}]\n\n**Note –** Quotation marks must be used for key and text values.\n"
items:
type: object
description: 'key/value pair.
key - Corresponds to a custom field''s key defined on your platform.
value - Can be a string, integer, boolean (true/false), date or dropdown
Quotation marks must be used for key and text values.'
x-examples:
Dropdown with multiple values:
custom_fields:
- '"animal_type': '"Persian cat"'
- '"age"': 3
- '"is_adopted"': true
- adoption_date: '2015-11-25'
- habitat:
- Urban
- Coastal
Dropdown with a single value:
custom_fields:
- '"animal_type': '"Persian cat"'
- '"age"': 3
- '"is_adopted"': true
- adoption_date: '2015-11-25'
- habitat: Urban
analysis_description:
title: analysis_description
type: string
description: 'OPTIONAL. A textual description of the violation that was created by a human reviewer or the Alice platform algorithm.
Returned only if exists.'
thumbnail_url:
type: string
title: thumbnail_url
description: 'The publicly available URL of the thumbnail that accompanied the item.
In order to be displayed correctly in the platform, the url should start with "https://" to avoid mixed content issues, where web browsers block insecure resources from loading.'
format: uri
callback_key_name:
title: callback_key_name
x-stoplight:
id: cufgi3wj9z5zc
type: string
description: 'The name of a key defined in the platform''s Auth Management section.
This key will be added to the header/query params of callback requests sent to the callback defined in **callback_url**.'
example: '"my key'
description:
title: description
type: string
description: The description that accompanied the item. Limited to 10,240 characters.
maxLength: 10240
responses:
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
example: 401
error:
type: string
example: Unauthorized
message:
type: string
example: Invalid credentials
params:
type: object
properties:
body:
type: object
description: error type
properties:
source:
type: string
keys:
type: array
items:
type: string
message:
type: string
example: Invalid credentials
'200':
description: Example response
content:
application/json:
schema:
type: object
properties:
response_id:
$ref: '#/components/schemas/response_id'
analyzed_violations:
type: array
description: A list of violations that will be analyzed for this response. The specific violations included in this list will depend on the configuration set up for your account and the type of media that was sent to be analyzed. In case this list is empty, no callback will be sent
items:
$ref: '#/components/schemas/violation_types'
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
example: 429
error:
type: string
example: Too Many Requests
message:
type: string
example: Too Many Requests
params:
type: object
properties:
body:
type: object
description: error type
properties:
source:
type: string
keys:
type: array
items:
type: string
message:
type: string
example: Too Many Requests
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
example: 400
error:
type: string
example: Bad Request
message:
type: string
example: \"text\" is required
params:
type: object
properties:
body:
type: object
description: error type
properties:
source:
type: string
example: body
keys:
type: array
items:
type: string
message:
type: string
example: \"text\" is required
parameters:
collection_type:
name: collection_type
in: path
required: true
schema:
type: string
enum:
- album
- playlist
- channel
- folder
- group
description: The type of the collection.
securitySchemes:
API Key:
name: af-api-key
type: apiKey
in: header
description: '
'
x-stoplight:
id: 324cav554fkgg
x-tagGroups:
- name: WonderSuite
tags:
- General
- WonderBuild
- WonderFence
- name: ActiveFamily
tags:
- Integrating with ActiveOS
- content
- users
- collection
- flags
- api keys