NAV Navbar
Logo
shell

Introduction

Welcome to Spectrum’s API documentation. Here, you’ll find everything you need to know to get started building apps on top of our content moderation platform. Note that this page is geared toward software developers. If you aren’t a software developer or are looking for general help with Spectrum’s platform, check out our Help Center or contact us for support.

Our API uses a combination of RPC and REST-ful endpoints to facilitate different features. See the documentation for each endpoint to determine if the endpoint uses RPC or REST.

The API’s root URL is https://api.prod.getspectrum.io. We version all of our API endpoints by following a loose interpretation of Semantic Versioning. Breaking changes will result in a new API version. Clients should be tolerant of additive changes.

Authentication

curl "api_endpoint" -h "Authorization: Apikey your_api_key"

You’ll need an API key to access our API. See the Help Center for instructions on how to create one. To authenticate with our API, pass the API key like this in the Authorization header:

Authorization: Apikey testing123

Content Classification

Our content classification service exists at /api/v1/classification. We currently support the following classifiers:

  1. Toxicity
  2. Sexual Content (internal beta)
  3. Phishing Attacks (internal beta)

Additional classifications are currently planned for the near future. Please contact us if you have specific needs.

This is a JSON-RPC service. See the JSON-RPC API 2.0 Specification for a complete description of the JSON-RPC 2.0 protocol.

Meta Objects

You can optionally pass a meta parameter to any classification method. The meta parameter allows API clients to send additional data alongside the text to be classified for use in their Spectrum dashboard or as part of any internal services listening for incoming webhooks. The meta parameter is an object that may contain any number of the following fields:

Parameter Type Description
authorId string The ID of the user who created the content.
authorName string The name of the user who created the content.
authorEmail string The e-mail of the user who created the content.
authorIpAddress string The IP address of the user who created the content.
streamId string The ID of the stream that the user posted the content into.
streamName string The name of the stream that the user posted the content into.
remoteId string The ID of the content on whatever remote system it resides.

If you’re worried about data privacy, the fields in the meta object can be hashed, encrypted, or obfuscated prior to being sent to our servers.

classifyText

curl -X POST \
  https://api.prod.getspectrum.io/api/v1/classification \
  -d '{
   "jsonrpc": "2.0",
   "method": "classifyText",
   "params": { 
        "text": "this text is toxic",
        "meta": { "authorId": "123" }
    },
   "id": 1
}'

The above command will return the following JSON:

{
   "jsonrpc": "2.0",
   "result": {
    "toxic": true,
    "toxicityConfidence": 0.86,
    "sexual": false,
    "sexualConfidence": 0.23
   },
   "id": 1
}

This method will return classifications for the content provided in the text parameter. The text parameter is limited in size to 15MB.

Method Parameters

Parameter Optional Default Description
text NO N/A The text to analyze.

recordUserClassification

curl -X POST \
  https://api.prod.getspectrum.io/api/v1/classification \
  -d '{
   "jsonrpc": "2.0",
   "method": "recordUserClassification",
   "params": { "content": "this content is garbage", "shouldBlock": true }
}'

This API method is a notification as per the JSON-RPC spec. If an ID is passed in the request payload, the string OK will be returned by the server.

This method is used to ingest correct classifications from external systems. For example, Spectrum’s WordPress plugin calls this method when users change the moderation status of a comment. Content ingested from this method is validated and used to better train our algorithms.

Method Parameters

Parameter Optional Default Description
content NO N/A The text content of the classification.
shouldBlock NO N/A Whether Spectrum should have blocked the content.

Error Codes

This method does not have any explicit error codes.

Webhooks

Webhooks are a simple way to get notified when Spectrum classifies certain content. For example, you could configure a webhook that will be called whenever Spectrum classifies something as toxic. Spectrum will make a POST request with a JSON body to each enabled webhook.

For the security-conscious, webhooks can be configured to send an HTTP Basic authentication header with each request.

Webhooks are created from our web UI. To test our webhooks, we suggest using a tool such as ngrok or RequestBin.

We send classifications and all provided metadata with each Webhook request. The following is an example Webhook payload:

{  
   "type": "CLASSIFICATION",
   "toxic": true,
   "toxicityConfidence": 0.9996266447109696,
   "meta": {  
      "authorName": "test",
      "authorId": "123",
      "authorEmail": "test@example.com",
      "authorIpAddress": "127.0.0.1",
      "streamName": "hello",
      "streamId": "hello",
      "remoteId": "hello",
      "avatarUrl": "https://www.google.com",
      "remoteCreatedAt": 1509570919000
   }
}
shell