Skip to main content
Version: 3.0.0

Alice API Documentation

About This Guide​

This guide provides comprehensive documentation for Alice's API offerings:

WonderSuite - Our GenAI protection suite:

  • WonderBuild: Red teaming and security assessment tools for AI applications
  • WonderFence: Real-time guardrails for AI-generated content

Content Moderation - Our platform for moderating user-generated content:

  • ActiveScore: AI-driven automated detection API that analyzes items and returns risk scores
  • ActiveOS: Self-service UI for organizing items, taking automatic or manual actions, and more

All APIs use a standard REST design, allowing you to use any standard REST client to call our endpoints from your server.

Run in Postman​

If 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:

Run in Postman

Authentication​

An 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.

The APIs accept two credentials, and every endpoint takes either one:

CredentialSent asBest for
API key — a long-lived key you generate in the platformalice-api-key: <key>Server-to-server integrations you control, and the quickest way to get started
OAuth 2.0 — a client id and secret you exchange for a 15-minute tokenAuthorization: Bearer <access_token>Integrations that need short-lived, individually revocable, role-scoped credentials, and third-party systems that speak OAuth natively — including Databricks Unity Catalog, which supports no other method

If a request carries an alice-api-key header, that is the credential used, even when a bearer token is also present.

Both sections below describe how to obtain and use each one.

API Key​

Generating an API Key – How To​

To generate an API key –

  1. Click the Account Settings button.

  2. Select INTEGRATIONS and then select Alice API Keys. A list of the Alice API keys that have already been defined is displayed.

  3. Click the Add Key button. The following displays –

  4. In the Key Name field, enter any free-text name to identify the key.

  5. In the Description field, enter any free text description of the key.

  6. Click the Generate Key button. The key is then displayed in the following window –

    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.

  7. 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.

  8. Use this key as the value of an alice-api-key header that you must add to each request. alice-api-key: "YOUR_API_KEY"

Regenerating a Key​

Regenerating 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.

To regenerate an Alice API Key –

  1. Click the Account Settings button.

  2. Select INTEGRATIONS and then Alice API Keys. The following displays –

  3. Click the Regenerate button on the right side of the API key to be generated.

Note – The options to delete a key and/or regenerate an existing one enable you to rotate between two different API keys.

Editing/Deleting a Key​

Only the name and description of a key can be edited. Once you delete a key, any request that uses the deleted key will be rejected.

To delete an Alice API Key –

  1. Click the Account Settings button.

  2. Select INTEGRATIONS, and then Alice API Keys.

  3. Click the button on the right side of the API key and select the Edit or the Delete option.

OAuth 2.0 – How To​

An OAuth credential is an inbound machine-to-machine credential. You exchange it for a short-lived access token and send that token on API calls. The credential is held by Alice's identity provider rather than stored in the platform, its role is fixed when it is created, and revoking it takes effect immediately.

To create an OAuth credential –

  1. Click the Account Settings button.

  2. Select INTEGRATIONS and then select OAuth Credentials.

  3. Click the Create button, give the credential a name and description, and choose the role it should carry.

  4. The Client ID, the Client Secret and the Token Endpoint URL are displayed, each with a Copy button. The client secret is shown once — copy it before closing the dialog. If it is lost, delete the credential and create another.

To exchange it for an access token –

Send a form-encoded client_credentials request to the token endpoint. Credentials travel either as HTTP Basic or as form fields; send one or the other.

curl -X POST https://api.alice.io/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
{ "access_token": "eyJhbGciOiJSUzI1NiIs...", "token_type": "Bearer", "expires_in": 900 }

Note – The token endpoint is on the same host as the rest of the API. It is the one endpoint that takes no credential of its own — the client id and secret are its request body. Use the Token Endpoint URL the dialog gave you rather than assembling it yourself.

To use the token –

Send it as a bearer token on each API request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Token lifetime. A token lives 900 seconds and no refresh token is issued. A long-running client repeats the exchange rather than refreshing it — re-mint at roughly expires_in - 30 seconds, and read expires_in from the response rather than hardcoding it.

Rate limits. Failed exchanges are limited to 20 per minute per source IP, 60 per minute per client id, and 5 per minute per client-and-source pair. Successful exchanges are not counted, so normal traffic never approaches these ceilings.

The full request and response contract, including every error code, is documented under Authentication → OAuth 2.0.

Integrating With Activeos​

ActiveOS is the world's leading tool stack for Trust & Safety teams.

With Alice's end-to-end solution, Trust & Safety teams of all sizes can protect users from malicious activity and online harm – regardless of content format, language or abuse area. By combining AI and a team of our subject-matter experts, the ActiveOS platform enables you to be agile and proactive for maximum efficiency, scalability and impact.

Integrating with ActiveOS platform enables you to detect, collect and analyze harmful content that may put your users and brand at risk. ActiveOS also provides a self-service UI that lets you easily tackle various moderation challenges and take action against violators.

Concepts & Terms​

Entities​

The ActiveOS platform categorizes your content data as one of the following entities –

Content​

Represents WHAT content was created on your platform, such as a post, comment, review, message, article or data. For example, a web page containing a video, a customer review of a product, a comment and so on.

Users​

Represents WHO created content on your platform. These are the end users that have uploaded content to your platform, meaning the people who are the creators or publishers of the content. For example, the account used for creating an image, the user who commented on a post and so on.

Collections​

Represents grouped entities. A collection is composed 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.

Item​

An item is an instance of an entity, meaning a specific user, content or collection that was on your platform and was sent to ActiveOS platform for analysis. For example, a specific user (a guy named Roy-the-Man), specific content (a video that this user uploaded to your platform) or a specific collection (a specific playlist of this user).

Media​

It's important to differentiate between content and media. Media refers to the images, videos, text, audio and/or files that may be contained in an item (entity instance). All entity types in ActiveOS (meaning users, content and collections) can contain one or more media.

For example, a blog post, an article or a post might contain an image, video, text, audio and/or file.

Flags​

A flag is a common mechanism for platform users to report what they consider harmful, such as to specify that something is offensive, abusive or hate speech. Each flag may have multiple attributes, such as a Violation Category and the free text explanation entered by the person who flagged the item.

Risk Score​

ActiveScore uses a combination of AI-powered risk scores and human analysis to analyze each item, as well as its context in order to provide a risk score of (between 0 – 1) that indicates the extent and confidence that the item is in violation of each violation type, as described above.

This means that an array of two values is sent by ActiveScore in response to each item that is analyzed.

For example, the following array might be returned by the API for a specific text item –

  • Violation Type – abusive_or_harmful.hate_speech, Risk Score – 0.8
  • Violation Type – abusive_or_harmful.harassment_or_bullying, Risk Score – 0.6

These keys are illustrative. Which violation types your project can receive depends on the policies it has, and each policy’s key is shown as API Response Key on the policy’s page in the platform.

A risk score is only returned for a violation type, if the risk score is over 0.1.

Note – In ActiveOS platform user interface, this number is represented as 0 – 100 and a single aggregated risk score is assigned to each item.

Violation Types​

Each item that is analyzed by ActiveScore is assigned a risk score for each violation type in order to indicate the extent and confidence that an item (entity instance) is in violation of each violation type. Violation types include abusive behavior, terrorism, extremism, profanity and so on. A risk score between 0 and 1 represents the probability of the item to be violative, as described below.

API Response latency​

Response latency is measured from the time a request is received by our servers to the time the response is returned by our servers, not including network latency, which might have an impact.

The latency depends on file type and size, so it might vary from our general benchmark:

mediap50p90
text100 ms250 ms
image1 sec5 sec
video (1 min)10 sec15 sec
video (5 min)1 min1.5 min
video (30 min)3 min3.5 min
audio (30 sec)6 sec8 sec
audio (60 sec)8 sec11 sec
audio (30 min)15 min20 min

ActiveScore and ActiveOS Use Cases​

Here's a few popular use cases for sending data to ActiveOS platform –

  • Newly published items – Before publishing items, you can send them to the platform in order to avoid publishing violative items. Alternatively, you can send all newly published items to the platform immediately after publishing them in order to determine whether they should be removed.
  • High-impact items – You can send items that have become extremely popular to the platform in order to verify whether they are violative and should be removed.
  • Just violation detection – If you have your own in-house platform, you can send items to the platform for violation detection and then handle the results yourselves.
  • A second opinion – If you're already sending your data to other risk score vendors, you can use the platform as yet another vendor for specific violations.
  • Orchestration – You can send your data to the platform in order to leverage its Automated Workflows and Moderation Views.
  • Getting more services – You can send the platform items that you have already detected as violative, so that the platform can use this information to provide various services, such as detecting repeat offenders or improving the platform's violation detection services.

Rate limit​

Projects has a rate limit for the amount of requests you can send per second. The default rate limit is 50 requests per second. You can reach out to your account manager to increase this rate limit.

When you are past the rate limit, your API requests will get a HTTP 429 response.

APIs​

Alice platform APIs enable you to send your content to the platform in order to get violation detections, risk scores, moderation insights and reports to be consumed by your software.

In this way, you can use the Alice APIs in the traditional request/response model, with or without the Alice platform UI. When using the Alice platform UI, the APIs can act as a gateway for sending your data to Alice. This data then appears in the Alice platform's UI (Moderation View) and in Automated Workflows.

APIs – How To​

Here's a list of the API types provided for sending your data to the platform –

The platform provides both synchronous endpoints and asynchronous endpoints. The data in the request and the response of both types is similar. The difference is the manner in which the response is sent.

  • The platform responds to synchronous endpoints in real time.
  • The platform responds to asynchronous endpoints by acknowledging the receipt of the request and then later sending a callback.
Synchronous APIs​

A synchronous endpoint is best suited for users who need realtime responses and require low latency. A synchronous endpoint keeps the HTTP request connection open until after it has completed processing and has sent the results in the response. Currently, text items and image items can be sent to the platform synchronously. For example, a chat message or an image post might require a realtime response from the platform in order to verify that it is not violative before it is published.

To execute a synchronous endpoint –

  1. If you have not done so yet, create an API key, as described in the Authentication section. Otherwise, you can use the API key that you created previously.
  2. Send a request to the platform, while using the API key in the alice-api-key header of the request. The platform immediately sends back the violation detections and risk scores. See Text API – synchronous or Image API – synchronous for the syntax of the request.
Asynchronous APIs​

The Asynchronous API enables you to send data to the platform and to later get a response as a callback.

To execute an asynchronous endpoint –

  1. If you have not done so yet, create an API key, as described in the Authentication section. Otherwise, you can use the API key that you created previously.
  2. Configure your callback endpoint in the platform as described in Callbacks.
  3. Send a request while using the API key in the alice-api-key header of the API request that you send to the platform. The platform immediately sends back an acknowledgement upon receiving a request and later sends the result to your callback endpoint. See the following for the syntax of the requests –

Action Webhooks​

In the Alice platform, you can define action webhooks that enable you to trigger actions on your own platform or on any other third-party system.

These action webhooks can be triggered by you at the click of a button in the platform Moderation View or by an Automated Workflow that you define.

You must make sure that a relevant API is defined on your platform or on the third-party platform that will execute the action upon receiving the action webhook from the Alice platform.

Action Webhooks – How To​

In the Alice platform, you can define action webhooks that enable you to activate actions on your platform or on any other third-party system. These action webhooks can be triggered by you at the click of a button in the Alice platform Moderation View or by an Automated Workflow that you define.

  • Actions on your platform – The Alice platform action webhooks can trigger actions on your platform, such as removing content, suspending a user, removing a user, warning a user and so on. You must define an API on your platform (for each action webhook) that will execute the relevant action upon receiving the action webhook request from the Alice platform.
  • Actions on third-party platforms – The Alice platform action webhooks can trigger actions on third-party applications, such as ZenDesk. You must ensure that the relevant API exists on the third-party application that will execute the relevant action upon receiving the action webhook request from the Alice platform.

You can customize Moderation Views and the action buttons that they contain, as well as Automated Workflows according to your organization's preferences and requirements.

Callbacks​

A callback is a notification sent by the Alice platform in response to an asynchronous API request sent by your platform.

The Alice platform will send a callback to the endpoint of your choice after the Alice platform has completed processing the request sent in an asynchronous API.

For example, after your platform sends an asynchronous text request, the Alice platform returns an analysis result callback containing the list of violations that were detected for that text.

Important Note

Terror, Hate Speech and Child Abuse violations take longer to process. To avoid waiting for the results of each of these types of violations, a separate callback is sent by the Alice platform for each of these violations after the process completes for a text, image and/or audio API.

A separate callback may be sent in response to a video API for each type of violation.

This means that multiple callbacks may be triggered in response to a single request. Each callback contains the risk score for one or more violations and considers all relevant media fields (texts/images and so on) sent in the request.

You may refer to the documentation of each API for a description of the fields that are analyzed for each API.

The list of the violations with which this callback is associated is in the analyzed_violations field.

A callback is triggered even when no violation is found (risk score is 0, or no relevant fields exist in the request for a violation) so that you can track when the processing of this item has finished.

How to define a Callback​

To define the callback endpoint –

When sending an asynchronous request, set the callback_url field to your endpoint. Alice will call this endpoint once processing is done, or for error reporting.

Note - This field is not mandatory. In case it is not used, the request would still be processed, only a callback won't be called by Alice.

Callback Authentication

You have the option to add an API key to a callback request's header or query params. To do so, assign the name of a key that you defined in the platform's Key Management section to callback_key_name. This key is then added as the API key in the callback request's header or query params.

Key Management​

The Key Management option enables you to create API keys that you can use to interact programmatically with Alice platform. In addition, they can be used by the platform to send action webhook notifications or callbacks to your platform, such as a notification to remove a post from your platform.

To define an API key –

  1. Click the Account Settings button.

  2. Select DATA MANAGEMENT, and then select Key Management.

    A list of the API keys that have already been defined is displayed.

  3. Click the Add Key button.

  4. Define the API key by filling out the following fields –

  • Key Name – Enter any free text to identify the key.
  • Description – Enter a free text description of the purpose of this key.
  • Key – Enter any free-text as the key name. Spaces or periods (.) are not permitted. Underscores (_) and dashes (-) are permitted.
  • Value – Enter the value for this key. For security reasons, once you save the API key, you will no longer be able to display it here, but you can always regenerate another API key.
  • Add To – Select Header or Query Params to specify where the key will be inserted in the request.
  1. Click the Save button.

Custom Fields​

By default, the Alice platform is provided with a wide variety of fields to describe your items.

The Alice platform also enables you to add your own fields by defining the title, key and type of each Custom Field to be added to your account. These Custom Fields then appear throughout the platform, such as in the Moderation Views and Automated Workflows.

For example, you might define a new Custom Field named Subscription, which can have one of the following values – Premium, Basic or Free.

By defining these Custom Fields in the Alice platform, the request structure of the API requests that you can send to the Alice platform is automatically modified to accept these Custom Fields according to your definitions. You can immediately start sending values in these new fields.

To define Custom Fields –

  1. Click the Account Settings button.

  2. Select MODERATION CAPABILITIES and then select Custom Fields.

  3. Click the Add Field button.

  4. Click on the COLLECTED or EDITABLE option and then the Next button to specify that the values of these fields will be received by the Alice platform from your platform via API request or direct upload.

  5. In the Title field, enter any free-text name. This name appears as the name of this Custom Field and as title of this field's column in the Moderation View. This field can include spaces.

  6. In the Key field, enter any free text name for this key. This name appears as the name of this field in an API request to the platform. Spaces or periods (.) are not permitted. Underscores (_) and dashes (-) are permitted.

  7. From the Type dropdown menu, select the data type of the Custom Field, which can be Text, Number, Boolean, Date or Dropdown.

    Note – The data type of fields sent to the Alice platform in a Custom Field will be verified and if incorrect, an error is generated.

    Later, in the Moderation View, the Alice platform will validate the data type that a moderator can enter for this field. The platform will also validate data type received in API requests accordingly.

  8. Click the Finish button.

  9. You can now push data to the Alice platform.

The following is an example of an API request that sends an image to the platform.

animal_type, age, is_adopted, adoption_date and habitat are the key names of the Custom Fields and Persian cat, 3, true, 2015-11-25 and Urban, Coastal are the values accordingly.

When this request will be received by the platform, it will validate the data type (Text, Number, Boolean, Date or Dropdown) in each Custom Field.

Valid formats:

Text : Free text.

Number : Any number including floating number.

Boolean : true / false.

Date: "MM-DD-YYYY" , "YYYY-MM-DD" , "MM-DD-YYYY HH:MM" , "YYYY-MM-DD HH:MM".

Dropdown: A single string or an Array of strings - ["str1", "str2"].

Request example:

"custom_fields" : [ {"animal_type": "Persian cat"}, {"age": 3}, {"is_adopted": true}, {"adoption_date" : "2015-11-25"}, {"habitat" : ["Urban","Coastal"]} or {"habitat" : "Urban"} ]

These fields are now part of each item, so that they may appear in each row (item) in a Moderation View, if the Moderation View is defined to include them.

Note – Defining Editable fields by selecting Editable in the Choose custom field type window (described above) enables moderators to enter these item values in a Moderation View. Editable fields can also be populated by API requests using the custom fields.

Authentication​

API Key for authentication

Security Scheme Type:

apiKey

Header parameter name:

alice-api-key

Contact

Support: support@alice.io