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[![Run in Postman](https://run.pstmn.io/button.svg)](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